High Level Flow

This document provides a high-level overview of the typical message exchange scenarios using the EDI 2.0 API. It covers configuration, sending messages, and the process for receiving notifications and documents.

For detailed technical specifications, please refer to the Swagger documentation.

1. Initial Configuration

Before using the API, each client must configure its message handler (MSH) settings. We recommend sending this configuration declaratively every time the client application starts or when settings change.

For more details, see the configuration endpoint page.

sequenceDiagram
    participant Client
    participant API as EDI 2.0 API

    Client->>API: PUT /mshconfigurations
    Note right of Client: Sets notification channels and filters
    API-->>Client: 204 No Content

2. Sending a Message

To send a business document, the client submits it as a base64-encoded XML. The API validates the request and returns an Id which can be used to track the delivery status.

For more details, see the sending messages endpoint page.

sequenceDiagram
    participant Client
    participant API as EDI 2.0 API

    Client->>API: POST /messages
    Note right of Client: Sends base64-encoded business document
    API-->>Client: 202 Accepted (Id)

3. Receiving Notifications and Messages

Clients consume notifications to stay informed about new incoming messages (NewMessage) and status updates for sent messages (MessageSentStateUpdated, MessageDeliveryStateUpdated, MessageApprecInfoUpdated, RefusedMessage).

For more details, see the notifications endpoint page.

There are two supported flows for handling notifications:

1. Delete after processing (Recommended): Consume via /notifications/unread (poll or stream), then delete each notification once it has been handled.
2. Track an offset (deprecated): Consume via /notifications (poll or stream), tracking the offset of the last processed notification. Notifications are left in place and expire via server-side retention.

Note: Flow 2 is deprecated and may be discontinued in a future release. New clients should use flow 1.

Why flow 1 is recommended: The offset in flow 2 is a single point of state. If your client restarts from a stale offset (for example after an active cluster/region failover), you risk re-processing notifications you already handled, or — worse — starting ahead of notifications that were slow to replicate, effectively losing them. With flow 1, the unread set is self-correcting: on reconnect you simply receive whatever has not yet been deleted, regardless of what happened on the infrastructure side.

Note: Active region failover is not implemented as of September 2026, so this is not an operational concern today. The recommendation is made with future resilience in mind.

If you choose flow 2, be aware that you may supplement missing status updates by calling the /status endpoint. For NewMessage notifications, the handling of a missed message depends on the sender's follow-up routines (some will re-send if no application receipt is received within a certain period).

Recommended Workflow (Flow 1 — Unread + Delete):

Consuming notifications:

1. Fetch: Poll GET /notifications/unread (or open an SSE stream to /notifications/unread/stream).
2. Persist: Store notifications in the client's local database.
3. Finalize: Delete the handled notifications via POST /notifications/delete. You can delete in bulk.

Processing each notification:

• Process: Handle the locally persisted notification (e.g., download the message, check status).

Note: It is good practice to mark the message as downloaded (PUT /messages/{id}/downloaded), as this immediately triggers the payload to be deleted from EDI 2.0.

sequenceDiagram
    participant Client
    participant API as EDI 2.0 API

    rect rgb(240, 240, 240)
    Note over Client, API: Polling Loop (e.g., every 1 minute)
    Client->>API: GET /notifications/unread
    API-->>Client: 200 OK (Unread Notifications)
    end

    rect rgb(255, 255, 240)
    Note over Client, API: Processing Loop (For each NewMessage notification)
    Client->>API: GET /messages/{id}/business-document
    API-->>Client: 200 OK (Business Document)

    Note over Client: Persist document locally

    Client->>API: PUT /messages/{id}/downloaded
    Client->>API: POST /notifications/delete
    Note right of Client: Body: {"notificationIds": ["..."]}
    API-->>Client: 204 No Content


    Note over Client: Process document & generate AppRec

    alt Option A: Delegate AppRec generation to API
        Client->>API: POST /messages/{id}/apprec
        API-->>Client: 202 Accepted
    else Option B: Send custom AppRec as new message
        Client->>API: POST /messages (AppRec XML)
        API-->>Client: 202 Accepted
    end
    end

4. Complete End-to-End Flow

The following diagram illustrates a full exchange where Client A sends a message to Client B, and Client B responds with an Application Receipt (AppRec).

sequenceDiagram
    participant A as Client A
    participant API as EDI 2.0 API
    participant B as Client B

    Note over A: 1. Send Message
    A->>API: POST /messages
    API-->>A: 202 Accepted (ID_1)

    Note over B: 2. Poll for Notifications
    B->>API: GET /notifications/unread
    API-->>B: List [NewMessage(ID_1)]

    Note over B: 3. Retrieve & Process Message
    B->>API: GET /messages/ID_1/business-document
    API-->>B: Business Document
    B->>API: PUT /messages/ID_1/downloaded

    Note over B: 4. Send AppRec
    B->>API: POST /messages/ID_1/apprec
    API-->>B: 202 Accepted (ID_2)

    Note over A: 5. Receive AppRec & Status info
    A->>API: GET /messages/ID_1/status
    API-->>A: 200 OK (StatusList)

Key Considerations for Application Receipt:

• Sending AppRec: The receiver can either let the API generate a standard AppRec or upload a custom one.
• Receiving AppRec: The original sender will receive the AppRec as a NewMessage notification and can also see the delivery status update via /Status endpoint.