Find answers to Frequently Asked Questions

ExternalCodes for records in Basware API need to meet the following criteria:

  1. They must retain their value when updating records (else data updates will not work)
  2. They most not exceed the field max length (else the record will be rejected by Basware API).

Two common ways are 1) using UUIDs and 2) Concatenating the externalCode from other key values, such as SourceSystem_CompanyCode_PONumber_PORowNumber_GRNumber.

The UUIDmethod requires saving this guid to the sending system.  The second "composite key" method may make integration debugging more straightforward and requires making sure the combined key does not exceed the max length for externalCode -field.

It's up to the customer implementation what is the best way to create them.

Please refer to the error handling section of Purchase-to-Pay API manual.

Please check the errorFeedbacks API. Note that specific kinds of errors can take some minutes to become available in errorFeedbacks API due to internal retry logic. Try to use GET errorFeedbacks with just daterange search, setting the date to one day before your expected error (in case of timezone differences). If this does not resolve your issue, please contact Basware support.

There is a setting in P2P admin, settings section called "Delete existing user groups when importing users". This setting needs to be enabled in order to clear existing user groups during import.

No, each bank account on the vendor needs to be unique.

This typically happens for invoices which have already been acknowledged. API allows acknowledging an invoice only once (unless it is retransferred from P2P). Already acknowledged invoices have 'processingStatus' = 'TransferInProgress'.

Please check that you are sending the x-amz-meta-continuationtoken parameter as a request header parameter. It does not work if it is not sent in header (for example in body).

The x-amz-meta-continuationtoken parameter is preconfigured in our Postman templates. Please try it out through postman using the preconfigured template, that should help spot the difference between how it is set up in the request sent by Postman and sending it in your HTTPS request.

API_RequestId

There is filtering in use for records which are sent unchanged from the last time the record was sent to API. Such records are not forwarded from API to the target systems. Please make a small change to the record manually (such as update the name) and resend, then it will pass the check in API. Alternatively, you can delete the record(s) from API and then post again.

The swagger definition should serve you the same way as WSDL. You can download the swagger here https://api.basware.com/swagger/v1/swagger.json  and then validate the messages against that. However, there is no json schema or WSDL file currently available.

There is no way at the moment to keep changes made manually to records which are updated through the API. An exception to this is the vendors -interface, where some of the interface fields can be configured so API data does not overwrite existing data in P2p. This functionality to vendors -interface is planned to be released in Q3/2020.

Please find a way to update the data fully in your source system, alternatively you could consider creating a separate maintenance table for particular items - please discuss options for you specific scenario with your Basware consultant.

The vendor's default currency is taken from field 'currencyCode' under paymentMeans block. Please make sure default = 'true' on the paymentMeans block with the default currency.
The delete command deletes data from API only, you'll need to manually delete the data from the target system(s). The delete functionality is implemented mainly for manual clean-ups during / after development and does not support deleting the data all the way in target systems. Note in some cases the target systems also have restrictions on deleting the data if there are dependencies to it in other records in the system.
The order header sums are not imported through API. MatchingOrder APIs were built mainly for the new html5 based P2P user interface (Edge), which takes sums from order lines. In silverlight based UI (Workplace) the order sums are not available for API-imported orders. Matching is fully possible using both user interfaces for orders imported through API.

Yes you can. There are some things which need to be taken into account. The most important thing is to update user externalCodes in P2P to have same externalCode values that will be sent for each user through users API. This will enable users API to correcly identify existing users for update instead of creating new users instead. It is important to update existing users instead of creating new ones so the users preserve access to invoices they have processed and invoices they currently have in circulation.

User externalCodes can be updated either manually through the user administration -module in P2P or automatically with more direct access to the system. Basware consultants and delivery partners can update the externalCodes directly in P2P. Note that when importing users through API, the user will be available for a GET operation in users API only after the user has been POSTed to users API.

Please test this procedure in test environment to verify all the details are correctly in place before applying the same in a production environment.

You should create one or more applicationGroup(s). Application groups provide log-in access to applications when assigned to users.

