Basware ExportedContracts API

openapi: 3.2.0
info:
  title: Basware OAUTH2 authentication APIs AccountingDocuments Exported Contracts API
  description: "**Using OAUTH2.0 authentication:**\n\nGet API access token from api.basware.com/tokens\n1. Using client id and client secret, which you can obtain from Basware. \n2. Specify which APIs can be accessed by using the token e.g. Read only access to vendors API only (these are called scopes). Available scopes are listed at <https://developer.basware.com/api/p2p/manual#AccessRights>. \n3. Each token has an expiration time, until which it can be used to call APIs.\n\nWhen using OAUTH2 authentication, you need to pass the OAUTH2 authentication token when calling Basware API endpoints. Available Basware API operations are documented at <https://api.basware.com/swagger>. \n\nSee the Basware API developer site at <https://developer.basware.com/api/p2p/manual#Authentication> for more details on API authentication."
  version: 1.0.0
  x-logo:
    url: https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png
servers:
- url: https://api.basware.com
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: ExportedContracts
paths:
  /v1/exportedContracts:
    get:
      tags:
      - ExportedContracts
      summary: Returns contracts (along with spend totals) exported from Basware P2P.
      description: "Notes: \n1) Whether contract spends are collected is controlled by the fields 'invoiceSpend', 'orderSpend' and 'spendPlanSpend'. Spend is not collected when these fields are set to 'false'.\n2) This API supports sending webhook based  [push notifications](https://developer.basware.com/api/p2p/manual#PushNotifications) when new data is available to be exported. \n3) This API exports contracts imported through Basware API. Contracts imported through anyerp are not exported. \n\nPlease see section \"[Usage scenario 4: Import and export procurement data](https://developer.basware.com/api/p2p/manual#usage4)\" for details on implementing this API. Check out also the [example JSONs using a minimal feasible set of fields](https://developer.basware.com/api/p2p/templates) from the developer site."
      parameters:
      - name: processingStatus
        in: query
        description: Document status filter. Returns records by document status. Use 'WaitingForExport' to retrieve unacknowledged records.
        schema:
          enum:
          - WaitingForExport
          - Exported
          type: string
      - name: pageSize
        in: query
        description: A limit for the number of items to be returned for one request. Limit can range between 1 and 500 items.
        schema:
          type: integer
          format: int32
          default: 200
      - name: companyCode
        in: query
        description: Company filter. Returns items for specific company.
        schema:
          type: string
          default: ''
      - name: lastUpdated
        in: query
        description: Date Filter. Returns items that have been updated after specified date.
        schema:
          type: string
          format: date-time
      - name: x-amz-meta-continuationtoken
        in: header
        description: Used to get next page of results when item count indicated by 'pageSize' is exceeded. A token is returned in header (not body) parameter 'X-amz-meta-continuationToken' of the response whenever there are more records to fetch. Post the received value here in a new HEADER parameter on the next GET request to receive the next page of results. When getting the next page of results, you must include the same query parameters that were used when getting the first page.
        schema:
          type: string
        example: 6724c88a-3a53-4a08-a3a8-c2a05c5e42f8
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ExportedContractsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ExportedContractsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ExportedContractsResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '500':
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
    delete:
      tags:
      - ExportedContracts
      summary: Deletes data from Basware API. For manual one-time operations.
      description: "For manual one-time operations only, such as a manual clean-up to remove test data generated during API integration development. Only removes records from API layer. \nDeletion in target systems needs to be done separately using the data deletion mechanisms available in each of the target system in addition to deleting the data in Basware API."
      requestBody:
        description: "Contains the body of the request.\n            Either externalCode or lastUpdated -field is required. If both values are provided, externalCode will have the priority."
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/DeleteRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '202':
          description: RequestAccepted
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: BadRequest
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '500':
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
  /v1/exportedContracts/{externalCode}:
    get:
      tags:
      - ExportedContracts
      summary: Returns contracts (along with spend totals) exported from Basware P2P by externalCode.
      description: "Notes: \n1) Whether contract spends are collected is controlled by the fields 'invoiceSpend', 'orderSpend' and 'spendPlanSpend'. Spend is not collected when these fields are set to 'false'.\n2) This API exports contracts imported through Basware API. Contracts imported through anyerp are not exported. \n\nPlease see section \"[Usage scenario 4: Import and export procurement data](https://developer.basware.com/api/p2p/manual#usage4)\" for details on implementing this API. Check out also the [example JSONs using a minimal feasible set of fields](https://developer.basware.com/api/p2p/templates) from the developer site."
      parameters:
      - name: externalCode
        in: path
        description: The ExternalCode of the contract to be fetched.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ExportedContractsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ExportedContractsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ExportedContractsResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '404':
          description: Not found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
        '500':
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityList'
  /v1/exportedContracts/acknowledge:
    post:
      tags:
      - ExportedContracts
      summary: Acknowledged contract spends are no longer returned on the next GET operation.
      description: "Notes: \n1) Updates 'processingStatus' -field on the document to allow filtering out already acknowledged documents on the next GET operation. \n2) For a document which is already acknowledged (processingStatus: 'Exported'), API will return 405 'Method not allowed' if acknowledge is attempted again on the document."
      parameters:
      - name: Content-Type
        in: header
        description: Specifies the media type of the resource. Value application/json is supported.
        schema:
          type: string
        example: application/json
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: string
            text/json:
              schema:
                type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '405':
          description: Method not allowed. This generally happens when trying to acknowledge an exportedContract that is already acknowledged.
        '500':
          description: Unexpected error
