Basware Request Status 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: Request Status
paths:
  /v1/requestStatus/{requestId}:
    get:
      tags:
      - Request Status
      summary: Returns request status responses from receiving end-system(s), based on request…
      description: 'Note: RequestStatus functionality is not yet available for ''users'' API for ''Basware network'' target system, which uses application codes ''SupplierPortal'' and ''SupplierManagement'').


        Please see section "Usage scenario 5: Error handling and monitoring" in Basware Purchase-to-Pay API manual for details on implementing error handling with Basware API.'
      parameters:
      - name: requestId
        in: path
        description: The request id used to post in the data. This is returned in request header parameter 'x-amzn-RequestId', in response of the original request.
        required: true
        schema:
          type: string
      - name: system
        in: query
        description: Allows limiting the responses to requests routed to a particular target system.
        schema:
          type: string
      - name: ignoreSuccessfulItems
        in: query
        description: Allows filtering out succesful records within the response. Can be used to show only records with errors and records in progress.
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '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: getV1RequestStatusByRequestId
      x-operation-id-source: derived
  /v1/requestStatus:
    get:
      tags:
      - Request Status
      summary: Returns request status responses from receiving end-system(s), based on status…
      description: 'Notes:

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

        2) RequestStatus functionality is not yet available for ''users'' API for ''Basware network'' target system, which uses application codes ''SupplierPortal'' and ''SupplierManagement'').


        Please see section "Usage scenario 5: Error handling and monitoring" in Basware Purchase-to-Pay API manual for details on implementing error handling with Basware API.'
      parameters:
      - name: status
        in: query
        description: Allows filtering requests by status. Defaults to status ‘Error’ if search is not narrowed-down by entityType or system.
        schema:
          enum:
          - InProgress
          - Success
          - Error
          - AcknowledgedSuccess
          - AcknowledgedError
          type: string
      - name: entityType
        in: query
        description: Allows filtering requests by EntityType.
        schema:
          enum:
          - Account
          - Contract
          - CostCenter
          - TaxCode
          - ExchangeRate
          - PaymentTerm
          - User
          - Project
          - MatchingOrder
          - MatchingOrderLine
          - GenericList
          - AdvancedPermission
          - TransferResponse
          - PaymentResponse
          - PrebookResponse
          - Vendor
          - AdvancedValidation
          - PurchaseRequisition
          - PurchaseOrder
          - PurchaseGoodsReceipt
          - Organization
          - EnrichmentTransferResponse
          - UserGroup
          - UserGroupAssociatedUser
          - UserGroupPermission
          type: string
      - name: ignoreSuccessfullItems
        in: query
        description: Allows filtering out succesful records within the response. Can be used to show only records with errors and records in progress.
        schema:
          type: boolean
      - name: system
        in: query
        description: Allows limiting the responses to requests routed to a particular target system.
        schema:
          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: 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: 273705a0-c35a-4fda-8f98-450705ac5e96
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/RequestStatusResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '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: getV1RequestStatus
      x-operation-id-source: derived
  /v1/requestStatus/acknowledge:
    post:
      tags:
      - Request Status
      summary: Acknowledged request status responses are no longer offered for next GET…
      description: 'Acknowledging will status from ''Success'' or ''Error'' to indicate the request has already been acknowledged. Please see section "Usage scenario 5: Error handling and monitoring" in Basware Purchase-to-Pay API manual for details on implementing error handling with Basware API.'
      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/ProcessingStatusGetBatchRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessingStatusGetBatchRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ProcessingStatusGetBatchRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ProcessingStatusGetBatchRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: string
            text/json:
              schema:
                type: string
        '400':
          description: Bad request
          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
        '404':
          description: Not found. Record to acknowledge not found.
        '405':
          description: Method Not allowed. This generally happens when trying to acknowledge an request status response that is already acknowledged.
          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: postV1RequestStatusAcknowledge
      x-operation-id-source: derived
