📘

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 MAPI Guided Tour – Message Services .

Sending electronic documents

1. Create a random unique identifier (GUID) and store internally. This will become the message identifier (:mid).

2. 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.

3. Optionally, stream a binary payload as attachment (e.g. timesheet, product description) using:\

   • POST /messages/:mid/documents
     The content type must be a valid 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.

4. Check the state of the message any time using:\

   • GET messages/:mid/status
     This will both give delivery information as well as message handling traces. The states: a) Delivered (delivered to endpoint), b) Failed (there was an error) and c) Parked (manually parked as handled) may be considered final states.

5. Store the referenceId parameter for each document for later displaying the document(s) see Receiving electronic documents below.

Alerting users of pending incoming documents

To avoid pending incoming documents from piling up in the inbox, either:

• Set up a service that will routinely (every 10-30 minutes) fetch the inbound documents into the ERP system (according to the instructions below).

• Add an alert, notification or badge on a dashboard or in context views related to handling invoices and credit notes indicating the number of pending entries and an action to fetch them:\

  • GET /parties/{isoIdentifier}/pending-summaries?action=SubmitInvoice,CorrectWithCredit (where isoIdentifer is the prefixed identifier e.g. 0196:6511230889 and action limits the query to invoices and credit notes) for partner admin users OR\
  • GET /messages/pending-summaries?action=SubmitInvoice,CorrectWithCredit (in the ERP user context)

Receiving electronic documents

1. Fetch a list of pending incoming messages using:\

   • GET /messages?status=pendingdelivery&transfer=inbound
     For each message, make a note of the unique identifier (GUID), the action parameter and the referenceId of the document(s).

2. 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

3. 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}**

4. 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).

5. 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)