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 . \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 . \n\nSee the Basware API developer site at 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