components:
  schemas:
    ConsumerLogEventUserView:
      type: object
      properties:
        requestId:
          type:
          - string
          - 'null'
          description: The request id used to post in the data. This is returned in request header parameter 'x-amzn-RequestId', in response of the original request.
          example: 06ca6901-f728-489b-a827-704f5048858c
        entityType:
          enum:
          - Account
          - Contract
          - CostCenter
          - TaxCode
          - ExchangeRate
          - PaymentTerm
          - User
          - Project
          - MatchingOrder
          - MatchingOrderLine
          - GenericList
          - AdvancedPermission
          - TransferResponse
          - PaymentResponse
          - PrebookResponse
          - Vendor
          - AdvancedValidation
          - PurchaseRequisition
          - PurchaseOrder
          - PurchaseGoodsReceipt
          - Organization
          - EnrichmentTransferResponse
          - UserGroup
          - UserGroupAssociatedUser
          - UserGroupPermission
          type: string
          description: Entity type (API interface) of processed data.
          example: Account
        entityVersion:
          type:
          - string
          - 'null'
          description: Version of entity type (API interface).
          example: AccountV1
        requestStatus:
          enum:
          - InProgress
          - Success
          - Error
          - AcknowledgedSuccess
          - AcknowledgedError
          type: string
          description: "Status of processing the request (aggregated from statuses of each target system).\n* InProgress: Request is still being processed.  \n* Success: Request succesfully processed (no errors/warnings). \n* Error: There was one or more errors processing the request. \n* AcknowledgedSuccess: Request with 'Success' status after 'acknowledge' API operation. \n* AcknowledgedError: Request with 'Error' status after 'acknowledge' API operation."
          example: Error
        changedBy:
          type:
          - string
          - 'null'
          description: Username / name of the user who made change request
          example: John Doe
        operationType:
          type:
          - string
          - 'null'
          description: Type of API operation.
          example: POST
        genericListKey:
          type:
          - string
          - 'null'
          description: Generic List key against which changes have been made.
          example: ACC_LIST_1
        lastUpdated:
          type: string
          format: date-time
        systems:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BaswareSystem'
          description: Target system from which the response originates (P2P, network, etc).
      additionalProperties: false
    ProcessedItemErrorDetail:
      type: object
      properties:
        type:
          enum:
          - Error
          - Warning
          - RecordExpired
          type: string
          description: "Mesage type.\n* Error: Error processing the record. \n* Warning: Record saved with warning(s). Some data on the record may not be saved. Example: One or more user group(s) indicated on user record not found in P2P. User was saved, missing user groups were omitted.\n* RecordExpired: More recent version of the record has been posted to API. Skipped this version since only the more recent version will be saved. This usually requires the same record to have been updated two or more times within less than a second."
          example: Error
        message:
          type:
          - string
          - 'null'
          description: Error message.
          example: Record skipped due to wrong or missing CompanyCode
        category:
          enum:
          - Unknown
          - Technical
          - DataValidation
          type: string
          description: "Error category.\n* DataValidation: Data validation error. Typically correctable by customr through correcting an error in the data payload sent by customer.\n* Technical: Technical error. These typically require an intervention from Basware. \n* Unknown: Error category not identified."
          example: Data validation
      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
    RequestStatusResponse:
      required:
      - requestStatus
      type: object
      properties:
        requestStatus:
          type: array
          items:
            $ref: '#/components/schemas/ConsumerLogEventUserView'
      additionalProperties: false
    BaswareSystem:
      type: object
      properties:
        system:
          type:
          - string
          - 'null'
          description: Target system from which the response originates (P2P, network, etc).
          example: P2P
        module:
          type:
          - string
          - 'null'
          example: IA
        systemStatus:
          enum:
          - InProgress
          - Success
          - Error
          - AcknowledgedSuccess
          - AcknowledgedError
          type: string
          description: "Status of processing the request in the target system (aggregated from statuses of individual records). \n* InProgress: Request is still being processed.  \n* Success: Request succesfully processed (no errors/warnings). \n* Error: There was one or more errors processing the request. \n* AcknowledgedSuccess: Request with 'Success' status after 'acknowledge' API operation. \n* AcknowledgedError: Request with 'Error' status after 'acknowledge' API operation."
          example: Error
        lastUpdated:
          type: string
          format: date-time
        items:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ProcessedItem'
          description: Contains status for each invividual record posted in the original request.
      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.
    ProcessingStatusGetBatchRequest:
      type: object
      properties:
        requestIds:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of requestIds to acknowledge. Several requests can be acknowledged in one operation.
      additionalProperties: false
    ProcessedItem:
      type: object
      properties:
        externalCode:
          type:
          - string
          - 'null'
          description: ExternalCode of the processed record.
          example: aedf21df912ebc89123687cgh181ea4
        parentExternalCode:
          type:
          - string
          - 'null'
          description: ExternalCode of the parent record, if applicable. For example, for accounting document responses we will provide InvoiceID in this field.
        status:
          enum:
          - InProgress
          - NotProcessed
          - Warning
          - Success
          - Error
          - RecordExpired
          - Unpublished
          type: string
          description: "Status of the processed record. \n* InProgress: Record is still being processed.  \n* NotProcessed: Record skipped due to no changes from previous version of the record. \n* Warning: Record saved with warning(s). Some data on the record may not be saved. Example: One or more user group(s) indicated on user record not found in P2P. User was saved, missing user groups were omitted. \n* Success: Record succesfully saved (no errors/warnings). \n* Error: Error processing the record. \n* RecordExpired: More recent version of the record has been posted to API. Skipped this version since only the more recent version will be saved. This usually requires the same record to have been updated two or more times within less than a second.\n* Unpublished: Record is in draft status ('published' = 'false') and is not distributed to any target system. This status is used only with organizations API (coming soon)."
          example: Error
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ProcessedItemErrorDetail'
      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