Introduction
The purpose of this manual is to describe Basware API integration capabilities for Master data imports and Purchase-to-Pay integration scenarios. It contains process-level instructions, end-to-end data flows, as well as recommended practices for implementation and debugging.
Basware API is a REST API available through web service calls. JSON data format is used in the message payloads.
Basware API integrations are available for the following Basware end-systems.
- Basware Network
- Basware Purchase-to-Pay
- Basware Supplier Management
P2P APIs are available through the following regions: Europe (EU), USA (US) and Australia (AU). APIs will be set up in the same region as your P2P system. Separate environments are available for test and production systems.
List of available Purchase-to-Pay APIs
The following APIs are available for transferring invoices to accounting, importing master data, user data and external purchase orders for invoice matching, as well as for importing and exporting data to and from P2P Purchase.
| Importing master data | Available Basware systems |
|
| AdvancedValidations | Import invoice coding row validation rules from ERP | P2P |
| Accounts | Import accounts from ERP | P2P |
| CostCenters | Import cost centers from ERP | P2P |
| ExchangeRates | Import exchange rates from ERP | P2P |
| GenericLists | Import additional coding dimensions from ERP | P2P |
| PaymentTerms | Import payment terms from ERP | P2P |
| Projects | Import projects from ERP | P2P |
| TaxCodes | Import tax codes from ERP | P2P |
| Vendors | Import vendors from ERP | P2P, Supplier Management |
| Importing user master data | ||
| Users | Import users |
P2P, Supplier Portal, Supplier Management, Reporting, CloudScan 3.0 |
| ApplicationGroups | Control per-application log-in access (assigned to users). | P2P, Supplier portal, Supplier Management, Reporting, CloudScan 3.0 |
| AdvancedPermissions | Import user approval rights information | P2P |
| Importing external purchase orders for invoice matching | ||
| MatchingOrders | Import order header data into matching | P2P (AP Automation) |
| MatchingOrderLines | Import and update order lines and goods receipts into matching | P2P (AP Automation) |
| Importing and exporting procurement data for P2P Purchase | ||
| PurchaseRequisitions | Import purchase requisitions to P2P Purchase from an external system | P2P (Purchase) |
| ExportedPurchaseRequisitions | Export purchase requisitions from P2P Purchase | P2P (Purchase) |
| PurchaseOrders | Import Purchase Orders to P2P Purchase from an external system | P2P (Purchase) |
| PurchaseGoodsReceipts | Import goods receipts to P2P Purchase from an external system | P2P (Purchase) |
| ExportedPurchaseOrders | Export purchase orders and GR's from P2P Purchase | P2P (Purchase) |
| Contracts | Import contract metadata to P2P Purchase from an external system | P2P (Purchase) |
| ExportedContracts | Export contracts from P2P Purchase | P2P (Purchase) |
| ExportedContractSpends | Export contract spends from P2P Purchase | P2P (Purchase) |
| Transferring approved invoices to accounting | ||
| AcccountingDocuments | Prebook invoices or transfer approved invoices to accounting system | P2P (AP Automation) |
| Acknowledge | Mark invoice as fetched | P2P (AP Automation) |
| PrebookResponse | Mark invoice as prebooked in accounting system | P2P (AP Automation) |
| TransferResponses | Mark invoice as transferred to accounting system | P2P (AP Automation) |
| PaymentResponses | Update invoice payment date | P2P (AP Automation) |
| Retrieving API request status / errors |
||
| RequestStatus (new API) | Check target system status of sent requests. Asynchronously returns success and error messages from target systems. Replaces errorFeedbacks API. | P2P, Supplier portal, Supplier Management |
| ErrorFeedbacks | Error handling. Returns errors asynchronously from Basware receiving systems. | P2P |
| Push notifications | ||
| Subscriptions | Subscribe to receive push notifications. | P2P |
| Tasks | Check status of notifications sent by Basware API. | P2P |
| Authentication | ||
| Tokens | Retrieve OAUTH2 authentication tokens. | P2P, Supplier Portal, Supplier Management, Reporting, CloudScan 3.0 |
Supported methods for Basware APIs
API methods and fields
Detailed documentation for available methods and field sets for each API are described in the P2P API reference documentation.
Basware APIs support the following methods.
POST - Adds or updates records. Clears existing data from omitted fields
POST method updates the record based on externalCode field. If no record is found with given externalCode, a new record is created. All fields are updated within the record. Existing data in fields is cleared before the update.
PATCH - Updates records. Preserves existing data in omitted fields
PATCH method updates the record based on externalCode field. Difference to POST is that only fields included in the JSON in the request are updated. Data fields not explicitly included in the JSON request are left unchanged.
GET - Gets records from Basware API
GET method lists the records for a particular interface. Returned data contains all JSON fields and their values for the returned records. An externalCode can be specified as parameter to return data for only the specified record.
DELETE - Deletes records from Basware API
DELETE method deletes records from Basware API. The records are deleted from API only. To delete the records also from the data receiving Basware systems, use the data deletion mechanisms provided by each of the Basware receiving systems.
Data update scenarios
Below is an illustration of system behaviour in various data update scenarios.
Push notifications
To receive push notifications, customer needs to publish a webservice which receives notifications in a predefined format. These notifications trigger customer system to fetch documents from Basware API, which enables near real-time transfer of documents. Data export notifications are available for the following APIs. When notification is received, you can immediately retrieve data from the same API(s) as would be polled otherwise.
-
- accountingDocuments
- exportedPurchaseOrders
- exportedPurchaseRequisitions
- exportedContracts
- exportedContractSpends
- requestStatus
Subscribing to push notifications
Receiving the notifications requires customer to publish a webservice which receives task notifications in below JSON format. This webservice needs to be accessible from public Internet. Each nofitication is signed a using secret key which is self-service changeable by customer.
[
{
"taskId": "sajkhe1i87yhdgdi6sad7iyahljh1ut1",
"taskStatus": "New",
"taskType": "AccountingDocuments",
"taskSubtype": "WaitingForTransfer",
"documentId": "sajkhe1i87yhdgdi6sad7iyahljh1ut1",
}
]When the webservice to receive notifications is up and running, customer can subscribe to receive webhook notifications. This is done by specifying your webhook endpoint address as well as details on which notifications you want to receive through the 'subscriptions' API.
When subscribing, Basware API will verify the endpoint by posting a test notification with taskType 'ConnectionTest'. Customer system needs to return a 200 'OK' HTTP response to this request for the subscription endpoint to be validated. When subscribed, notifications for any new API tasks will be sent to your specified webservice address.
Recommended usage patterns
When you receive a notification, you should do a GET request to the interface specified by the notification's (field 'taskType'). Since one GET operation can return multiple documents and new notifications may arrive before the GET operation finishes, Basware recommends following usage patterns.
Usage pattern 1: GET multiple documents in a single thread (recommended)
- Start the thread for fetching documents when a webhook notification is received.
- If a thread is already running, do not start another one before the thread completes in order to to prevent receiving same documents twice. Instead, start the new thread after task has completed in order to fetch any remaining documents.
- Use acknowledge or lastUpdated to get the next round of documents.
- Have a (nightly) task which polls for new documents in order to prevent missing documents due to network or other issues.
Usage pattern 2: Get each document by documentId
Usage pattern 2: GET invoices one by one using the invoiceId provided in the notification.- GET each invoice individually by invoiceId as soon as the notification arrives.
- Have a (nightly) task which polls for new documents in order to prevent missing documents due to network or other issues.
- Note: Sending webhook notifications is not retried, but you can use the 'tasks' API to check for any notifications whose delivery has failed.
Validating notification signature
In order to secure your webhook endpoints, which receive calls from Basware, Basware signs the webhook events it sends to your endpoints by including a signature in each request’s header. This allows you to verify that the event requests were sent by Basware and not by an unauthorized third party. Here is how to validate the signature with example payload contents.
Request header parameter 'x-bwapi-signature-256':
Name: x-bwapi-signature-256
Value: t=1629118316,v1=55258f455c0c0427527679626967148475a12d68b19248b69a903a9970b35a02
JSON payload:
[{"taskId": "1a2ee1c0-d0ab-486d-8da6-95a8d4ac37ce", "taskStatus": "New", "taskType": "AccountingDocuments", "taskSubType": "WaitingForTransfer", "documentId": "3661018bdfe24eeea2ec271a45eca5b4", "expirationTime": null}]
Validation instructions:
- Read request header parameter 'x-bwapi-signature-256'.
- 't=1629118316' indicates the timestamp (in epoch format). Timezone: UTC.
- 'v1=55258f455c0c0427527679626967148475a12d68b19248b69a903a9970b35a02' contains the signature.
- Check notification timestamp
- Compare timestamp t=1629118316 to current datetime. Reject the notification if it is too old.
- Useful tool for converting the time: https://www.epochconverter.com/
- Calculate signature from request payload
- Create a string in format TIMESTAMP.NOTIFICATION_PAYLOAD
- Example: 1629118316.[{"taskId": "1a2ee1c0-d0ab-486d-8da6-95a8d4ac37ce", "taskStatus": "New", "taskType": "AccountingDocuments", "taskSubType": "WaitingForTransfer", "documentId": "3661018bdfe24eeea2ec271a45eca5b4", "expirationTime": null}]
- Calculate HMAC-SHA256 hash from the generated string using pre-specific secret key.
- The secret key has been specified by customer when subscribing to receive push notifications through /v1/subscriptions API. The key is specified in field 'webhookAuthenticationToken' in /v1/subscriptions API. It can be changed at any time by updating the subscription. Values used in this example below:
- Secret key: ad65rujltr9093ijhdkutiyua09döijhsa76d8799w8pqugdfafjdhfkjhadls
- Resulting hash using above example values: 55258f455c0c0427527679626967148475a12d68b19248b69a903a9970b35a02
- Note the resulting hash is the same as in 'v1' on the header parameter.
- Useful tool for calculating the signature: https://www.devglan.com/online-tools/hmac-sha256-online
- The secret key has been specified by customer when subscribing to receive push notifications through /v1/subscriptions API. The key is specified in field 'webhookAuthenticationToken' in /v1/subscriptions API. It can be changed at any time by updating the subscription. Values used in this example below:
- Create a string in format TIMESTAMP.NOTIFICATION_PAYLOAD
- Compare the calculated signature with value given in header parameter
- Get value from 'X-BWAPI-Signature-256' header parameter, field 'v1'.
- Reject the notification if the values are different.
- Else accept the notification.
Notes: Webhook payloads may contain unicode characters in the future. If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8.
Usage scenario 1: Import master data
Basware solutions require a set of master data that replicate the Customer’s business model in Basware. This data is required to enhance the processing of business documents and makes it possible to bring all, or suitable parts of the validation logic to Basware.
As best practice, master data should be maintained in one central place. This data nearly always sits in an organization’s main ERP system. Basware API is designed for importing master data to Basware services from your central master data store(s). Master data can be made available in all supported Basware services.
Posting and updating basic records
The following diagram illustrates data flow for posting master data, such as basic data records and user data, to Basware API.
This is applicable for the following entity types (APIs): Accounts, AdvancedPermissions, AdvancedValidations, ApplicationGroups, Contracts, CostCenters, ExchangeRates, GenericLists, PaymentTerms, Projects, TaxCodes, Vendors.
POST operation must be used when first sending the record to Basware API. Records can be updated using both POST and PATCH operations. Basware recommends using POST operation to also update the records for most cases. PATCH may be more suitable when, for example, the sending system provides only the changed fields within the modified record.
Note that GenericLists API can be used to populate several different lists. The list key needs to be specified as additional parameter for this API.
Usage scenario 2: Import external purchase orders for Order Matching
In order matching a purchase order, purchase order line, or a goods receipt is linked to an invoice or invoice line. Basware API supports importing external Purchase orders from customer systems to order matching. Purchase orders, purchase order lines and goods receipts can be imported and updated using Basware API.
These orders need to be fully processed, approved, and marked received in external systems. These orders are called matching orders and they are used only for automatic matching to received invoices. Creating, approving and sending orders can be also done in Basware P2P using "Purchase" module, which has another set of APIs to integrate the purchasing process with external purchasing systems (see section "Usage scenario 4: Import and export procurement data").
Posting and updating matching orders
The following diagram illustrates data flow for transferring and updating order data for use in invoice matching. Purchase orders from external systems are received through the MatchingOrders (order headers) and MatchingOrderLines (order lines and goods receipts) API entity types.
Order header needs to be received before the order lines are sent. Both order headers and order lines can be updated through API when they are changed, for example when changing requested delivery date or when items have been received.
Order data validations
There are validations performed on order data. Expand below section to list the validations.
Below diagram describes the main flow in terms of invoice status transitions in AccountingDocuments API.
Below diagram describes the available statuses in exception situations. Some of the exception statuses are currently reserved for future use. These are in grey and there is no interaction path leading to those statuses at the moment. Retransferring an invoice from P2P will start the invoice process again as in the main flow above. Note: If a prebooked invoice is returned, prebook cancellation may need to be triggered in ERP system from 'WaitingToBeReturned' status. Most returned invoices are reprocessed and retransferred again to ERP.
The following diagram illustrates the data flow for retrieving prebooked or approved invoices (AccountingDocuments) from Basware P2P to accounting and handling related response messages.
Usage scenario 4: Import and export procurement data
The procurement subset of APIs is used to integrate Basware Purchase with external purchasing systems. These APIs are not used to import orders for matching. For matching please see Usage scenario 2: Import external purchase orders for Matching. Basware Purchase handles the procurement process. It allows users to approve the purchase requisition, sends created order(s) out to supplier(s), handles any changes done in ordering phase and allows documenting that goods have been received. Orders created in Basware Purchase are also automatically available for invoice matching along with the documented goods receipts.
Procurement data integrations scenarios
- Basware API currently supports importing purchase requisition draft(s) to a specified owner on valid organization. The imported data is pre-validated by Basware Purchase making sure that document contains sufficient data required by purchase process setup. Purchase requisition can contain lines to many suppliers. Result of requisition approval process (requisition approved or cancelled) can be retrieved from Basware API as an exported purchase requisition.
- Basware API also supports importing purchase orders. Purchase orders (single supplier) are already approved before importing so they bypass approval process and are automatically sent to supplier.
- Basware Purchase supports contract based purchasing. Contract metadata can be imported through Basware API contract import. Contracts link buyer and supplier in requisition.
- Contract metadata can be exported along with total contract spend through exported contracts API. Individual spend events linked to contracts are available through exported contract spends API. The API exports spends of invoices, spend plans and purchase orders against contracts. Spend events of matching orders are not collected separately but they are included in the invoice spends. These exports are currently available only for contracts created through contract import API.
- Orders sent to suppliers can be exported from exported purchase orders API. Whenever the order status changes, the data in API is also updated.
- Basware API exported purchase orders also include goods receipts when they are registered in Basware Purchase. The goods receipts can originate from Basware API goods receipt import or Basware Purchase goods receiving UI action.
Below picture illustrates available order and requisition document flows. The operations between P2P and purchasing system are performed using Basware API.
Below diagram illustrates document flows for contract documents. The operations between P2P and contracting system are performed using Basware API.
APIs for importing procurement data:
Importing procurement data is done in similar manner as master data imports. See Usage scenario 1: Import Master data for more details.
APIs for exporting procurement data:
Exporting procurement data is done in a similar manner to invoice transfer (Usage Scenario 3: Prebook and transfer invoices to Accounting). Exported data is made available in the exportedPurchaseRequisitions/ exportedPurchaseOrders / exportedContracts / exportedContractSpends APIs. Export is confirmed by sending an acknowledgement response. Documents which have been acknowledged are marked as 'Exported' and can be filtered out from the next get request.
Usage scenario 5: Error handling and monitoring
You can check request status from end-systems (which receive data asynchronously) through ‘requestStatus’ API. When you POST records to Basware API, the posted data contents are schema validated on API layer and then distributed asynchronously to one or more target system(s).
In case an error occurs when target system(s) process the record, it will be returned through 'requestStatus' API. This API can be queried to check status of a request POSTed to Basware API. Errors returned by target systems are typically data validation errors that cannot be validated on the API layer. Examples of such errors would be "Company not found in target system" or "Cannot resolve username 'JOHNSMITH' to a valid purchase requisition owner". You can choose to query only errors or also success' responses. Retrieving only the errors should be enough for most use cases. Success responses indicate that the request has been succesfully processed in all of the target systems. If this does not occur within three hours, an error response is returned.
There is also an older 'errorFeedbacks' API, which returns only errors from P2P ('success' responses are not available). The 'errorFeedbacks' API is likely to be deprecated at a later time. There will be a 12 months notice period before eventual deprecation. Currently both APIs are functioning side by side and are returning same errors.
Retrieving request status messages from requestStatus API
Do a GET to 'requestStatus' API in order to retrieve target system processing status(es) for a POSTed request. Most often the request status response will be available within less than one minute. There are some conditions, such as a heavy initial data loads, where this can take longer. If there is no response from a target system within two hours, the request is set to ’Error’ status automatically. Checking this is done hourly, so max time until timeout is just below three hours.
Request status is shown as 'error' if one or more of the POSTed records could not be imported to one or more of the target systems. Note that you need to query the API separately for both 'success' and 'error' statuses. If parameter 'status' is not used in the GET requestStatus query, the API defaults to returning only messages which have received 'error' status. Basware recommends following ways to programmatically query the API.
Option 1: GET by status + acknowledge
- Get by statuses: 'error', 'success'.
- This needs to be done in two GET requests.
- POST acknowledge for all requestIds (to which status response is received)
- Acknowledged status responses are no longer offered on the next GET request.
- Acknowledging changes the status: 'Error' -> 'AcknowledgedError', 'Success' -> 'AcknowledgedSuccess'.
- Repeat from step 1.
Option 2: GET by lastUpdated timestamp.
- GET with 'lastUpdated' timestamp
- Include a stored 'lastUpdated' timestamp in GET request. Get by statuses: 'error', 'success'.
- This needs to be done in two GET requests.
- Store the 'lastUpdated' timestamp locally.
- Store the latest 'lastUpdated' timestamp separately for 'error' and 'success' statuses.
- Repeat from step 1.
Option 3: Get by requestId
- Save the returned requestId when doing a POST/PATCH request to Basware API
- RequestId is returned as a header parameter in response message.
- Query the API using the requestId until a response is received.
Basware recommends doing GET requestStatus 1 minute after sending a request. If several requests are sent over time, you can do GET requestStatus once a minute until the last request has been sent. It's also a good practice to additionally poll requestStatus API every 10..60 minutes to receive responses for potentially long-running requests. If status responses to all request have been received, this polling can be stopped until a new request is sent to Basware API.
[Legacy] Retrieving error messages from errorFeedbacks API
Note: The 'errorFeedbacks' API has been replaced by 'requestStatus' API and is likely to be deprecated at a later time. There will be a 12 months notice period before eventual deprecation. Currently both APIs are functioning side by side and are returning same errors.
In case an error occurs while using an API an error message is returned either in the API response message or through the ErrorFeedbacks API.
Errors from data validation in Basware API are returned immediately in the API response. These are mainly errors resulting from data structure validation and simple validations on data values.
Errors occurring when data is distributed from Basware API to the receiving Basware systems are returned asynchronously through the ErrorFeedbacks API. These include errors from validations performed in the receiving systems.
The following diagram illustrates data flow for receiving error messages.
Recommended practice is to query the errorFeedbacks API using the timestamp of the last error that has been retrieved. This will return any new errors that have occurred since the last time errors have been fetched. Errors will become available in the API at the same time as the receiving Basware systems process data. Most requests will be processed within 60 seconds. If there is considerable load errorFeedbacks will be available only after the receiving Basware systems have finished processing the data.
Usage scenario 6: Import companies
Importing companies is a network-only usage scenario (companies cannot be imported to P2P). Companies are imported through the 'companies' API. The sequence of API messages is same as when posting master data records.
The company identifier type (field identifiers.schemeId) needs to be specified from available values. Please expand the element under the flow diagram for a table of available values.
Available company identifier types
Expand below section to list available company identifier types used in companies API.
Usage Scenario 7: Import users
Users can be imported through the 'users' API. It is possible to import user(s) to any of the following Basware applications: Purchase-To-Pay (P2P), Supplier portal (network), Supplier Management (network), Network, CloudScan 3.0 (available Q1/2021). The log-in-to-application rights are managed through both 'users' and 'applicationGroups' APIs.
Before importing users, you need to have one or more application Group(s) set up for the users. Application groups provide log-in access to applications when applicationGroups are assigned to users. Each user contains a section specifying which applicationGroups the user has access to. After the application groups are set up, POST user(s) while specifying their assigned applicationGroups.
If some of your end users require access to more Basware systems than other users, you will need to define multiple applicationGroups. An example of this would be access to P2P and Vendor management for some users while most users access only P2P. If you need to define invoice approval rights for users on coding row level, you can also import these using 'advancedPermissions' API.
Note: If you are not importing users from scratch but have an existing P2P tenant where users have already been created, it is still possible to move user maintenance to Basware API. See FAQ article "Can I migrate user maintenance to users API on an existing P2P tenant" for what needs to be taken into consideration.
API testing guidelines
This section aims to support creating your API implementation test plan as well as to provide guidelines on how to test. Please select the scenarios applicable to your implementation onto your test plan, as well as add customer-specific cases. While going through the scenarios, notice which ones you understand and clarify the ones you're not sure about with your consultants.
In a typical integration scenario, there are two or three actors: The customer, a Basware product consultant, and an ERP system consultant. There may also be an external company building the integration. Ideally the integration is verified before customer testing workshop(s) to work from a technical point of view and customer focuses on verifying the business logic of the integration.
As the integration endpoint(s) integrating with Basware API are generally custom built, it is important to verify the applicable scenarios to ensure smooth end-to-end functioning of the overall integration in production.
Use cases for testing
Click on below section(s) to view related test cases. The tables can be copy/pasted to Excel for easy tracking of scenarios.
Common considerations when using Basware API
Please take the following into account in order to achieve smoothly running integrations.
Records are identified for update based on ‘externalCode’ field value
ExternalCode field is present in all record types. This field is used to identify the record to be updated and must be unique per record within an interface (single Account, Cost Center, etc.). More specifically, it must be unique within an Entity Type (Accounts, CostCenters, etc).
Exception to this is GenericLists, where the externalCode must be unique within the target list (specified by the ‘listKey’ parameter).
Maximum length of the externalCode is 36 characters – this needs to be maintained in cases where externalCode is concatenated from other key values, such as [companyCode]_[AccountCode]. The max length of these values combined must not exceed 36 characters.
Inactivating records is done by updating the record
Records are inactivated by updating the record with field ‘active’ = ‘false’. There is no explicit delete (or delete/insert) functionality.
Changed records are forwarded from Basware API to receiving Basware systems
To improve end-to-end integration throughput, received data is compared record-by-record to current data stored in the Basware API. Only records with changed data (compared to what is already in Basware API) are forwarded to receiving systems.
Basware API is primarily designed to receive incremental data changes. It is still possible to send a full data set (such as full list of suppliers) once per night.
GET method returns the latest version of data posted to Basware API
Changes made manually to master data, for example through user interfaces, are not reflected in returned results. GET is mainly intended as a tool to check what has been posted to Basware API.
Number of records per message is limited per API
Consecutive API calls are needed for processing large amounts of records. The record limit varies by endpoint. It is 100 for AccountingDocuments and MatchingOrderLines, 200 for purchaseOrders, PurchaseRequisitions, vendors and 500 for most other endpoints. Please distribute the payload over multiple requests to stay below the respective limits.
Please send the ‘x-amz-meta-continuationtoken’ parameter value returned in previous GET response header as parameter in the GET request header in order to retrieve the next batch of items.
API responses make use of HTTP redirects
Programs using Basware API need to handle redirects either at the application layer or the HTTP layer. Please verify all HTTP request headers are correctly included in the redirected request (the second request after receiving a redirect) including HTTP standards such as Authorization and Date.
JSON parsing requirements for API clients
Basware reserves the right to introduce new non-mandatory fields to existing API data schemas (new fields may be added to Accounts, Vendors, AccountingDocuments, etc). Please make sure your API client is configured to read data from records returned from API using named JSON fields and does not assume the fields come in a predefined sequence of elements.
Basware also reserves the right to send only those fields in API responses, where the field value is not null. Please make sure your API client checks whether the field exists in the received JSON before attempting to parse it’s contents.
The above kinds of changes are considered minor (non-breaking) changes and may be performed by Basware upon discretion at any time. Changes where, for example, a mandatory field is added or removed, or existing field names are changed, are considered major (breaking) changes and will be published under a new API version (‘v2/accounts’ instead of ‘v1/accounts’, etc)
Automatically populated fields in API
The following fields are automatically populated and should be omitted with POST and PATCH requests. They will be visible with GET requests and therefore are present in API schema definitions.
- LastUpdated (All APIs)
- Buvid (Vendors)
Authentication and access rights
Authentication
Basware P2P APIs support following authentication types to authenticate API clients. You can choose the authentication type when requesting Basware to create your API user.
- Basic HTTP authentication
- OAUTH2 (client credentials flow)
All communication is secured by using the HTTPS protocol (HTTP over TLS, TLS version 1.2 or later). You must make all API requests over HTTPS. API requests made without authentication will fail.
Using basic authentication
HTTP Basic authentication relies on passing a username and password along with each API request. The username and password are encoded into the HTTP Authorization request header.
Using OAUTH2 authentication
Basware P2P APIs support the OAUTH2 client credentials flow. The client credentials flow works by first requesting an access token from a dedicated API endpoint /v1/tokens using a client id and client secret (sent as Basic Auth header), then passing that token in subsequent API operations. This token is passed as a bearer token in the Authorization request header. You must specify the API operations permitted by the token when requesting the access token. Tokens have a limited validity time (default 1 hr), after which a new token needs to be requested. Token validity time can be specified while requesting the oAUTH2 credentials from Basware. Minimum allowed token validity time is 5 minutes and maximum is 24 hrs.
There is a separate swagger page for the APIs used to retrieve OAUTH2 tokens. Most integration tools have Oauth2 support built-in for both requesting an access token and using it in subsequent calls.
API operations permitted by an access token are called scopes. Available scopes are limited by access rights granted to API user. When returning requested scopes Basware API will ignore any missing or misspelled scopes. Scopes need to be always specified. For best security, recommended practice is to request only the scope(s) required for each API operation during production use. Multiple scopes can be specified by separating them with a blank space.
- 'read' operation grants access to GET operations
- 'write' operation grants access to POST and PATCH operations
- 'delete' operation grants access to DELETE operations.
Available scopes used are listed below.
Scopes for P2P APIs
accountingDocuments.read accountingDocuments.write accountingDocuments.delete
accounts.read accounts.write accounts.delete
advancedPermissions.read advancedPermissions.write advancedPermissions.delete
advancedValidations.read advancedValidations.write advancedValidations.delete
applicationGroups.read applicationGroups.write
companies.read companies.write
contracts.read contracts.write contracts.delete
costCenters.read costCenters.write costCenters.delete
errorFeedbacks.read errorFeedbacks.write errorFeedbacks.delete
exchangeRates.read exchangeRates.write exchangeRates.delete
exportedPurchaseOrders.read exportedPurchaseOrders.write exportedPurchaseOrders.delete
exportedPurchaseRequisitions.read exportedPurchaseRequisitions.write exportedPurchaseRequisitions.delete
lists.read lists.write lists.delete
matchingOrderLines.read matchingOrderLines.write matchingOrderLines.delete
matchingOrders.read matchingOrders.write matchingOrders.delete
paymentTerms.read paymentTerms.write paymentTerms.delete
projects.read projects.write projects.delete
purchaseGoodsReceipts.read purchaseGoodsReceipts.write purchaseGoodsReceipts.delete
purchaseOrders.read purchaseOrders.write purchaseOrders.delete
purchaseRequisitions.read purchaseRequisitions.write purchaseRequisitions.delete
requestStatus.read requestStatus.write
taxCodes.read taxCodes.write taxCodes.delete
taskStatus.read
users.read users.write users.delete
vendors.read vendors.write vendors.delete
Scopes for push notification APIs
subscriptions.read subscriptions.write subscriptions.delete
tasks.read
Note that scopes need to be separated by a blank space. If copy/pasting multiple lines from the list above, please remove the new line characters. Scope 'taskStatus.read' is required to query status of long-running DELETE operations.
Please make sure to have a mechanism implemented to automatically fetch a new token when your existing token expires. This is especially important for long-running tasks, such as a large initial load of matching orders which may take more time than the max validity time of one token (24hrs). Basware API does not support refresh tokens. You'll need to request a new token each time using the client id and client secret (same way as when getting the token for the first time).
API consumers can validate token signature using metadata from API endpoint /.well-known/jwks.json. Each token returned by Basware API is signed by by one of the public keys listed in the returned payload. The access tokens are returned as jwt tokens. Their contents can be viewed through jwt.io.
If you are currently using basic authentication and want to switch to using OAUTH2, you can request OAUTH2 authenticated API user credentials from Basware. You will receive a new set of credentials. Your existing basic authentication API credentials will continue to work alongside the new OAUTH2 ones. When you have fully made the switch, please request Basware to disable your previous API user credentials.
Access rights
API user access rights control what the user can do when interacting with Basware API. One user can be granted several kinds of access (read, write, delete) to several API endpoints. It is possible for example to have read access to AccountingDocuments and read+write access to Contracts on the same API user. You can request an API user having a combination of read/write/delete access to any of the APIs listed in this manual. If no restrictions are specified API users will have full access (read+write+delete) to all P2P APIs. Changes to API access rights will take effect within 5 minutes from making the change.
Available access rights are:
- 'read' grants access to GET operations
- 'write' grants access to POST and PATCH operations
- 'delete' grants access to DELETE operations.
For full access, each of the above needs to be granted to user. Write alone does not grant access to GET operations and delete alone does not grant access to GET/POST/PATCH.
If the API user uses OAUTH2 for authentication, there are two levels of granting access. The first level is on the API user, specifying what access is granted overall for the user. The second level is controlled by the customer when requesting scopes on OAUTH2 access tokens. The scopes on the token determine which API operations are allowed when passing the token. If scopes are requested to API operations which is not granted to an API user, such scopes will not be granted through access tokens either.
Common scenarios where access restrictions are needed are:
- Restricting access for technical partners, who GET/POST data only to one API, such as Contracts.
- Restricting access for a reporting integration, which for example is only allowed to GET records
API response codes
The various response codes are outlined in the API definition per endpoint and method. Overall API response guideline:
- 200/OK: Credentials validated, task executed successfully
- 302/Redirect: Request redirected
- 404/Not Found: Credentials validated, that particular data item does not exist (e.g. unknown Account)
- 403/Forbidden: Credentials invalid
- 405/Method Not Allowed: Typically occurs on POST Acknowledge, when the invoice has been already acknowledged. Each invoice can be acknowledged only once.
- 411/Length Required: URI is not correct, check for typos (case-sensitive). This usually occurs on POSTs.
- 502/Bad Gateway: URI or endpoint does not exist, check for typos (case-sensitive). This usually occurs on GETs
API Versioning
Every time there is a backwards-incompatible change to the API, a new major version will be released. This major version is part of the URL path. The current major version is v1.
Unless informed by our technical support department that we are discontinuing support for a particular API version, you do not need to switch API versions. We will let you know at least 12 months in advance if an old API version is to be deprecated.
Major change
Change that requires changes from the API consumer before the new version can be taken into use. This change would for example be a change to existing fields or adding new mandatory fields.
Minor change
Minor change is a new version of the API that is backward compatible and does not require changes from the API consumer. Minor change would consist of for example adding a new non-mandatory field. Please make sure your API client accepts new non-mandatory fields.
Fair use practices
Data import APIs
Data import APIs are intended only for importing data from Customer systems to Basware systems. Data imports are one directional, APIs will not reflect any changes done in Basware P2P.
Main use cases
- Import new data entities (Method: POST)
- Update existing data entities (Method: PATCH/POST)
Development phase / Supporting use cases
- Getting data entities by external code (Method: GET) – This use case is mainly intended for development phase usage. Not to be used as part of production usage.
- Deleting data from API layer – This use case is mainly intended for development phase usage. Not to be used as part of production usage.
Posting all entities vs changed entities
Best practice is to update entities one by one as they change as opposed to batch operations. If batch operation (posting all entities, not only changed ones, every time) is used then that should be done infrequently. Optimal frequency depends on how many data entities there are in total and should be discussed with Basware especially if there are very high number of entities
Invoice transfer APIs
Invoice transfer APIs are meant for transferring invoice data to ERP system when an invoice is ready for payment. The process includes polling the AccountingDocuments API for new invoices, fetching invoices and posting transfer and payment responses.
Polling for invoices that are ready for transfer
- GET with status ‘ReadyForTransfer’ from AccountingDocuments API
- It is recommended to use one polling process only to avoid duplicate requests
- Polling frequency best practice is once per minute
Rate limits for APIs
The API platform has been built to scale up and down automatically. Sudden peaks in usage can potentially cause timeouts as it may take a moment for the platform to scale up. Please avoid very high concurrency especially when starting an integration flow. Please ensure you have retry mechanisms in place to handle any failed requests.
We may temporarily or permanently block access if you are calling the API too frequently or you are requesting an unreasonable amount of data in a short time period. The limits should only affect scripts that are malfunctioning or attempting to make too many requests in parallel.
Update frequency for Matching Order Lines
- Do not POST or PATCH updates to the same MatchingOrderLine more often than every 10 seconds.
Release notes
Release notes are updated after API release to production.
| Release to production | API | Change category | Notes | Type |
|---|---|---|---|---|
| 20.8.2020 | v1/matchingOrderLines | Data validation change | Ignore deleted goods receipts when validating PO line quantities | Bug fix |
| 20.8.2020 | v1/Users | Other | Password field is no longer returned in API responses | Bug fix |
| 17.9.2020 | v1/vendors | New fields | Added new non-mandatory fields vendorClass, deliveryLocation and orderingMessageLanguage | New feature |
| 17.9.2020 | v1/errorFeedbacks | Other | ErrorFeedbacks API returns messages in correct order when not using lastUpdated -parameter | Bug fix |
| 1.10.2020 | v1/purchaseGoodsReceipts | Data validation change |
Validate correct set of field are posted for both standard and reverse GRs. New validation: If field 'referenceGRDocumentExternalCode' doesn’t have a value, then:
|
New feature |
| 19.10.2020 | - | Swagger update |
Updated Swagger documentation
|
Documentation |
| 19.10.2020 | v1/exportedPurchaseRequisitions | New API | Introduced new API for exporting purchase requisitions from Basware P2P. | New feature |
| 26.10.2020 | v1/purchaseRequisitions | Data validation change | Increased max number of purchase requisition lines from 100 to 200. | New feature |
| 07.12.2020 | v1/vendors | Data validation change | Increased max length of 'groupName' field (in customFields block) to 500 chars. |
New feature |
| 07.12.2020 | v1/users | Data validation change | Increased max length of 'externalGroupCode' field (in groups block) to 260 chars. | New feature |
| 14.12.2020 | - | Swagger update |
Updated Swagger documentation
|
Documentation |
| 20.1.2021 | - | Swagger update |
Updated Swagger documentation
|
Documentation |
| 20.1.2021 | - | Other |
Made Basware APIs available in Canada region (api.ca.basware.com) |
New feature |
| 25.1.2021 | v1/applicationGroups | Data validation change |
Added CloudScan to list of applications supported in applicationGroups. |
New feature |
| 3.3.2021 | v1/requestStatus | New API |
Introduced new API for tracking request status in target systems, supporting both 'error' and 'success' responses. |
New feature |
| 17.3.2021 | v1/genericLists | Data validation change |
'Inherit' field is no longer mandatory. |
Bug fix |
| 17.3.2021 | v1/purchaseGoodsReceipts | Data validation change |
'lineReceivings' block is now mandatory. Added API validation as field is required by target system (P2P). |
Bug fix |
| 16.4.2021 | v1/genericLists | Data validation change |
Added target list specific field validations. |
New feature |
| 27.4.2021 | v1/users | Other |
Fields not included in PATCH method payload no longer get default values. |
Bug fix |
| 5.5.2021 | v1/contracts | New fields |
Added new non-mandatory fields orderSpend, spendPlanSpend, invoiceSpend. |
New feature |
| 12.5.2021 | v2/projects | New API |
Released v2/projects API. |
New feature |
| 12.5.2021 | - | Swagger update |
Updated swagger to OAS3 specification. |
Documentation |
| 10.6.2021 | - | Swagger update |
Fixed functionality to POST requests through Swagger page |
Bug fix |
| 22.6.2021 | - | Developer site update |
Updated API developer site with
|
Documentation |
| 4.8.2021 | v1/accountingDocuments | New fields |
Added field 'OriginService' to accountingDocuments API. |
New feature |
| 14.8.2021 | v1/subscriptions, v1/tasks | New API |
Enabled pilot use of push notifications APIs. |
New feature |
| 16.8.2021 | - | Other |
Deprecated usage of TLS1.0/1.1. |
Other |
| 28.8.2021 |
v1/purchaseOrders, v1/purchaseRequisitions, v1/exportedPurchaseOrders, v1/exportedPurchaseRequisitions |
New fields |
Added support for blanket orders to purchasing APIs. New fields: validityPeriodStartDate, validityPeriodEndDate, orderType, releaseOrdersRequired, hidePricesFromSupplier, parentOrderNumber, parentOrderexternalCode, parentOrderExtNumber, parentOrderLineExternalCode. |
New feature |
| 6.9.2021 |
v1/purchaseRequisitions |
New fields |
Enhanced ways owner of requisition can be identified: Added new field "ownerExternalCode". Made existing field "ownerLogin" not mandatory. Added validation that at least one of the following owner -identifying fields are not empty (same validation as used in purchaseOrders API): ownerExternalCode, ownerLogin, ownerEmail. |
New feature |
| 6.9.2021 |
- |
Swagger update |
Minor clarifications based on consultant feedback. |
Documentation |
| 14.9.2021 |
v1/contracts, v1/purchaseOrders, v1/matchingOrderLine, v1/lists |
Other |
Fixed bug introduced by a previous enhancement where PATCH operation reset values for those enum fields which were not included in the PATCH payload. |
Bug fix |
| 23.9.2021 |
v1/accountingDocuments, v1/matchingOrderLines, v1/contracts |
New fields |
Added new field 'contractNumber' to accountingDocuments and matchingOrderLines APIs. Changed length of 'referenceCode' field in contracts APi from 100 to 255 chars. |
New feature |
| 28.10.2021 |
v1/requestStatus |
Other |
Fixed handling of lastUpdated field value in requestStatus API in the case when a request times out. |
Bug fix |
| 3.11.2021 |
v1/purchaseOrders, v1/exportedPurchaseOrders, v1/purchaseRequisitions, v1/exportedPurchaseRequisitions |
New fields |
Added field 'otherOrderingEmail'. Updated descriptions of ordering email related fields. |
New feature |
| 12.11.2021 |
v1/requestStatus |
Other |
Reliability improvement to requestStatus of concurrent API operations done to same record. |
Bug fix |
| 18.11.2021 |
v1/purchaseOrders, v1/exportedPurchaseOrders, v1/purchaseRequisitions, v1/exportedPurchaseRequisitions |
New fields |
Added new fields 'CountrySubEntity', 'CountrySubEntityDescription' to the address blocks in P2P Purchase APIs. |
New feature |
| 14.12.2021 |
v1/tokens |
New API |
Added OAUTH2 support for Basware P2P APIs. |
New feature |
| 5.1.2022 |
- |
Swagger update |
Made following unused fields hidden: GenericLists, Accounts, Costcenters APIs -> 'parents' -block. Users API: 'spendingLimits, PurchaseManagerUserLocations, PurchaseManagerModuleAccess, PurchasingGroups' -blocks. GenericLists API: 'inherit'. Minor documentation updates based on feedback. |
Documentation |
| 7.4.2022 |
v1/exportedcontracts, v1/exportedContractSpends |
New API |
Introduced new APIs for exporting contracts and contract spends from Basware P2P. |
New feature |
| 14.4.2022 |
v1/exportedPurchaseRequisitions |
Other |
Field 'sendingMethod' made not mandatory in 'orderGrouping' block. |
Bug fix |
| 26.4.2022 |
- |
Swagger update |
Show oAuth2 as a supported authentication method. Small clarifications to documentation. |
Documentation |
| 4.5.2022 |
v1/accountingDocuments, v1/purchaseOrders, v1/exportedPurchaseOrders, v1/purchaseRequisitions, v1/exportedPurchaseRequisitions |
Other |
Improved handling of HTTP redirects. Feature is manually activated per tenant. |
New feature |
| 9.5.2022 |
v1/users |
New fields |
Added new field 'accessEnabledLogin. |
New feature |
| 11.5.2022 |
v1/accounts |
New fields |
Added new fields 'taxCode', 'text1' - 'text5'. |
New feature |
| 24.5.2022 |
v1/taxCodes |
New fields |
Added new field 'taxGroup', removed validation on 'taxPercent' and 'taxPercent2'. |
New feature |
| 13.6.2022 |
- |
Other |
Introduced new API redirect method by default for new API customers. The redirect now points to a Basware domain. No change to redirect method for existing customers. |
Other |
| 14.6.2022 |
v1/vendors |
New fields |
Added new field 'linkedBbanOrIban' to allow linking IBAN to BBAN when importing account data to P2P. |
New feature |
| 17.6.2022 |
v1/accountingDocuments |
New fields |
Added new fields 'text84' and 'text85' to 'codingRows' block. |
New feature |
| 18.6.2022 |
v1/accountingDocuments |
Bug fix |
Added limit to store only last 100 responses per accountingDocument. |
Bug fix |
| 3.8.2022 |
- |
Swagger update |
oAUTH2 URL in swagger dynamically pointed to correct API environment. |
Bug fix |
| 10.8.2022 |
- |
Swagger update |
Drop-down menu added to change between swagger instances. |
New feature |
| 31.8.2022 |
v1/users, v1/vendors, v1/purchaseRequisitions, v1/purchaseOrders, v1/purchaseGoodsReceipts, v1/exportedPurchaseRequisitions, v1/exportedPurchaseOrders |
Bug fix |
Relaxed email validation in Basware API to allow special characters such as !#$%&'*+-/=?^_`{|}~ in email addresses. |
Bug fix |
| 21.9.2022 |
v1/users, v1/vendors, v1/purchaseRequisitions, v1/purchaseOrders, v1/purchaseGoodsReceipts, v1/exportedPurchaseRequisitions, v1/exportedPurchaseOrders |
Bug fix |
Fixed regression issue related to above where some of the emails were not validated correctly. |
Bug fix |
|
Entity type |
Named structured types with a key. They define the named properties and relationships of a record. Examples: accounts, costCenters, matchingOrderLines. |
|
Record |
Instances of entity types (e.g. account, opportunity). |
|
Accounting system |
Computer program used for keeping accounts. Commonly included in an ERP system as a module |
|
ERP |
Enterprise resource planning (ERP) is defined as the ability to deliver an integrated suite of business applications. ERP tools share a common process and data model, covering broad and deep operational end-to-end processes, such as those found in finance, HR, distribution, manufacturing, service and the supply chain. |
|
Basware P2P |
Basware Purchase-to-Pay, in this manual refers to Basware Purchase-to-Pay solution. |
|
Basware AP Automation |
Accounts Payable Automation solution. Part of Basware P2P. |
|
Basware Purchase |
Basware Purchase solution. Part of Basware P2P. |
