Basware ExportedContractSpends API

openapi: 3.2.0
info:
  title: Basware APIs for Purchase-to-Pay and Master Data import…
  description: The Basware APIs documented here are for Purchase-to-Pay use cases and for importing Master Data to Basware services.
  version: v1
servers:
- url: ''
security:
- Bearer: []
- oauth2authentication: []
tags:
- name: ExportedContractSpends
paths:
  /v1/exportedContractSpends:
    get:
      tags:
      - ExportedContractSpends
      summary: Returns contract spends exported from Basware P2P
      description: 'Notes:

        1) 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''.

        2) This API supports sending webhook based push notifications when new data is available to be exported.

        3) This API exports spends for contracts imported through Basware API. Spend is not exported for contracts imported through anyerp.


        Please see section "Usage scenario 4: Import and export procurement data" for details on implementing this API. Check out also the example JSONs using a minimal feasible set of fields 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: documentType
        in: query
        description: Document type filter. Returns items for specific document type.
        schema:
          enum:
          - AccountingDocument
          - PurchaseOrder
          - SpendPlan
          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: 500
      - name: contractExternalCode
        in: query
        description: Contract code filter. Returns items for specific contract.
        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: 4e1c0aa1-5478-4396-a6c1-4fd816030924
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ExportedContractSpendsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ExportedContractSpendsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ExportedContractSpendsResponse'
        '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'
      operationId: getV1ExportedContractSpends
      x-operation-id-source: derived
    delete:
      tags:
      - ExportedContractSpends
      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.

        Deletion 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'
      operationId: deleteV1ExportedContractSpends
      x-operation-id-source: derived
  /v1/exportedContractSpends/{externalCode}:
    get:
      tags:
      - ExportedContractSpends
      summary: Returns contract spend details exported from Basware P2P by externalCode
      description: 'Notes:

        1) 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''.

        2) This API exports spends for contracts imported through Basware API. Spend is not exported for contracts imported through anyerp.


        Please see section "Usage scenario 4: Import and export procurement data" for details on implementing this API. Check out also the example JSONs using a minimal feasible set of fields from the developer site.'
      parameters:
      - name: externalCode
        in: path
        description: The ExternalCode of the ContractSpend to be fetched.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ExportedContractSpendsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ExportedContractSpendsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ExportedContractSpendsResponse'
        '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'
      operationId: getV1ExportedContractSpendsByExternalCode
      x-operation-id-source: derived
  /v1/exportedContractSpends/acknowledge:
    post:
      tags:
      - ExportedContractSpends
      summary: Acknowledged contract spends are no longer returned on the next GET operation
      description: 'Notes:

        1) Updates ''processingStatus'' -field on the document to allow filtering out already acknowledged documents on the next GET operation.

        2) For a document which is already acknowledged (processingStatus: ''Exported''), API will return 405 ''Method not allowed'' if acknowledge is attempted again on the document.


        Please see section "Usage scenario 4: Import and export procurement data" for details on implementing this API. Check out also the example JSONs using a minimal feasible set of fields from the developer site.'
      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/ContractSpendAcknowledgeRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/ContractSpendAcknowledgeRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ContractSpendAcknowledgeRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ContractSpendAcknowledgeRequest'
      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 exportedContractSpend that is already acknowledged.
        '500':
          description: Unexpected error
      operationId: postV1ExportedContractSpendsAcknowledge
      x-operation-id-source: derived
