Guided Tour: Transaction Services

📘
Transaction Services are used for creating or parsing electronic business documents with JSON metadata, which abstracts the underlying XML (or EDI) technical specifications.

Documents are validated before delivery. Errors are returned if submitted data is inconsistent, but Unimaze will otherwise guarantee that documents are in compliance with syntax and business rules.

For working with raw XML, please refer to Guided Tour: Messaging Services.

Sending electronic documents

Create a random unique identifier (GUID) and store internally. This will become the message identifier (:mid), passed as the messageId parameter when you submit the document.
Prepare the JSON message and submit the business documents using, e.g.:\
- POST /transactions/submit-invoice
- POST /transactions/correct-with-credit
- POST /transactions/submit-order
  When including additional attachments in the message, ensure the parameter more is set to true. Otherwise set it to false to trigger processing and delivery of the message.
Optionally, stream a binary payload as attachment (e.g. timesheet, product description) using:\
- POST /messages/:mid/documents
  Send the file as the raw request body with Content-Type: application/octet-stream. The contentType query parameter is the file's own MIME type; supported are images, PDF, XLSX, CSV and plain text files. Set more to true or false depending on if processing can be triggered or not. If desired, set embedDocument to true.
Follow the state of the message through webhooks: Unimaze sends a messageStatusChanged event each time the delivery status changes. The states delivered (delivered to the receiver), failed (there was an error) and parked (manually parked as handled) are final states.
To check the state at any time, for example if you may have missed an event, use:\
- GET /messages/:mid/status
  This gives both delivery information and message handling traces.
Store the referenceId parameter for each document for later displaying the document(s), see Receiving electronic documents below.

Getting notified of incoming documents

To keep incoming documents from piling up in the inbox, set up a webhook endpoint for inbound messages. When a message is ready to be fetched, Unimaze sends your endpoint a deliveryNotified event. Fetch the documents into the ERP system as described below.

Once a day, also run a safety-net check with GET /messages?status=pendingdelivery&transfer=inbound, and handle any message that is still pending in the same way.

Fetching pending messages on a schedule instead (polling) is the legacy approach, supported for existing integrations. See Polling (legacy).

Receiving electronic documents

When a deliveryNotified event arrives, read the message from it: messageId is the unique identifier (GUID), and data is the message envelope, with the action parameter and the referenceId of each document.
If validationStatus of a message is not approved, it has one or more validation errors. Either mark the message as delivered or parked so that it will be removed from the list of pending incoming messages. If you like to fetch validation errors or warnings use:\
- GET /messages/:mid/validations
Based on the action parameter, get business document data in JSON format using:\
- GET /transactions/submit-invoice?messageId=:mid
- GET /transactions/correct-with-credit?messageId=:mid
- GET /transactions/submit-order?messageId=:mid, etc.
  Optionally, get any attached documents and store them if needed:\
- GET /messages/:mid/documents/{nameOrIndex}
Change the state of the message to delivered using:\
- POST /messages/:mid/mark-as-delivered
  Generally, marking the message delivered should be done as soon as possible (within minutes or hours).
To allow a user to view the document or any of the attached documents, use:\
- GET /messages/display/:referenceId (optionally add the ?lang=<language> parameter)