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: 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 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 (Id)

3. Receiving Notifications and Messages

Clients should periodically poll the API for new notifications. Notifications inform the client about new incoming messages (NewMessage).

For more details, see [Get Notifications](Get notifications.md).

Recommended Workflow:

1. Poll: Fetch new notifications.
2. Persist: Store notifications in the client's local database.
3. Process: Act on the persisted notifications (e.g., download messages).
4. Finalize: Mark the messages as downloaded.

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 /notifications ?Offset=<last-known-offset> 
    API-->>Client: 200 OK (List of 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    
    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
    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 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 /Status endpoint.