Creating applicationGroup(s) can be done by a one-time POST applicationGroups -operation. The easiest way to do that is to use the preconfigured API call for POSTing applicationGroups. After the application group(s) are created, POST user(s) while specifying their assigned applicationGroup(s). See related P2P API manual article for more information.

Example message returned from users API in this situation:

{
    "requestId": "e3361d63-bc8a-44a4-91f7-1ec4be706074",
    "hasErrors": true,
    "errors": [
        {
            "type": "VALIDATION",
            "code": "SCHEMA_VALIDATION_ERROR",
            "message": "The default application group does not exists for customer 123456"
        }
    ]
}

 

Handling supplier additional data fields (imported in vendors API 'customFields' block) in P2P is controlled by parameter 'DeleteAdditionalDataDuringSupplierImport' (in CMN_TENANT_SETTINGS in P2P).

When true, all existing values for supplier additional data fields are cleared before supplier is imported. When false, existing values are kept which can result in duplicate additional data -entries.

Most likely case is the parameter has incorrect value for your use case. Please check the parameter value and set it to 'true'.

This is an unsupported use case. The invoice needs to be present in accountingDocuments API for the responses to be updated to P2P. You will need to send the response information back through the same channel as was used for originally transferring the invoice.

This typically occurs when GETting data from APIs that use redirects to allow large data payloads (accountingDocuments, exportedPurchaseOrders, etc) and the redirected request includes extra HTTP headers. For the redirected call, the 'Authorization' HTTP header must not be sent. The redirected call is using secure signed URLs with short expiration time.

In Postman this is controlled by a setting called "Follow Authorization Header", having default value false. Sometimes this header is copied from the original request by integration software used. Please adjust the settings of your integration software to not send this header on the redirected request.

It looks like that you have MDD configuration in place for importing the data to Basware Access, but that you do not have a matching Basware Access account (one with the same customer id).

If you plan to use Access, you need to get Production to check the Access provisioning. If you don't plan to use Access, you need to remove or get removed the MDD configuration that synchronizes data to Access. In either case, please contact Basware's SaaS production team.

There are the following options:

  • You can (manually) post a transfer failed / transfer suceeded response to API for the invoice.
  • You can manually cancel process for the invoice in P2P and retransfer it again from P2P
  • You can use the P2P transfer recovery scheduler task with parameter 'IncludeOpenAPIInvoices' = 'True'

This scenario is currently not supported. API does updates only the comment in invoice history log when 'success' = 'false' on transferResponses API.

Basware has conversion tools from specific Excel templates to the JSON format natively used by Basware API. These can be used to load data to API.

Use cases include having relevant test data in the system before API build is complete on customer side or doing initial loads for data which is planned to be maintained manually in P2P. Please ask your consultant to provide these templates.

Yes, this is possible. Please specify the permissions required for your API user and make a request to your consultant / CSM.

The users are created by SaaS production.

You can, but this is not recommended as these are used as parts of an URL in the API's GET operations. If you would need to use these special characters they will need to be URL encoded whenever they are used as parts of a URL or used in query parameters.

Q: I got the above error message when posting users. How should I resolve this?

This error is due to the company on which you're importing the user not being marked as an administrative site in P2P. Make sure the the company to which you are posting the user is marked as an administrative site in P2P. When it is not, users cannot be imported to the company. We have logged an enhancement to return a clear error message also in this situation.

1000 calls in an hour should be fine. However, please avoid updating the same PO within ~5 seconds of the previous update. The interfaces currently lock the entire PO whenever just a part of it is updated. If a new update is received while the PO is locked it will go into delayed retries and it may take considerable time before all updates are processes.

Basware API currently support basic authentication over HTTPS. Oauth2 support (Client credentials flow) is also coming during 2021.

Status 'NotProcessed' commonly occurs due to delta check. If the record contents has not changed since last time it was posted, API skips the record (as is nothing to update) instead of sending it to target systems. Below is an example requestStatus response JSON where this has occurred.

RequestStatus_NotProcessed