Receiving inbound messages

When inbound messages are received and validated, they are made ready for importing into the receiver's back-end system. After the receiver's back-end system has handled the message, it notifies the messaging server of the outcome of the delivery.

Getting a list of pending messages

The messages that are waiting to be imported have the pendingdelivery message status. Checking for pending messages is done through the GET /messages?status=pendingdelivery&transfer=inbound call. By default, the request retrieves a list of the 50 most recent messages whose message status is pendingdelivery.

You can paginate the results using the offset and limit parameters. The maximum value of the limit parameter is 100.

Fetching documents

For parsing and processing, business documents are retrieved in their raw format, either in XML or in JSON.

When it comes to core documents, we recommend that you retrieve them using one of these calls:

• GET /transactions/submit-order?mid={mid}
• GET /transactions/submit-order-change?mid={mid}
• GET /transactions/submit-order-cancellation?mid={mid}
• GET /transactions/submit-invoice?mid={mid}
• GET /transactions/correct-with-credit?mid={mid}
• GET /transactions/submit-payment-notification?mid={mid}

These calls retrieve the document metadata in JSON format along with the information about the message. This helps you work with different document specifications that your business partners might support without having to prepare each document separately. The correct document specification is then chosen for you when creating a message based on the information about what the receiver can process.

Documents can also be retrieved based on their type, name, or index number. To fetch the core document of a message, use the GET /messages/:mid/documents/core call. If the core document had to be transformed to another business document specification so that the receiver can process it, the transformed document in the inbound message is retrieved through the GET /messages/:mid/documents/transformed call. To get the original document that was transformed, use the GET /messages/:mid/documents/original.

For the calls that take the document index or the document name, you first need to retrieve the message using the message identifier (uniqueId). Message details are given in JSON format, such as this one:

{
    "uniqueId": "6cfa5c24-25c5-4eb4-bed5-3ed6cc6c25c5",
    "timeReceived": "2019-05-29T13:24:54.31",
    "timeDelivered": null,
    "documentNo": "",
    "status": "pendingdelivery",
    "transfer": "inbound",
    "validationStatus": "unknown",
    "service": "urn:www:nesubl.eu:profiles:profile4:ver2.0##NESUBL-2.0",
    "action": "SubmitInvoice",
    "conversation": "190529:203504:KT:1111119999",
    "referenceInformation": "",
    "originParty": {
        "identifier": "KT:1111119999",
        "name": "Test Party One"
    },
    "destinationParty": {
        "identifier": "KT:2222229999",
        "name": "Test Party Two"
    },
    "documents": [
      {
        "index": 0,
        "name": "Invoice",
        "contentType": "application/xml",
        "encoding": "",
        "referenceId": "6cfa5c2425c54eb4bed53ed6cc6c25c5:KT:1111119999:0:hvbwdczr6i",
        "namespace": "",
        "attachmentType": "Core",
        "isTransformed": false
      }
    ]
}

The GET /messages/:mid/documents/:name call requires the name of the document, which matches the value of the name property of the corresponding element in the documents array in the same JSON object. Each business document has a unique name in the context of the message in which it is contained.

The other call for importing business documents, GET /messages/:mid/documents/:idx, relies on the index number of the document. The core business document always has an index of 0, while the attachments in the same message have a higher index. The index number is stored as the index property of each document in the documents array in the message object.

Setting message status

To remove messages from the list of messages with the pendingdelivery status, the receiver's back-end system must change their status depending on the outcome of importing and processing.

To indicate a successful delivery, you need to change the message status from pendingdelivery to delivered. This is achieved using the POST /messages/:mid/mark-as-delivered call. If there is an issue when importing the message, the message status is set instead to failed through the POST /messages/:mid/mark-as-failed call.

Messages marked as failed can be parked or retried manually through the Messaging Server UI.

Retrying triggers a new attempt to import the message. This is useful in case that the technical or other issues that prevented the first delivery attempt have been successfully fixed.

Parking a message typically indicates that the issue encountered has been resolved in some other way. For example, it might mean that the business document has been sent in another message, transmitted through email, or printed and delivered through the post. You need to provide a reason for parking the message, which facilitates document tracking.

Parking failed messages is especially useful if you do not intend to import them because it lets you detect and manage these messages more easily.