openapi: 3.0.2 info: title: Basware OAUTH2 authentication APIs AccountingDocuments ExportedContracts 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: ExportedContracts paths: /v1/exportedContracts: get: tags: - ExportedContracts summary: Returns contracts (along with spend totals) exported from Basware P2P. description: "Notes: \r\n1) Whether contract spends are collected is controlled by the fields 'invoiceSpend', 'orderSpend' and 'spendPlanSpend'. Spend is not collected when these fields are set to 'false'.\r\n2) This API supports sending webhook based [push notifications](https://developer.basware.com/api/p2p/manual#PushNotifications) when new data is available to be exported. \r\n3) This API exports contracts imported through Basware API. Contracts imported through anyerp are not exported. \r\n\r\nPlease see section \"[Usage scenario 4: Import and export procurement data](https://developer.basware.com/api/p2p/manual#usage4)\" 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: processingStatus in: query description: Document status filter. Returns records by document status. Use 'WaitingForExport' to retrieve unacknowledged records. schema: enum: - WaitingForExport - Exported type: string - name: 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: 200 - 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: 6724c88a-3a53-4a08-a3a8-c2a05c5e42f8 responses: '200': description: Success content: text/plain: schema: $ref: '#/components/schemas/ExportedContractsResponse' application/json: schema: $ref: '#/components/schemas/ExportedContractsResponse' text/json: schema: $ref: '#/components/schemas/ExportedContractsResponse' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ResponseEntityList' application/json: schema: $ref: '#/components/schemas/ResponseEntityList' text/json: schema: $ref: '#/components/schemas/ResponseEntityList' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/ResponseEntityList' application/json: schema: $ref: '#/components/schemas/ResponseEntityList' text/json: schema: $ref: '#/components/schemas/ResponseEntityList' '500': description: Unexpected error content: text/plain: schema: $ref: '#/components/schemas/ResponseEntityList' application/json: schema: $ref: '#/components/schemas/ResponseEntityList' text/json: schema: $ref: '#/components/schemas/ResponseEntityList' delete: tags: - ExportedContracts 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 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' /v1/exportedContracts/{externalCode}: get: tags: - ExportedContracts summary: Returns contracts (along with spend totals) exported from Basware P2P by externalCode. description: "Notes: \r\n1) Whether contract spends are collected is controlled by the fields 'invoiceSpend', 'orderSpend' and 'spendPlanSpend'. Spend is not collected when these fields are set to 'false'.\r\n2) This API exports contracts imported through Basware API. Contracts imported through anyerp are not exported. \r\n\r\nPlease see section \"[Usage scenario 4: Import and export procurement data](https://developer.basware.com/api/p2p/manual#usage4)\" 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 contract to be fetched. required: true schema: type: string responses: '200': description: Success content: text/plain: schema: $ref: '#/components/schemas/ExportedContractsResponse' application/json: schema: $ref: '#/components/schemas/ExportedContractsResponse' text/json: schema: $ref: '#/components/schemas/ExportedContractsResponse' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ResponseEntityList' application/json: schema: $ref: '#/components/schemas/ResponseEntityList' text/json: schema: $ref: '#/components/schemas/ResponseEntityList' '404': description: Not found content: text/plain: schema: $ref: '#/components/schemas/ResponseEntityList' application/json: schema: $ref: '#/components/schemas/ResponseEntityList' text/json: schema: $ref: '#/components/schemas/ResponseEntityList' '500': description: Unexpected error content: text/plain: schema: $ref: '#/components/schemas/ResponseEntityList' application/json: schema: $ref: '#/components/schemas/ResponseEntityList' text/json: schema: $ref: '#/components/schemas/ResponseEntityList' /v1/exportedContracts/acknowledge: post: tags: - ExportedContracts summary: Acknowledged contract spends are no longer returned on the next GET operation. description: "Notes: \r\n1) Updates 'processingStatus' -field on the document to allow filtering out already acknowledged documents on the next GET operation. \r\n2) For a document which is already acknowledged (processingStatus: 'Exported'), API will return 405 'Method not allowed' if acknowledge is attempted again on the document." 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/AcknowledgeRequest' application/json: schema: $ref: '#/components/schemas/AcknowledgeRequest' text/json: schema: $ref: '#/components/schemas/AcknowledgeRequest' application/*+json: schema: $ref: '#/components/schemas/AcknowledgeRequest' responses: '200': description: Success content: text/plain: schema: type: string application/json: schema: type: string text/json: schema: type: string '400': description: Bad request '401': description: Unauthorized '404': description: Not found '405': description: Method not allowed. This generally happens when trying to acknowledge an exportedContract that is already acknowledged. '500': description: Unexpected error components: schemas: 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 DeleteResponse: type: object properties: statusApiLink: type: string nullable: true taskName: type: string nullable: true taskStatus: type: string nullable: true additionalProperties: false ExportedContractExternalLink: 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 ExportedContractSpendTotal: type: object properties: documentType: enum: - AccountingDocument - PurchaseOrder - SpendPlan type: string description: Specifies the type of document for which sums of projected / spent amounts are stated. example: AccountingDocument netSumContract: type: number description: Net sum of spends in the currency of the contract. format: double example: 2000 grossSumContract: type: number description: Gross sum of spends in the currency of the contract. format: double example: 2480 currencyCodeContract: type: string description: Currency code of the contract. nullable: true example: EUR netSumCompany: type: number description: Net sum of spends in the currency of the company. format: double example: 10230 grossSumcompany: type: number description: Gross sum of spends in the currency of the company. format: double example: 12685.2 currencyCodecompany: maxLength: 3 minLength: 2 type: string description: Currency code of the company. nullable: true example: SEK netSumOrganization: type: number description: Net sum of spends in the currency of the Organization. format: double example: 1680 grossSumOrganization: type: number description: Gross sum of spends in the currency of the Organization. format: double example: 2291.52 currencyCodeOrganization: maxLength: 3 minLength: 2 type: string description: Currency code of the Organization. nullable: true example: GBP additionalProperties: false 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 ExportedContractsResponse: required: - contracts type: object properties: contracts: type: array items: $ref: '#/components/schemas/ExportedContractEntity' 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. ExportedContractEntity: required: - active - companyCode - currencyCode - externalCode - owner - referenceCode - suppliers - title - total - validFrom - validTo type: object properties: externalCode: maxLength: 100 minLength: 1 type: string description: External identifier that is used as a key in API. example: 4847-31231212-212121-1212 referenceCode: maxLength: 255 minLength: 1 type: string description: FreeText Reference shown in contracts view (Contract Number) example: '12197627' processingStatus: enum: - WaitingForExport - Exported type: string description: Processing status of the contract spend in Basware API. Use 'WaitingForExport' to get unacknowledged records. example: WaitingForExport companyCode: maxLength: 25 minLength: 1 type: string description: Buyer Company Code example: '200' companyName: maxLength: 250 minLength: 0 type: string description: Buyer Company Name nullable: true example: Acme Motor leasinc inc. 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: '' 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: '2023-12-31' total: 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 example: '12197627' currencyCode: maxLength: 3 minLength: 2 type: string description: Currency for the total value 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/ExportedContractSupplier' description: Suppliers for contract externalLinks: type: array items: $ref: '#/components/schemas/ExportedContractExternalLink' description: ExternalLinks for contract nullable: true spendTotals: type: array items: $ref: '#/components/schemas/ExportedContractSpendTotal' description: "Aggregate sums of all projected / spent amounts per document type. \r\n1) For 'AccountingDocument', this is the actual total spend. The spend is from invoices which are transferred to accounting (documents in circulation are not included). All invoices linked to the contract are included, whether PO, non-PO, or payment plan matched invoices. \r\n2) For 'PurchaseOrder', this is the projected total spend. Included are all purchaseOrders in P2P Purchase, which are sent to supplier and linked to the contract. It does not matter whether the orders have been invoiced or not. Spend from matching orders is not included. \r\n3) For 'SpendPlan', this is the projected total spend. Included are all active spend plans. The spend from a spend plan gets added the moment the spend plan is activated. It does not matter if the spend plan has received any invoices or not. \r\nNote: The individual spend events can be accessed through exportedContractSpends API by providing the externalCode of the contract and optionally the document type." nullable: true orderSpend: type: boolean description: States if spend of orders using this contract is collected for spend reporting. example: true spendPlanSpend: type: boolean description: States if spend of spend plans using this contract is collected for spend reporting. example: true invoiceSpend: type: boolean description: States if spend of invoices using this contract is collected for spend reporting. example: true lastUpdated: type: string description: Timestamp when the record was last sent to API. Set automatically. format: date-time additionalProperties: false AcknowledgeRequest: type: object properties: lastUpdated: type: string description: Records with lastUpdated -timestamp after the specified value are acknowledged. '0001-01-01' can be used as input value to acknowledge all records. format: date-time nullable: true example: '2022-01-01' externalCodes: type: array items: type: string description: List of requestIds to acknowledge. Several requests can be acknowledged in one operation. nullable: true additionalProperties: false ExportedContractSupplier: required: - supplierCode type: object properties: supplierCode: maxLength: 25 minLength: 1 type: string description: Code of the supplier on the contract example: '32789' supplierName: maxLength: 250 minLength: 0 type: string description: Acme Motor Leasing inc. nullable: true example: '32789' additionalProperties: false securitySchemes: HTTPBasic: type: http scheme: basic