components:
  schemas:
    ExportedContractSpendEntity:
      required:
      - contractNumber
      - externalCode
      - processingStatus
      type: object
      properties:
        externalCode:
          maxLength: 100
          minLength: 1
          type: string
          description: External identifier that is used as a key in API to identify the contract spend.
          example: 4847-31231212-212121-1212
        processingStatus:
          enum:
          - WaitingForExport
          - Exported
          type: string
          description: Processing status of the contract spend in Basware API. Use 'WaitingForExport' to get unacknowledged records.
          example: WaitingForExport
        contractNumber:
          maxLength: 255
          minLength: 1
          type: string
          description: Contract number in P2P.
          example: '2125400'
        contractExternalCode:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: External identifier that is used as a key in API for the contract to which this spend belongs. The contract can be found using this code from exportedContracts API.
          example: 4847-31231212-565656-3344
        companyCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Buyer Company Code
          example: '200'
        companyName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Buyer Company Name
          example: Basware Oyj
        supplierCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Code of the supplier in the contract spend event.
          example: '25365'
        supplierName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Name of the supplier in the contract spend event.
          example: Acme Motor Leasing inc.
        documentType:
          enum:
          - AccountingDocument
          - PurchaseOrder
          - SpendPlan
          type: string
          description: "Type of the spend source document. \n1) AccountingDocument = An approved invoice transferred to accounting (available trough accountingDocuments API). Spend is exported when the invoice is transferred to accounting. \n2) PurchaseOrder = An order created in or imported to P2P Purchase, which is sent to supplier (available from exportedPurchaseOrders API when export is enabled). \nNote: Spend is updated whenever the order is updated. \n3) SpendPlan = Spend plan created in P2P. Spend is exported when Spend plan is activated in P2P and removed if the spend plan is deactivated. SpendPlans are not available through Basware API. Note: When using spendPlans or PurchaseOrders, the spend is exported twice - first on the spendplan/PO and second on the invoice. Spend of PurchaseOrders and SpendPlans are considered as spend reservations and invoice spend as the actual spend."
          example: WaitingForExport
        documentExternalCode:
          maxLength: 100
          minLength: 1
          type:
          - string
          - 'null'
          description: External identifier of the spend source document. This can be used to fetch the document from accountingDocuments API (by invoiceId) or exportedPurchaseOrders API (by externalCode).
          example: 138e7d94997847aebe7432e521b3dac9
        documentNumber:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: DocumentNumber of the spend source document, ie. Invoice number, order number, spend plan reference. Corresponds to 'invoiceNumber' in accountingDocuments API or to 'orderNumber' in exportedPurchaseOrders API.
          example: '80000330200233'
        netSumDocument:
          type: number
          description: Net currency amount spent on this contract on the spend source document, indicated in currency of the spend source document.
          format: double
          example: 150
        grossSumDocument:
          type: number
          description: Gross currency amount spent on this contract on the spend source document, indicated in currency of the spend source document.
          format: double
          example: 250
        currencyCodeDocument:
          maxLength: 3
          minLength: 2
          type:
          - string
          - 'null'
          description: Currency of the spend source document.
          example: EUR
        netSumContract:
          type: number
          description: Net currency amount spent on the spend document, indicated in currency of the contract.
          format: double
          example: 150
        grossSumContract:
          type: number
          description: Gross currency amount spent on the spend document, indicated in currency of the contract.
          format: double
          example: 250
        currencyCodeContract:
          maxLength: 3
          minLength: 2
          type:
          - string
          - 'null'
          description: Currency of the contract.
          example: EUR
        netSumCompany:
          type: number
          description: Net currency amount spent on the spend document, indicated in currency of the byuer company.
          format: double
          example: 1534.5
        grossSumCompany:
          type: number
          description: Gross currency amount spent on the spend document, indicated in currency of the buyer company.
          format: double
          example: 1902.16
        currencyCodeCompany:
          maxLength: 3
          minLength: 2
          type:
          - string
          - 'null'
          description: Currency of the buyer company.
          example: Liz Black
        netSumOrganization:
          type: number
          description: Net currency amount spent on the spend document, indicated in currency of the byuer organization.
          format: double
          example: 126
        grossSumOrganization:
          type: number
          description: Gross currency amount spent on the spend document, indicated in currency of the buyer organization.
          format: double
          example: 156.2
        currencyCodeOrganization:
          maxLength: 3
          minLength: 2
          type:
          - string
          - 'null'
          description: Currency of the buyer organization.
          example: GBP
        isCancelled:
          type: boolean
          description: Indicates whether the spend is cancelled. An existing spend may be cancelled for example when wrong contract was linked to a document.
          example: false
        lastUpdated:
          type: string
          description: Timestamp when the record was last sent to API. Set automatically.
          format: date-time
      additionalProperties: false
      description: Contains details on indivisual spend events. Note that a spend event can contain just a part of the whole amount indicated on spend source document, such as when part of the invoice lines correspond to a contract.
    ExportedContractSpendsResponse:
      required:
      - contractSpends
      type: object
      properties:
        contractSpends:
          type: array
          items:
            $ref: '#/components/schemas/ExportedContractSpendEntity'
      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
    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
    DeleteResponse:
      type: object
      properties:
        statusApiLink:
          type:
          - string
          - 'null'
        taskName:
          type:
          - string
          - 'null'
        taskStatus:
          type:
          - string
          - 'null'
      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.
    ContractSpendAcknowledgeRequest:
      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
  securitySchemes:
    Bearer:
      type: http
      description: Please insert basic authentication credentials into fields
      scheme: basic
    oauth2authentication:
      type: oauth2
      description: Oauth2 client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.basware.com/v1/tokens
          scopes:
            accountingDocuments.read: GET accountingDocuments
            accountingDocuments.write: POST/PATCH accountingDocuments
            accountingDocuments.delete: DELETE accountingDocuments
            accounts.read: GET accounts
            accounts.write: POST/PATCH accounts
            accounts.delete: DELETE accounts
            advancedPermissions.read: GET advancedPermissions
            advancedPermissions.write: POST/PATCH advancedPermissions
            advancedPermissions.delete: DELETE advancedPermissions
            advancedValidations.read: GET advancedValidations
            advancedValidations.write: POST/PATCH advancedValidations
            advancedValidations.delete: DELETE advancedValidations
            applicationGroups.read: GET applicationGroups
            applicationGroups.write: POST/PATCH applicationGroups
            companies.read: GET companies
            companies.write: POST/PATCH companies
            contracts.delete: DELETE contracts
            contracts.read: GET contracts
            contracts.write: POST/PATCH contracts
            costCenters.read: GET costCenters
            costCenters.write: POST/PATCH costCenters
            costCenters.delete: DELETE costCenters
            errorFeedbacks.read: GET errorFeedbacks
            errorFeedbacks.write: POST/PATCH errorFeedbacks
            errorFeedbacks.delete: DELETE errorFeedbacks
            exchangeRates.read: GET exchangeRates
            exchangeRates.write: POST/PATCH exchangeRates
            exchangeRates.delete: DELETE exchangeRates
            exportedContracts.read: GET exportedContracts
            exportedContracts.write: POST/PATCH exportedContracts
            exportedContracts.delete: DELETE exportedContracts
            exportedContractSpends.read: GET exportedContractSpends
            exportedContractSpends.write: POST/PATCH exportedContractSpends
            exportedContractSpends.delete: DELETE exportedContractSpends
            exportedPurchaseOrders.read: GET exportedPurchaseOrders
            exportedPurchaseOrders.write: POST/PATCH exportedPurchaseOrders
            exportedPurchaseOrders.delete: DELETE exportedPurchaseOrders
            exportedPurchaseRequisitions.read: GET exportedPurchaseRequisitions
            exportedPurchaseRequisitions.write: POST/PATCH exportedPurchaseRequisitions
            exportedPurchaseRequisitions.delete: DELETE exportedPurchaseRequisitions
            lists.read: GET lists
            lists.write: POST/PATCH lists
            lists.delete: DELETE lists
            matchingOrders.read: GET matchingOrders
            matchingOrders.write: POST/PATCH matchingOrders
            matchingOrders.delete: DELETE matchingOrders
            matchingOrderLines.read: GET matchingOrderLines
            matchingOrderLines.write: POST/PATCH matchingOrderLines
            matchingOrderLines.delete: DELETE matchingOrderLines
            paymentTerms.read: GET paymentTerms
            paymentTerms.write: POST/PATCH paymentTerms
            paymentTerms.delete: DELETE paymentTerms
            projects.read: GET projects
            projects.write: POST/PATCH projects
            projects.delete: DELETE projects
            purchaseOrders.read: GET purchaseOrders
            purchaseOrders.write: POST/PATCH purchaseOrders
            purchaseOrders.delete: DELETE purchaseOrders
            purchaseRequisitions.read: GET purchaseRequisitions
            purchaseRequisitions.write: POST/PATCH purchaseRequisitions
            purchaseRequisitions.delete: DELETE purchaseRequisitions
            purchaseGoodsReceipts.read: GET purchaseGoodsReceipts
            purchaseGoodsReceipts.write: POST/PATCH purchaseGoodsReceipts
            purchaseGoodsReceipts.delete: DELETE purchaseGoodsReceipts
            requestStatus.read: GET requestStatus
            requestStatus.write: POST/PATCH requestStatus
            subscriptions.read: GET subscriptions
            subscriptions.write: POST/PATCH subscriptions
            subscriptions.delete: DELETE subscriptions
            tasks.read: GET tasks
            taskStatus.read: GET taskStatus
            taxCodes.read: GET taxCodes
            taxCodes.write: POST/PATCH taxCodes
            taxCodes.delete: DELETE taxCodes
            users.read: GET users
            users.write: POST/PATCH users
            users.delete: DELETE users
            vendors.read: GET vendors
            vendors.write: POST/PATCH vendors
            vendors.delete: DELETE vendors