The ecosio Messaging API enables you to send, receive, archive, and request messages, such as documents sent to suppliers.
Tip
You can try out the Messaging API by importing the OpenAPI specification into an API client such as Postman. For step-by-step instructions, see how to import an API specification in the Postman documentation.
Prerequisites
You must be able to authenticate with the ecosio API.
Send a message
You can send a message by calling Deliver a message to the ecosio Integration Hub.
Supported document types
The body of the request must contain the document you want to send in Base64 encoding. The ecosio Messaging API supports the following document types:
- ANSI X12
- CSV/XML (requires special arrangement)
- ebInterface
- EDIFACT
- ERPEL (ecosioās in-house format)
- JSON
- VRBL
- ZUGFeRD
The response will return the ecosio message ID.
To structure documents using ecosio ERPEL, see the following recipe.
Sender and receiver identification
The document must contain the SENDER and RECEIVER identifiers in one of the following identifier formats:
- Global Location Numbers (GLNs)
- Custom Identifier (requires special arrangement)
Handle message resubmission
Sending the same document multiple times within six hours results in a DOUBLE_SUBMISSION failure, which prevents the duplicate message from being sent to the receiver.
To avoid a double submission, modify the document slightly, such as changing the timestamp.
State modes
Status values returned by the Messaging API are determined by the API connectorās state mode.
Warning
If you use API polling, implement backoff and limits, and stop polling once the message reaches a final status. ecosio may temporarily block requests from a connector that exceeds reasonable request rates.
Automatic forwarding
The Messaging API supports the automatic forwarding of messages to a predefined HTTP endpoint, removing the need for constant polling.
The receiving company must run an HTTP server that accepts messages via PUT or POST requests. This forwarding must be explicitly configured and activated before the Messaging API can send messages to the specified endpoint.
The receiverās configuration requires the following data:
- HTTP Endpoint-URL
- HTTP Protocol-Version, for example HTTP/1.1
- HTTP Method, for example
POSTorPUT - Basic Authentication support
- SSL/TLS support
- Include callback URL as
Locationheader
If the remote endpoint returns HTTP 200, the message status changes to SENT or FORWARDED depending on the configured state mode, and finishes processing. Any other response code is treated as an error. If an error occurs, the API parses a JSON message from the response body. If the endpoint returns a different response structure, configure the expected response first. Otherwise, handle it manually.
Pass-through header
For security reasons, ecosio filters all incoming HTTP headers. Messages are indexed by our Elastic Search cluster and made available in the Messages overview page. The Messaging API provides a pass-through header that enables custom headers to bypass the filter and be included in the indexing.
Any additional information, such as a third party's message handle, must be specified as a pass-through header to be available in the Messages overview page. Use the pass-through header to include a JSON structure containing the key-value pairs in indexing.