Messaging API connector
The ecosio Messaging API uses the credentials displayed and generated in the Monitor on the Connectors page in the ERP connectors section. API connectors are set up for you by ecosio.
Interactive demo
API connector parameters
The API Parameters section of an API connector displays the parameters for messages delivered to and from ecosio.
Maximum message size
The Maximum message size parameter sets the largest document ecosio accepts or forwards.
State modes
State modes define the set of statuses the API returns. To maintain backwards compatibility, you can choose which mode the API should use. You can choose 10, 11, 12, or 13.
Mode 10
Mode 10 is the original mode and forms the basis for all other state modes.
| State | Final state | Description |
|---|---|---|
REQUEST_RECEIVED | No | ecosio received the request. |
RECEIVED | No | The document type, sender, and receiver of the document are determined. |
DELIVERED | No | The message is available for the recipient to download. |
PICKEDUP | No | The recipient picked up the message. |
FORWARDED | No | ecosio delivered the message successfully. |
PROCESSED | Yes | The recipient acknowledged the successful processing of the document via callback. |
EXCEPTION | No | An error occurred whilst processing or delivering the document to the recipient. |
HANDLED | Yes | An authorised person acknowledged the processing or delivery failure and took appropriate countermeasures. A resend wasn't necessary. |
ARCHIVED | Yes | ecosio archived the document without further processing or access. |
PROCESSING | No | The document processing hasn't yet finished. |
Mode 11
Mode 11 adds the EXCEPTION_UNDER_REVIEW and ONBOARDING states.
| State | Final state | Description |
|---|---|---|
REQUEST_RECEIVED | No | ecosio received the request. |
RECEIVED | No | The document type, sender, and receiver of the document are determined. |
DELIVERED | No | The message is available for the recipient to download. |
PICKEDUP | No | The recipient picked up the message. |
FORWARDED | No | ecosio delivered the message successfully. |
PROCESSED | Yes | The recipient acknowledged the successful processing of the document via callback. |
EXCEPTION | No | An error occurred whilst processing or delivering the document to the recipient. |
HANDLED | Yes | An authorised person acknowledged the processing or delivery failure and took appropriate countermeasures. A resend wasn't necessary. |
ARCHIVED | Yes | ecosio archived the document without further processing or access. |
PROCESSING | No | The document processing hasn't yet finished. |
EXCEPTION_UNDER_REVIEW | No | The message transitioned to the EXCEPTION state and ecosio is actively working on the resolution of the exception. |
ONBOARDING | Yes | The message transitioned to the EXCEPTION state but the customer is currently in the onboarding process, likely testing the connector. |
Mode 12
Mode 12 removes the ARCHIVED, EXCEPTION_UNDER_REVIEW, and ONBOARDING states, and adds the EXCEPTION_CUSTOMER and HANDLED_CUSTOMER states.
| State | Final state | Description |
|---|---|---|
REQUEST_RECEIVED | No | ecosio received the request. |
RECEIVED | No | The document type, sender, and receiver of the document are determined. |
DELIVERED | No | The message is available for the recipient to download. |
PICKEDUP | No | The recipient picked up the message. |
FORWARDED | No | ecosio delivered the message successfully. |
PROCESSED | Yes | The recipient acknowledged the successful processing of the document via callback. |
HANDLED | Yes | An authorised person acknowledged the processing or delivery failure and took appropriate countermeasures. A resend wasn't necessary. |
EXCEPTION_CUSTOMER | Yes | An exception occurred that ecosio can't resolve and you must fix. |
HANDLED_CUSTOMER | Yes | After you resolve an EXCEPTION_CUSTOMER state, trigger this state to mark it resolved. |
PROCESSING | No | The document processing hasn't yet finished. |
Mode 13
Modes 13 replaces the PICKEDUP, FORWARDED, and PROCESSED states with SENT.
| State | Final state | Description |
|---|---|---|
REQUEST_RECEIVED | No | ecosio received the request. |
RECEIVED | No | The document type, sender, and receiver of the document are determined. |
DELIVERED | No | The message is available for the recipient to download. |
SENT | Yes | The recipient received the message and, if supported, also acknowledged its processing. |
HANDLED | Yes | An authorised person acknowledged the processing or delivery failure and took appropriate countermeasures. A resend wasn't necessary. |
EXCEPTION_CUSTOMER | Yes | An exception occurred that ecosio can't resolve and you must fix. |
HANDLED_CUSTOMER | Yes | After you resolve an EXCEPTION_CUSTOMER state, trigger this state to mark it resolved. |
PROCESSING | No | The document processing hasn't yet finished. |
Request callback
If Request Callback is selected, when you send a message, ecosio automatically receives a delivery or processing callback from the recipient. The message state updates based on this response. This is set when the connector is created. To change it, contact your ecosio Integration Engineer.
If the recipient doesn't support callbacks, the message reaches a final state when delivery is confirmed by the channel. In mode 13 this is SENT. In modes 10, 11, and 12 this is PROCESSED. If delivery fails, the state changes to EXCEPTION in modes 10 and 11, or EXCEPTION_CUSTOMER in modes 12 and 13.
Updated 4 months ago