components:
  schemas:
    ExportedContractSpendTotal:
      type: object
      properties:
        documentType:
          enum:
          - AccountingDocument
          - PurchaseOrder
          - SpendPlan
          type: string
          description: Specifies the type of document for which sums of projected / spent amounts are stated.
          example: AccountingDocument
        netSumContract:
          type: number
          description: Net sum of spends in the currency of the contract.
          format: double
          example: 2000
        grossSumContract:
          type: number
          description: Gross sum of spends in the currency of the contract.
          format: double
          example: 2480
        currencyCodeContract:
          type:
          - string
          - 'null'
          description: Currency code of the contract.
          example: EUR
        netSumCompany:
          type: number
          description: Net sum of spends in the currency of the company.
          format: double
          example: 10230
        grossSumcompany:
          type: number
          description: Gross sum of spends in the currency of the company.
          format: double
          example: 12685.2
        currencyCodecompany:
          maxLength: 3
          minLength: 2
          type:
          - string
          - 'null'
          description: Currency code of the company.
          example: SEK
        netSumOrganization:
          type: number
          description: Net sum of spends in the currency of the Organization.
          format: double
          example: 1680
        grossSumOrganization:
          type: number
          description: Gross sum of spends in the currency of the Organization.
          format: double
          example: 2291.52
        currencyCodeOrganization:
          maxLength: 3
          minLength: 2
          type:
          - string
          - 'null'
          description: Currency code of the Organization.
          example: GBP
      additionalProperties: false
    AcknowledgeRequest:
      type: object
      properties:
        lastUpdated:
          type:
          - string
          - 'null'
          description: Records with lastUpdated -timestamp after the specified value are acknowledged. '0001-01-01' can be used as input value to acknowledge all records.
          format: date-time
          example: '2022-01-01'
        externalCodes:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of requestIds to acknowledge. Several requests can be acknowledged in one operation.
      additionalProperties: false
    DeleteRequest:
      type: object
      properties:
        lastUpdated:
          type:
          - string
          - 'null'
          description: 'To delete records updated after specific time, use lastUpdated -field. This will delete all items that have been updated after the specified date. In response, user will get the taskStatus api link where the task status can be checked. Note: ''0001-01-01'' can be used to delete all records.'
          format: date-time
        externalCode:
          maxLength: 36
          minLength: 0
          type:
          - string
          - 'null'
          description: Single item can be deleted using externalCode and final status is returned immediately.
      additionalProperties: false
    ResponseEntityList:
      type: object
      properties:
        requestId:
          type:
          - string
          - 'null'
          description: ID of the request on which error occurred (generated by Basware API).
          example: fbc082a2-65a4-469c-b230-d84a252f18fc
        hasErrors:
          type: boolean
          description: Specifies whether the request has errors.
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ErrorEntity'
      additionalProperties: false
      description: Errors returned here are returned synchronously from Basware API middle layer. Additional errors coming from target system(s) may be returned through errorFeedbacks API.
    ExportedContractSupplier:
      required:
      - supplierCode
      type: object
      properties:
        supplierCode:
          maxLength: 25
          minLength: 1
          type: string
          description: Code of the supplier on the contract
          example: '32789'
        supplierName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Acme Motor Leasing inc.
          example: '32789'
      additionalProperties: false
    ExportedContractEntity:
      required:
      - active
      - companyCode
      - currencyCode
      - externalCode
      - owner
      - referenceCode
      - suppliers
      - title
      - total
      - validFrom
      - validTo
      type: object
      properties:
        externalCode:
          maxLength: 100
          minLength: 1
          type: string
          description: External identifier that is used as a key in API.
          example: 4847-31231212-212121-1212
        referenceCode:
          maxLength: 255
          minLength: 1
          type: string
          description: FreeText Reference shown in contracts view (Contract Number)
          example: '12197627'
        processingStatus:
          enum:
          - WaitingForExport
          - Exported
          type: string
          description: Processing status of the contract spend in Basware API. Use 'WaitingForExport' to get unacknowledged records.
          example: WaitingForExport
        companyCode:
          maxLength: 25
          minLength: 1
          type: string
          description: Buyer Company Code
          example: '200'
        companyName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Buyer Company Name
          example: Acme Motor leasinc inc.
        title:
          maxLength: 250
          minLength: 1
          type: string
          description: A short name generally used to identify the contract in reporting
          example: Car Leasing
        description:
          maxLength: 2000
          minLength: 0
          type:
          - string
          - 'null'
          description: General information on contract
          example: This contract is for car leasing for Acme Motor leasing inc.
        type:
          maxLength: 100
          minLength: 1
          type:
          - string
          - 'null'
          description: Determined by the contract management system. Types are displayed only for informational purposes
          example: ''
        validFrom:
          type: string
          description: The date on which the contract legally came in to force
          format: date-time
          example: '2021-01-01'
        validTo:
          type: string
          description: The date on which the contract will naturally end if not active decisions are made to extend or terminate early
          format: date-time
          example: '2023-12-31'
        total:
          type: number
          description: Total expected expenditure under this contract between the Start and End Dates specified above
          format: double
          example: 10000
        amountType:
          enum:
          - Net
          - Gross
          type: string
          description: net or gross
          example: '12197627'
        currencyCode:
          maxLength: 3
          minLength: 2
          type: string
          description: Currency for the total value
          example: EUR
        paymentTermCode:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Payment term for this contract
          example: NET30
        owner:
          maxLength: 100
          minLength: 1
          type: string
          description: The person owning the contract
          example: Liz Black
        contactPerson:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: The person to contact on contract matters
          example: Liz Black
        active:
          type: boolean
          description: States if the contract can be used or not
          example: true
        suppliers:
          type: array
          items:
            $ref: '#/components/schemas/ExportedContractSupplier'
          description: Suppliers for contract
        externalLinks:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExportedContractExternalLink'
          description: ExternalLinks for contract
        spendTotals:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExportedContractSpendTotal'
          description: "Aggregate sums of all projected / spent amounts per document type. \n1) For 'AccountingDocument', this is the actual total spend. The spend is from invoices which are transferred to accounting (documents in circulation are not included). All invoices linked to the contract are included, whether PO, non-PO, or payment plan matched invoices. \n2) For 'PurchaseOrder', this is the projected total spend. Included are all purchaseOrders in P2P Purchase, which are sent to supplier and linked to the contract. It does not matter whether the orders have been invoiced or not. Spend from matching orders is not included. \n3) For 'SpendPlan', this is the projected total spend. Included are all active spend plans. The spend from a spend plan gets added the moment the spend plan is activated. It does not matter if the spend plan has received any invoices or not. \nNote: The individual spend events can be accessed through exportedContractSpends API by providing the externalCode of the contract and optionally the document type."
        orderSpend:
          type: boolean
          description: States if spend of orders using this contract is collected for spend reporting.
          example: true
        spendPlanSpend:
          type: boolean
          description: States if spend of spend plans using this contract is collected for spend reporting.
          example: true
        invoiceSpend:
          type: boolean
          description: States if spend of invoices using this contract is collected for spend reporting.
          example: true
        lastUpdated:
          type: string
          description: Timestamp when the record was last sent to API. Set automatically.
          format: date-time
      additionalProperties: false
    ErrorEntity:
      type: object
      properties:
        externalCode:
          type:
          - string
          - 'null'
          description: External code of record on which error occurred (when available).
          example: 4847-31231212-212121-1212
        type:
          enum:
          - BUSINESS
          - VALIDATION
          - TECHNICAL
          - SECURITY
          type: string
          description: Error type.
          example: ''
        code:
          enum:
          - EXTERNAL_CODE_MISMATCH
          - SCHEMA_VALIDATION_ERROR
          - CONFLICT_IN_POST
          - DATA_ORIGIN_VALIDATION_ERROR
          - ACCESS_TOKEN_VALIDATION_ERROR
          - CREDENTIAL_VALIDATION_ERROR
          - PARAMETER_VALIDATION_ERROR
          - UNEXPECTED_ERROR
          - METHOD_NOT_ALLOWED
          - ENTITY_NOT_FOUND
          - DATA_VALIDATION_FAILED
          - SNS_PUBLISH_ERROR
          - SQS_PUBLISH_ERROR
          type: string
          description: Error code.
          example: ''
        message:
          type:
          - string
          - 'null'
          description: Specific error message.
          example: ''
        info:
          type:
          - string
          - 'null'
          description: Information about type of the error.
          example: ''
      additionalProperties: false
    DeleteResponse:
      type: object
      properties:
        statusApiLink:
          type:
          - string
          - 'null'
        taskName:
          type:
          - string
          - 'null'
        taskStatus:
          type:
          - string
          - 'null'
      additionalProperties: false
    ExportedContractsResponse:
      required:
      - contracts
      type: object
      properties:
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/ExportedContractEntity'
      additionalProperties: false
    ExportedContractExternalLink:
      required:
      - externalLinkName
      type: object
      properties:
        externalLinkName:
          maxLength: 512
          minLength: 1
          type: string
          description: Name shown in UI for external link
          example: Acme motor leasing
        externalLinkURL:
          maxLength: 2000
          minLength: 1
          type:
          - string
          - 'null'
          description: URL used when selecting external link
          example: https://www.acmemotorsinc.com
      additionalProperties: false
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic