API Main 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 Configuration of EDI 2.0.

sequenceDiagram
    participant Client
    participant API as EDI 2.0 API

    Client->>API: POST /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 AssignedId which can be used to track the delivery status.

For more details, see Sende Melding.

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 (AssignedId)

3. Receiving Notifications and Messages

Clients should periodically poll the API for new notifications. Notifications inform the client about new incoming messages (NewMessage) or status updates for sent messages (StatusUpdate).

Recommended Workflow:

1. Poll: Fetch new notifications.
2. Persist: Store notifications in the client's local database.
3. Acknowledge: Delete the processed notifications from the server.
4. Process: Act on the persisted notifications (e.g., download messages).

For more details, see Hente informasjon om innkommende meldinger.

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 /messages/notices
    API-->>Client: 200 OK (List of Notifications)
    
    Note over Client: Persist notifications locally
    
    Client->>API: PUT /messages/{id}/read
    Note right of Client: Acknowledges/Deletes the notice
    API-->>Client: 204 No Content
    end

    rect rgb(255, 255, 240)
    Note over Client, API: Processing Loop (For each NewMessage notice)
    Client->>API: GET /messages/{id}
    API-->>Client: 200 OK (Business Document)
    
    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 /messages/notices
    API-->>B: List [NewMessage(ID_1)]

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

    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 Update
    A->>API: GET /messages/notices
    API-->>A: List [NewMessage(ID_2), StatusUpdate(ID_1)]
    A->>API: PUT /messages/ID_2/read
    Note over A: Message ID_1 is now fully completed

Key Considerations for AppRec:

• 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 a StatusUpdate notification.