Guided Tour: Messaging Services

For more details, check our online documentation: MAPI Message API Reference

Message Services are used for creating electronic business documents with raw XML. For working with JSON metadata, please refer to MAPI Guided Tour – Transaction Services.

Sending electronic documents

1. Create a random unique identifier (GUID) and store internally. This will become the message identifier (:mid).
2. Prepare the XML message and submit the business documents using:
   • POST /messages/create-business-transaction To define the type of document being submitted, ensure the parameter transactionGroupIdentifier is set, e.g.SubmitInvoice or CorrectWithCredit. 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 either true or false depending on if processing can be triggered or not.
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) PendingReview (some data may be incorrect, check message errors and warnings) and c) Parked (manually parked) may be considered final states.
5. Store the referenceId parameter for each document for later displaying the document(s) **[see Receiving electronic documents, #4]**

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, e.g.:
   • GET /transactions/submit-invoice?messageId=:mid
   • GET /transactions/correct-with-credit?messageId=:mid
   • GET /transactions/submit-order?messageId=:mid OR get the business document data in raw XML format using:
   • GET /messages/:mid/documents/core 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 hours).
5. To allow a user to view the document, use:
   • GET /messages/display/:referenceId (optionally add the ?lang=<lang> parameter)