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 [Q4/2020] |
| 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) |
| PurchaseOrders (Q3/2020) | Import Purchase Orders to P2P Purchase from an external system | P2P (Purchase) |
| Goodsreceipts (Q3/2020) | Import goods receipts to P2P Purchase from an external system | P2P (Purchase) |
| Contracts | Import contract metadata to P2P Purchase from an external system | P2P (Purchase) |
| ExportedPurchaseOrders | Export purchase orders and GR's from P2P Purchase | P2P (Purchase) |
| ExportedPurchaseRequisitions ( Q4/2020) | Export purchase requisitions 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 error messages from target systems | ||
| ErrorFeedbacks | Error handling. Returns errors asynchronously from Basware receiving systems. | P2P |
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.
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, Contracts, CostCenters, ExchangeRates, GenericLists, PaymentTerms, Projects, PurchaseRequisitions, PurchaseOrders [Q3/2020], GoodsReceipts [Q3/2020] TaxCodes, Users, 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 "Importing and exporting 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.
Usage scenario 3: Prebook and transfer invoice to Accounting
Once an invoice has been approved in P2P, it is routed to AP/finance users for transfer to accounting. In this phase, the invoice and its coding data are transferred to an ERP system for payment. This phase can be configured to be completed automatically.
Prebooking invoices and transferring approved invoices to accounting
Prebooking and transferring invoices from Basware P2P to accounting use AccountingDocuments API. The progress of both activities is shown in 'ProcessingStatus' field.
Invoice is made available for transfer to accounting when it has been approved in Basware P2P. When an invoice is transferred in Basware P2P it becomes available for a GET operation in AccountingDocuments API with status 'WaitingForTransfer'. When a transfer succeeded message is received, invoice status in P2P is changed from “Transfer in progress” to “Processed”.
Invoice prebooking is an optional feature that can be enabled if required. In prebooking invoice data can be made available in the AccountingDocuments API before the invoice is approved. Prebooked invoices require a prebookeResponse message from ERP system. When a prebooked invoice is approved in P2P it will be made available in the accountingDocuments API as an invoice 'WaitingForTransfer'. Invoices can can be sent for prebooking automatically based on configurable rules. Manual selection of invoices to be prebooked is not yet supported.
Invoice transfer consists of the following steps
-
- Get invoice data from the API for prebooking (processing status: WaitingForPrebook)
- Post technical acknowledgement (optional, processing status changed to: PrebookInProgress)
- Post prebook succeeded / failed message (processing status changed to: Prebooked, PrebookFailed)
- Get invoice data from API for transfer (processing status: WaitingForTransfer)
- Post technical acknowledgement (optional, processing status changed to: TransferInProgress)
- Post transfer succeeded / failed message (processing status changed to: Transferred or TransferFailed)
- Post payment information (optional, processing status changed to: Paid)
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
This set of APIs is used to integrate Basware Purchase to 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, i.e. approving the order, sending it out to supplier, and creating the goods receipts. Orders created in Basware Purchase are automatically available for matching.
Procurement data integrations scenarios
-
- Purchase Requisitions can be created through several different methods in Basware Purchase. Basware API currently supports importing purchase requisition data as a draft to a specified owner. The imported data is prevalidated by Basware Purchase before the creation of the draft can start.
- Basware Purchase supports contract based purchasing. Contract metadata can be imported through Basware API.
- Orders and goods receipts can be exported from Basware Purchase. Whenever the order status changes, the data in API is also updated.
- Basware APIs for importing purchase orders, importing GRs and exporting purchase requisitions will be be released during 2020.
APIs for importing procurement data:
-
- contracts
- purchaseRequisitions
- purchaseOrders [Q3/2020]
- purchaseGoodsReceipts [Q3/2020]
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:
-
- exportedPurchaseOrders
- exportedPurchaseRequisitions [Q4/2020]
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 exportedPurchaseOrders API from where it needs to be retrieved. Export is confirmed by sending an acknowledgement response. The acknowledgement response is mandatory. Orders which have been acknowledged are marked as 'Exported' and can be filtered out from the get next request.
Usage scenario 5: Error handling and monitoring
When using Basware API errors from data validation are returned immediately in the API response. These are mainly errors resulting from data structure validation and simple validations on data values.
Sometimes errors may be occurring in the Basware receiving system that prevent data updates to the end system, Basware P2P for example. These are most commonly errors from additional validation performed in the receiving systems. These errors are not available immediately in the API response, due to asynchronous data distribution from API to Basware end system, but are made available in the Basware API through a separate ErrorFeedbacks API.
Retrieving error messages from errorFeedbacks API
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 30 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
This is a network-only usage scenario (companies cannot be imported to P2P). 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.
