openapi: 3.0.2
info:
  title: Basware OAUTH2 authentication APIs AccountingDocuments 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
tags:
- name: Contracts
paths:
  /v1/contracts:
    get:
      tags:
      - Contracts
      summary: Returns contract entities
      description: ''
      parameters:
      - 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: 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: 20577767-3fd9-4dda-9667-a7d7ee00ac95
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ContractResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ContractResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ContractResponse'
        '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:
      - Contracts
      summary: Creates new contract entity, overwrites previous if exists.
      description: "Notes: \r\n1. The supplier and company code used need to exist in P2P. \r\n2. P2P needs to know the exchange rate from contract currency to company currency (if there are different)."
      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/ContractEntity'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ContractEntity'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ContractEntity'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ContractEntity'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContractEntity'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContractEntity'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContractEntity'
        '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:
      - Contracts
      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. \r\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.\r\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/contracts/{externalCode}:
    get:
      tags:
      - Contracts
      summary: Returns single contract entity by ID
      description: ''
      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/ContractEntity'
            application/json:
              schema:
                $ref: '#/components/schemas/ContractEntity'
            text/json:
              schema:
                $ref: '#/components/schemas/ContractEntity'
        '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:
      - Contracts
      summary: Updates contract entity. To do a partial update consumer needs to provide changed properties.
      description: 'Note: Contract currency can no longer be changed if spend has been collected for the contract.'
      parameters:
      - name: externalCode
        in: path
        description: The ExternalCode of the contract to be updated
        required: true
        schema:
          type: string
      requestBody:
        description: Entity to be updated
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/ContractEntity'
          application/json:
            schema:
              $ref: '#/components/schemas/ContractEntity'
          text/json:
            schema:
              $ref: '#/components/schemas/ContractEntity'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ContractEntity'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ContractEntity'
            application/json:
              schema:
                $ref: '#/components/schemas/ContractEntity'
            text/json:
              schema:
                $ref: '#/components/schemas/ContractEntity'
        '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'
components:
  schemas:
    ContractSuppliers:
      required:
      - supplierCode
      type: object
      properties:
        supplierCode:
          maxLength: 25
          minLength: 1
          type: string
          description: Code of the supplier on the contract. This supplier needs to exist in P2P and be available on the selected company.
          example: '32789'
        supplierName:
          maxLength: 250
          minLength: 0
          type: string
          description: Name of the supplier on the contract. Informative field, P2P will take supplier name from it's supplier registry.
          nullable: true
          example: Acme Motor Leasing inc.
      additionalProperties: false
    DeleteRequest:
      type: object
      properties:
        lastUpdated:
          type: string
          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
          nullable: true
        externalCode:
          maxLength: 36
          minLength: 0
          type: string
          description: Single item can be deleted using externalCode and final status is returned immediately.
          nullable: true
      additionalProperties: false
    ContractEntity:
      required:
      - active
      - companyCode
      - currencyCode
      - externalCode
      - owner
      - referenceCode
      - suppliers
      - title
      - total
      - validFrom
      - validTo
      type: object
      properties:
        referenceCode:
          maxLength: 255
          minLength: 1
          type: string
          description: FreeText reference shown in contracts view (Contract Number). Same company and vendor -combination(s) must not use same reference code (contract number) multiple times.
          example: '12197627'
        companyCode:
          maxLength: 32
          minLength: 1
          type: string
          description: Buyer Company Code. This company needs to exist in P2P before importing the contract.
          example: '200'
        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
          description: General information on contract.
          nullable: true
          example: This contract is for car leasing for Acme Motor leasing inc.
        type:
          maxLength: 100
          minLength: 1
          type: string
          description: Determined by the contract management system. Types are displayed only for informational purposes.
          nullable: true
          example: Leasing
        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: '2025-01-01'
        total:
          maximum: 9999999999999
          minimum: 0
          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. Default value: Net.'
          nullable: true
          example: net
        currencyCode:
          maxLength: 3
          minLength: 2
          type: string
          description: 'Currency used in the contract. Note: 1) P2P needs to have an exhange rate configured from contract curency currency of the company used on contract (if they are different). 2) Contract currency cannot be changed if spend has been collected for the contract.'
          example: EUR
        paymentTermCode:
          maxLength: 250
          minLength: 0
          type: string
          description: Payment term for this contract.
          nullable: true
          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
          description: The person to contact on contract matters.
          nullable: true
          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/ContractSuppliers'
          description: Supplier(s) for contract.
        externalLinks:
          type: array
          items:
            $ref: '#/components/schemas/ContractExternalLinks'
          description: ExternalLinks for contract.
          nullable: true
        orderSpend:
          type: boolean
          description: States if spend of orders using this contract is collected for spend reporting.
          nullable: true
          example: true
        spendPlanSpend:
          type: boolean
          description: Field reserved for future use (to state if spend of spend plans using this contract is collected for spend reporting).
          nullable: true
          example: false
        invoiceSpend:
          type: boolean
          description: Field reserved for future use (to state if spend of invoices linked to this contract is collected for spend reporting).
          nullable: true
          example: false
        externalCode:
          maxLength: 36
          minLength: 1
          type: string
          description: External identifier that is used as a key in API.
          example: 4847-31231212-212121-1212
        lastUpdated:
          type: string
          description: Timestamp when the record was last sent to API. Set automatically.
          format: date-time
      additionalProperties: false
      description: ''
    DeleteResponse:
      type: object
      properties:
        statusApiLink:
          type: string
          nullable: true
        taskName:
          type: string
          nullable: true
        taskStatus:
          type: string
          nullable: true
      additionalProperties: false
    ContractExternalLinks:
      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
          description: URL used when selecting external link
          nullable: true
          example: https://www.acmemotorsinc.com
      additionalProperties: false
      description: Contract external links
    ErrorEntity:
      type: object
      properties:
        externalCode:
          type: string
          description: External code of record on which error occurred (when available).
          nullable: true
          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
          description: Specific error message.
          nullable: true
          example: ''
        info:
          type: string
          description: Information about type of the error.
          nullable: true
          example: ''
      additionalProperties: false
    ContractResponse:
      required:
      - contracts
      type: object
      properties:
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/ContractEntity'
      additionalProperties: false
    ResponseEntityList:
      type: object
      properties:
        requestId:
          type: string
          description: ID of the request on which error occurred (generated by Basware API).
          nullable: true
          example: fbc082a2-65a4-469c-b230-d84a252f18fc
        hasErrors:
          type: boolean
          description: Specifies whether the request has errors.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
          nullable: true
      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.
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic