Basware MatchingOrderLines API

openapi: 3.2.0
info:
  title: Basware OAUTH2 authentication APIs AccountingDocuments Matching Order Lines 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: MatchingOrderLines
paths:
  /v1/matchingOrderLines:
    get:
      tags:
      - MatchingOrderLines
      summary: Returns matching order lines posted to Basware API.
      description: ''
      parameters:
      - name: orderExternalCode
        in: query
        description: The externalCode of the order.
        required: true
        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 100 items.
        schema:
          type: integer
          format: int32
          default: 100
      - 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: 194943db-da52-4167-a464-d348bb1ced18
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/OrderLineResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/OrderLineResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/OrderLineResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found. Request was successful and no records were 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'
    post:
      tags:
      - MatchingOrderLines
      summary: Creates new matching order line(s), fully overwrites previous record if exists.
      description: "Notes:\n1) Please make sure you have POSTed the order header through matchingOrders API before posting lines to the same order to matchingOrderLines API. It is enough to POST the order header only once (unless updates are neede to the order header). \n2) Up to 100 order lines can be posted in one request. Order lines for an order containing more than 100 lines need to be posted in several requets.\n3) A single POST operation is saved to P2P in a single transaction. Multiple POST operations will be saved each in their own transactions.\n4) Invoiced quantities and sums need to be imported before matching has been performed against the order in P2P. \n5) Field 'isDeleted' needs to have a value other than null when bestfit matching is used on the order in P2P. \n\nPlease see section \"[Usage scenario 2: Import external purchase orders for Order Matching](https://developer.basware.com/api/p2p/manual#usage2)\" 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: 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:
              type: array
              items:
                $ref: '#/components/schemas/OrderLineEntity'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrderLineEntity'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrderLineEntity'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrderLineEntity'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderLineEntity'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderLineEntity'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderLineEntity'
        '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
        '409':
          description: Conflict
          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:
      - MatchingOrderLines
      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
        '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/matchingOrderLines/{externalCode}:
    get:
      tags:
      - MatchingOrderLines
      summary: Returns single matching order line by externalCode -identifier.
      description: ''
      parameters:
      - name: externalCode
        in: path
        description: ExternalCode of the entity to be fetched
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/OrderLineEntity'
            application/json:
              schema:
                $ref: '#/components/schemas/OrderLineEntity'
            text/json:
              schema:
                $ref: '#/components/schemas/OrderLineEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not found. Request was successful and no records were 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'
    patch:
      tags:
      - MatchingOrderLines
      summary: Updates fields on specified matching order line. Can be used for adding new goods receipts to the order line. Preserves existing values in fields, which were not updated.
      description: "Notes: \n1) Concurrent PATCH operations to the same matchingOrderline can fail with error HTTP 503 due to concurrency issues. In such a case the failed request should be retried after a few seconds delay. \n2) Basware API considers 'null' value in field(s) equivalent to the field(s) not being sent. For this reason patch method does not support setting field values to 'null'.\n\nPlease see section \"[Usage scenario 2: Import external purchase orders for Order Matching](https://developer.basware.com/api/p2p/manual#usage2)\" 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 orderLine to be updated
        required: true
        schema:
          type: string
      requestBody:
        description: Entity to be updated
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/OrderLineEntity'
          application/json:
            schema:
              $ref: '#/components/schemas/OrderLineEntity'
          text/json:
            schema:
              $ref: '#/components/schemas/OrderLineEntity'
          application/*+json:
            schema:
              $ref: '#/components/schemas/OrderLineEntity'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/OrderLineEntity'
            application/json:
              schema:
                $ref: '#/components/schemas/OrderLineEntity'
            text/json:
              schema:
                $ref: '#/components/schemas/OrderLineEntity'
        '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 update 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'
        '503':
          description: Service unavailable
components:
  schemas:
    OrderLineUserEntity:
      type: object
      properties:
        userExternalCode:
          maxLength: 36
          minLength: 0
          type:
          - string
          - 'null'
          description: External code. Either userExternalCode or userEmail is required.
          example: 6532e1d70e194ff8a193e42beab4a0d9
        userEmail:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Email address. Either userExternalCode or userEmail is required.
          example: buyer@company.com
        userRole:
          enum:
          - Buyer
          - Owner
          - ReferencePerson
          - Other
          type:
          - string
          - 'null'
          description: User role.
          example: ''
        lastUpdated:
          type: string
          description: Timestamp when the record was last sent to API. Set automatically.
          format: date-time
      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
    GoodsReceiptEntity:
      required:
      - externalCode
      - goodsReceiptNumber
      - quantity
      type: object
      properties:
        externalCode:
          maxLength: 36
          minLength: 1
          type: string
          description: Identifies the goods receipt for future updates through Basware API. Typically Generated by the system calling Basware API.
          example: 234-3444-74334667-1434612
        goodsReceiptNumber:
          maxLength: 100
          minLength: 1
          type: string
          description: Goods receipt number.
          example: '487632933422'
        goodsReceiptLineNumber:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Goods receipt line number.
          example: '1'
        referenceGRExternalCode:
          maxLength: 36
          minLength: 0
          type:
          - string
          - 'null'
          description: "Used to cancel (part of) an existing goods receipt. Place the 'externalCode' value of the original goods receipt here when this receipt item is a negative return/cancellation item for an earlier receipt. \n\nNote: If the original GR does not have netPrice / grossPrice, reversing part of the original GR will set the netSum / grossSum of the original GR to 0. This happens because the the sums get recalculated based on quantity x (net/gross)Price when values are updated."
          example: ''
        deliveryNoteNumber:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Identifier of the delivery from where the receipt was made.
          example: '8718232387'
        bestFitGrouping:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Grouping factor for received items that are invoiced together without any delivery indicator. The value can be for example a delivery note number or a delivery date. Used in best-fit matching.
          example: '4847432142354'
        quantity:
          type: number
          description: Received quantity
          format: double
          example: 10
        netSum:
          type:
          - number
          - 'null'
          description: 'Total currency value of the received items, excluding tax. Note: Either net or gross currency amounts are required on the entire purchase order (both can be provided). Depending on type of provided amounts, either net or gross -based invoice matching can be used.'
          format: double
          example: 1000
        grossSum:
          type:
          - number
          - 'null'
          description: 'Total currency value of the received items, including tax. Note: Either net or gross currency amounts are required on the entire purchase order (both can be provided). Depending on type of provided amounts, either net or gross -based invoice matching can be used.'
          format: double
          example: 1160
        netPrice:
          type:
          - number
          - 'null'
          description: "The unit price of the received item (price for a single item), excluding tax. \n\nNote: If the original GR does not have netPrice, reversing part of the original GR (done using 'referenceGRExternalCode' field) will set the netSum of the original GR to 0. This happens because the netSum gets recalculated based on quantity x netPrice when values are updated."
          format: double
          example: 100
        grossPrice:
          type:
          - number
          - 'null'
          description: 'The unit price of the received item (price for a single item), including tax.


            Note: If the original GR does not have grossPrice, reversing part of the original GR (done using ''referenceGRExternalCode'' field) will set the grossSum of the original GR to 0. This happens because the grosstSum gets recalculated based on quantity x grossPrice when values are updated.'
          format: double
          example: 116
        isDeleted:
          type:
          - boolean
          - 'null'
          description: 'Indicates whether the received item is deleted. If TRUE, the received item has been marked as deleted. Default value: FALSE.'
          example: false
        notifyFault:
          type:
          - boolean
          - 'null'
          description: Used to indicate goods have been received as damaged. 'True' if goods are faulty. P2P can be configured to stop automatic invoice processing when an invoice has been matched against damaged goods.
          example: false
        invoicedQuantity:
          type:
          - number
          - 'null'
          description: Quantity that already has been matched from the line item
          format: double
          example: 0
        invoicedNetSum:
          type:
          - number
          - 'null'
          description: Sum that already has been matched excluding tax
          format: double
        invoicedGrossSum:
          type:
          - number
          - 'null'
          description: Sum that already has been matched including tax
          format: double
        unitOfMeasure:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Unit of measure of the line item. Valid value is UN/ECE CEFACT Trade Facilitation Recommendation No. 20 common code value represented as string.
          example: ''
        subUnitOfMeasure:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Alternative unit of measurement of the line item. Valid value is UN/ECE CEFACT Trade Facilitation Recommendation No. 20 common code value represented as string.
          example: ''
        goodsReceiptType:
          type:
          - integer
          - 'null'
          description: Goods receipt type, specified by Customer.
          format: int32
        receiveMethod:
          type:
          - integer
          - 'null'
          description: Receive method, specified by customer.
          format: int32
        voucherNumber:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: A reference to a buyer-generated document that authorizes a purchase transaction
          example: 201809PO0001
        goodsReceiptNote:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Free-form text applying to the goods receipt. This field may contain notes or any other similar information that is not contained explicitly in another structure.
          example: Quality check ok
        fiscalYear:
          type:
          - string
          - 'null'
          description: Used when goods or services are received this fiscal year and will be paid for next fiscal year
          format: date-time
        deliveryDate:
          type:
          - string
          - 'null'
          description: 'Date when the goods/services are delivered. Valid values are in format: CCYY-MM-DD. If the time zone is known, it must be represented with +hh:mm or -hh:mm or Z (which means UTC). If the time zone is not known, it must be left empty.'
          format: date-time
        productSerialNumber:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: A serial number is a code to uniquely identify the received item.
          example: 8-01553-01
        comment:
          maxLength: 255
          minLength: 0
          type:
          - string
          - 'null'
          description: Available for additional information regarding the goods receipt, such as description of damaged goods.
        text1:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Text1-5 are available for customer-specific text fields.
          example: ''
        text2:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text3:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text4:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text5:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text6:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: account
        text7:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text8:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text9:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        text10:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        numeric1:
          type:
          - number
          - 'null'
          description: Numeric1-5 are available for customer-specific numericfields.
          format: double
        numeric2:
          type:
          - number
          - 'null'
          format: double
        numeric3:
          type:
          - number
          - 'null'
          format: double
        numeric4:
          type:
          - number
          - 'null'
          format: double
        numeric5:
          type:
          - number
          - 'null'
          format: double
        date1:
          type:
          - string
          - 'null'
          description: Date1-5 are available for customer-specific date fields.
          format: date-time
        date2:
          type:
          - string
          - 'null'
          format: date-time
        date3:
          type:
          - string
          - 'null'
          format: date-time
        date4:
          type:
          - string
          - 'null'
          format: date-time
        date5:
          type:
          - string
          - 'null'
          format: date-time
        serviceEntrySheetDocId:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: Custom field in the business document
          example: ''
        receiptCoding:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OrderLineCodingEntity'
          description: ReceiptCoding (for Service POs only) defines default coding dimension values for matched invoice lines. For Service POs, only one codingRow is allowed.
      additionalProperties: false
    OrderLineCodingEntity:
      required:
      - allocatedQuantity
      - externalCode
      - rowIndex
      type: object
      properties:
        externalCode:
          maxLength: 36
          minLength: 1
          type: string
          description: Unique identifier used for updates through Basware API.
          example: 1547e437-1231-ad32-dff2-132985aae212
        rowIndex:
          maximum: 100000
          minimum: 0
          type: integer
          description: Row number of coding row on the PO line.
          format: int32
          example: 0
        netTotal:
          type:
          - number
          - 'null'
          description: 'Represents total excluding tax that is allocated for the accounting dimensions set in the coding row item. Note: Either net or gross currency amounts are required on the entire purchase order (both can be provided). Depending on type of provided amounts, either net or gross -based invoice matching can be used.'
          format: double
        grossTotal:
          type:
          - number
          - 'null'
          description: 'Represents total including tax that is allocated for the accounting dimensions set in the coding row item. Note: Either net or gross currency amounts are required on the entire purchase order (both can be provided). Depending on type of provided amounts, either net or gross -based invoice matching can be used.'
          format: double
        accountCode:
          maxLength: 50
          minLength: 0
          type:
          - string
          - 'null'
          description: Account code. A code that identifies the general ledger account to where the matched spend is recorded.
          example: '28520'
        accountName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Name of the account
          example: Other marketing expences
        costCenterCode:
          maxLength: 200
          minLength: 0
          type:
          - string
          - 'null'
          description: Cost center code. A code that identifies the part of an organization to which costs may be charged for accounting purposes
          example: '1010'
        costCenterName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Name of the cost center
          example: Global presales and Marketing
        projectCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: A code that identifies the project when the spend is required to be recorded
          example: '32101'
        projectName:
          maxLength: 250
          minLength: 0
          type:
          - string
          - 'null'
          description: Name of the project
          example: Basware Connect 2022
        conversionNumerator:
          type:
          - number
          - 'null'
          description: A conversion factor is used to change the units of a nominator in quantity without changing its value. For example, one envelope weighs 7 g.
          format: double
        conversionDenominator:
          type:
          - number
          - 'null'
          description: A conversion factor is used to change the units of a denominator in quantity without changing its value.
          format: double
        conversionDeNumerator:
          type:
          - number
          - 'null'
          description: Deprecated - field not in use.
          format: double
        taxCode:
          maxLength: 25
          minLength: 0
          type:
          - string
          - 'null'
          description: Tax code.
          example: T16
        taxPercent:
          maximum: 1000000000
          minimum: -1000000000
          type:
          - number
          - 'null'
          description: Tax percent.
          format: double
          example: 16
        taxPercent2:
          maximum: 1000000000
          minimum: -1000000000
          type:
          - number
          - 'null'
          description: Tax percent 2. Can be used for example for handling reverse charges on EU VAT.
          format: double
          example: 0
        taxSum:
          type:
          - number
          - 'null'
          description: Tax sum.
          format: double
          example: 16
        taxSum2:
          type:
          - number
          - 'null'
          description: Tax sum 2.
          format: double
          ex

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/basware/refs/heads/main/openapi/basware-matchingorderlines-api-openapi.yml