Basware Open Vault API Manual

With Basware Vault, customers can set up one or many vaults for storing invoices according to pre-configured settings and for a selected period of up to 15 years. There can be separate vaults for example for different business units. The service can automatically store for example structured invoices files, invoice image files, invoice attachments, and digital signatures/seals. It can also store certain invoice metadata to enable a swift search.

Laws around the world regulate the retention of business records, such as invoices, whether they are on paper or in electronic form. Countries, and for example the European Union, have rules on how and for how long such records must be retained. Basware Vault helps customers to meet these requirements in the supported countries. It also helps to confidently move to automated e-archiving, and thus reach the full benefits of e-invoicing.

With Basware Vault, you can follow the archiving requirements in the countries supported by the service. This frees from the setup and management of a variety of country-based archiving services. It also helps to improve and manage compliance with varying local archiving requirements. The service's compliance management and the technical service layers free you from a large part of the burden. It adds automation to your in-house archiving and compliance management processes.

The purpose of this manual is to describe the Basware API integration capabilities for Vault API 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 systems:

• Basware Network
• AP Automation and Procurement
• Basware Vault
• Basware Supplier Management

Vault APIs are available only in the EU region. Separate environments are available for test and production systems.

Vault API is an upload method to the vault, and the vault internal processing has multiple steps as described in the following picture.

The following APIs are available for uploading the invoices to Basware Vault.

API methods and fields

Detailed documentation for available methods and field sets for each API are described in the Open Vault API 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.

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.

To upload the document with the Vault API, you must have Vault API credentials and a vault ID. Both are created by the Basware consultants. The Vault API credentials authenticate the API call and the vault ID defines which vault the document gets archived to.

1. Make sure that the document that is to be archived is in a ZIP file and is ready to be uploaded. All the files belonging to the particular invoice must be zipped to be uploaded.
2. POST document metadata to the Vault API documents endpoint. This will return a pre-signed URL as well as an identifier (bumId) for the document. Please save the bumId identifier for checking the status of the archival task.
3. PUT the zip file to the pre-signed URL returned in step 2 to upload the actual business document.

When the ZIP file is uploaded, the file is then in the queue to be archived.

If you upload multiple metadata in the first call, you will get multiple BUM IDs and pre-signed URLs to upload the corresponding ZIP files. Make sure to keep the pre-signed URL(s) until the file(s) are uploaded. The pre-signed URL are valid for 15 minutes. Please also retain the bumId so you can verify the status of the uploaded documents.

Vault UI can also be used to search uploaded documents using the posted metadata as well as the returned bumId.

Notes on uploading the document ZIP file:

• API client issues a second PUT request using the provided archiveFileURL URL and fields.
• Use Content-Type "application/octet-stream". Optionally, specific types such as application/zip can be used in the request depending on the file type.
• You'll get a "200 OK" response code if the upload was successful, or with an appropriate error response code if something went wrong. See error responses in https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html.

You can get the status of the document that you have uploaded to be archived using the bumId document identifier. Archiving is a process that has multiple operations before the document is archived.

Above example returns the status of a single document. You can also get status of the last 500 uploaded documents through using GET /v1/vaults/{vaultId}/documents/status. The process is same as described above.

Please take the following into account to achieve smoothly running integrations.

JSON content to be preserved for the searching of uploaded documents in Vault UI

When you are uploading the JSON content in the first POST call, the values will be stored, and you can use those values to search the document in Basware Vault. Access to Basware Vault is provided separately by the Basware consultant. 

Pre-signed URL and BUM ID to be used to the corresponding document JSON posted

Pre-signed URL and BUM ID correspond to the particular clientUUID, so it is very important to preserve those for making any relational mapping and to upload the documents / ZIP files correctly. 

Status of the single documents can be updated late as they are in queue to be archived

Archiving is a process that has a lot of steps, and getting a response for the status API can take hours if there is heavy upload that is pushed to the vault. 

JSON validation of the content

Before posting the metadata for the document to be archived, make sure that all the JSON content is valid and as per the schema. 

Authentication

Basware Vault APIs support the following authentication types to authenticate API clients. You can select the authentication type when requesting Basware to create your API user.

• Basic HTTP authentication

All communication is secured with 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.

The various response codes are outlined in the API definition per endpoint and method. Overall, API responses:

• 200 OK: Credentials validated; task executed successfully.
• 403 Forbidden: Invalid credentials.
• 400 Bad data: Data does not belong to the mentioned API schema.
• 502 Bad Gateway: URI or endpoint does not exist, check for typos (case-sensitive). This usually occurs on GETs.

Every time there is a backward-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 v. 1.

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 that your API client accepts new non-mandatory fields.

Vault APIs

Vault document upload API is intended only for uploading data from customer systems to Basware solutions. Data upload is one directional. You can get the status of the document to be archived. 

Main use cases:

• Upload document to be archived (Method: PUT/POST)
• Check status of document(s) uploaded to be archived (Method: GET)

Mass upload

You can upload multiple document JSON files to get the multiple BUM IDs and pre-signed URLs. These URLs can be used to upload the ZIP file separately corresponding to the issued clientUUIDs by yourself. 

Upload ZIP file size

The average file size of documents archived (including attachments) must not exceed 1 MB. Individual archived files must not exceed 100 MB. If the average size limit is exceeded, Basware reserves the right to invoice for the overage. The average file size is calculated by dividing the total storage space consumed by transactions and archived within a calendar year by the total number of transactions archived by the customer within a calendar year. The resulting storage consumption excess is then summed and divided by the average file size maximum (1 MB). The resulting overage result is invoiced according to the applicable price list of vault transactions. 

Release notes are updated after API release to production. 

Release notes are available from December 2022 onward.

Vault: Basware Vault is the service provided by Basware to archive the document.

Vault ID: Vault ID is the vault which is created for your organization setup in Vault and provided by a Basware consultant.

System user: User provided by a Basware consultant to authenticate and use the vault API.

BUM ID: Basware unique identifier which is unique per single zip uploaded. This is provided by Basware.

clientUUID: In its canonical textual representation, the 16 octets of a UUID are represented as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters. Use this for archive request correlation.

archiveFileURL: Used to construct the HTTP request to PUT the ZIP material.