Guide to Network APIs

Send and receive invoices through the Basware Network

Basware Network lets you send and receive invoices using the Basware APIs. The Invoices API lets you send and receive invoice data in JSON format. With the Files API, you can send and receive invoice attachments in supported file formats, such as PDF files.

Before you send your first invoice, make sure that you meet all the requirements described in the Network Get Started page

Note that the URL addresses below point to the customer test environment https://test-api.basware.com.

1. Generate a UUID (unique identifier) that identifies the request-response flow of the invoice.

The Files API uses a X-BW-REQUEST-ID value to identify uniquely the request-response flow of an invoice. Use the following command in Linux to issue this UUID:

_REQUEST_ID=`uuidgen | tr [:upper:] [:lower:]`

2. Generate a UUID for the business document's identifier (BUMID)

Use the following command in Linux to issue a UUID for the BUMID:

_UUID=`uuidgen | tr [:upper:] [:lower:]`

3. Upload the invoice/invoice attachment to Basware Network

The file that is being uploaded to Basware Network in this example is invoice1.pdf.

Replace the system account and password used below with with your details.

curl -v -X POST -u "<system-account>:<password>" --header "X-BW-REQUEST-ID: $_REQUEST_ID" --header "Content-Type: multipart/mixed" -F "request={\"bumId\":\"$_UUID\",\"fileType\":\"imageFile\"};type=application/json" -F "file=@invoice1.pdf" "https://test-api.basware.com/v2/files"

You will receive a response for the previous command in the following format:

{ "version": "1.0" , "fileId": "d864fc85d1704cabb23553e8" }

Be sure to store the fileid value from the response that you receive.

1. Create a JSON request file that contains the details of the invoice

Prepare a JSON file. In this example, the filename of the JSON file is postSimpleInvoiceExample.json. Include the fileId value from the previous step in the refId field in your JSON file:

"fileRefs": [ { "refId": "d864fc85d1704cabb23553e8" } ],

2. Send the invoice using POST /invoices/{bumId}

curl -v -X POST -u "<system-account>:<password>" -k --header "Content-Type: application/json" --header "X-BW-REQUEST-ID:$_UUID" --data "@postSimpleInvoiceExample.json" https://test-api.basware.com/v2/invoices/$_UUID

Receiving invoices through the Basware Network is simple. First, you need to fetch notifications about invoices that have been sent to your company. If there are notifications about unread invoices waiting to be delivered to your company in the Basware Network, you can fetch the contents of these invoice contents with the Invoices API and attachments using the Files API.

1. Generate a UUID (unique identifier) that identifies the request-response flow of the invoice

The Basware Network API uses a X-BW-REQUEST-ID value to identify uniquely the request-response flow of an invoice. Use the following command in Linux to issue a UUID:

_REQUEST_ID=`uuidgen | tr [:upper:] [:lower:]`

2. Fetch notifications about new invoices

Use the following command in Linux to fetch all notifications:

curl -v -X GET -u "<system-account>:<password>" --header "X-BW-REQUEST-ID:$_REQUEST_ID" https://test-api.basware.com/v1.1/notifications?type=DocumentsReceived

You will receive the following response for this command:

{ "hasMoreItems":false, "notifications": [ { "bumid": "7de91997-70de-51b8-84e1-41cc473eeee7", "documentType": "Invoice", "acknowledgementId": "7de91997-70de-51b8-84e1-41cc473ebeef", "responseCode": "TechnicalInformation", "responseType": "BCN:responsecode-v1", "actionCode": "Received", "actionType": "BCN:actioncode-v1", "notificationCreated": "1334578485000", "description": "Business document has been received", "links": [ { "rel": "businessDocument", "href": "https://test-api.basware.com/v2/invoices/7de91997-70de-51b8-84e1-41cc473eeee7", "method": "GET" }, { "rel": "notification", "href": "https://test-api.basware.com/v1.1/notifications/7de91997-70de-51b8-84e1-41cc473ebeef", "method": "DELETE" } ] } ] }

The response contains a bumid value and an acknowledgementId value. The bumid is used to identify the invoice linked to the response and the acknowledgementId is used to acknowledge the invoices as processed on your side. Please store both values. In the following step, the bumid is stored in a $_BUMID variable and acknowledgementId is stored in $_ACKID variable.

1. Fetch the invoice

Use the following command in Linux to retrieve the contents of an invoice:

curl -v -X GET -u "<system-account>:<password>" --header "X-BW-REQUEST-ID:$_UUID" https://test-api.basware.com/v1/invoices/$_BUMID

If the invoice contains attachments, the response will contain file references like the ones shown in the following example:

"fileRefs": [ { "refId": "539a78446842ed5025466947d", "fileType": "imageFile" }, { "refId": "539a785684ede2025415913b", "fileType": "attachmentFile" } ],

The refId value is the attachment file’s identifier and the fileType value tells you the type of the attachment. Please store all refId values used on the response that you receive. In the following step, the file reference is stored in a $_FILEID variable.

2. Fetch the file attachments

Use the following command in Linux to download the file attachment, one at the time:

curl -v -X GET -u "<system-account>:<password>" --header "X-BW-REQUEST-ID:$_UUID" https://test-api.basware.com/v1/files/$_FILEID

3. Acknowledge the notification

Once you have processed the invoice, you must acknowledge the notification about the invoice. Use the following command in Linux to acknowledge the notification.

curl -v -X DELETE -u "<system-account>:<password>" --header "X-BW-REQUEST-ID:$_REQUEST_ID" https://test-api.basware.com/v1.1/notifications/$_ACKID