Migration Guide: V2 → V3

1. Changes to Overall Flow

Configuration

• Mandatory for every communication party that uses EDI 2.0.
• Each party is identified by its HER‑Id.
• As a system provider you must create a configuration for every HER‑Id belonging to your clients.
  • When you acquire a new client → add a configuration for its HER‑Id(s).
  • When you release a client → remove the configuration for its HER‑Id(s).
• Requests on behalf of an un-configured HER‑Id are rejected.
• Configurations are managed via the /mshconfigurations endpoint.

Polling & Notifications

Polling now occurs only on /notifications/unread or /notifications. The old /messages polling endpoint is retired. Both endpoints return new-message notifications (as in V2), status-update notifications for sent messages, and possibly more types in the future. This reduces the number of HTTP calls required to stay up-to-date.

No extra steps are needed to start receiving notifications — they are available immediately. Retention rules apply:

• Notifications older than 4 days are deleted unless a configuration exists for the HER-Id.
• Once a configuration is in place, notifications for that HER-Id are retained for a long period.

/notifications/unread (recommended)

• Returns all not-yet-deleted notifications. No offset tracking is required.
• You should delete notifications as you process them (see Notifications).

/notifications (deprecated)

• Uses an offset to track position (see "Handling Notification Offsets and Duplicates" below).
• You do not need to delete notifications — simply move to the next offset.

Server‑Sent Events (SSE) Stream

• /notifications and /notifications/unread also support an SSE stream.
• A GET request to /notifications/stream or /notifications/unread/stream opens a long‑living HTTP connection that pushes events in real time.
• If you use the SSE stream, you can stop polling any endpoint entirely.

2. Functional Changes to /messages

3. Transition Procedure

The most important part is to stop handling messages with your V2 client before you start handling messages with your V3 client.

Recommended Procedure:

• 1. Deploy the V3 client without processing messages.
• 2. Register configurations for all your HER‑Ids via the V3 client.
• 3. (Optional) Record the current notification offset (see below).
• 4. Stop the V2 client. Messages will begin queuing.
• 5. Start the V3 client and process the backlog that accumulated in step 4.
• 6. If processing fails, temporarily revert to the V2 client.
• 7. Once stable, undeploy the V2 client.

Alternative Single-Deploy Procedure:

• 1. Undeploy the V2 client (messages will queue).
• 2. (Optional) Record the current offset.
• 3. Deploy the V3 client - it will declare its configuration and automatically consume the queued messages.

Running both clients concurrently is technically supported, but you may see “missing” documents as one client may trigger deletion of a message that the other has not yet processed. If this is something your application can handle, it is also viable.

4. Handling Notification Offsets and Duplicates

You may ignore offsets entirely and instead use the /notifications/unread endpoints, which return all not-yet-deleted notifications. You then delete notifications as you process them. Read more about the different approaches in the Notifications documentation.

You will have to handle duplicate notifications that were created before making the switch to V3. The duplicate notifications for a HER-Id will have started to pile up from 4 days before creating a configuration for that HER-Id.

If you do choose to use offset tracking:

• Starting from a pre-existing offset should eliminate most duplicate handling, but not all. Contact the EDI 2.0 developers to receive a suitable offset.
• Starting at offset 0 is allowed, but you will receive the same duplicate notifications as if you did not use offset tracking.

5. Duplicate Handling

You should already have logic to ignore duplicate messages! If you need to add or verify this logic, follow the steps below.

Example V2 Message (GET /messages)

{
    "id": "524f2619-49e0-4899-a26a-9ccb2c682b9a",
    "contentType": "application/xml",
    "receiverHerId": 8142092,
    "senderHerId": 8094866,
    "businessDocumentId": "01ec80d4-ad73-457e-9ae0-3808971e4a84",
    "businessDocumentGenDate": "2026-05-15T07:57:03",
    "isAppRec": false,
    "sourceSystem": "Meldingsvalidator, 2.0.1533.0"
},

or, without metadata:

{
    "id": "524f2619-49e0-4899-a26a-9ccb2c682b9a",
    "receiverHerId": 8142092
}.

Note that id (internal id for EDI 2.0 message handler) is not the same as businessDocumentId (id for the clinical message (business document/payload)).

Corresponding V3 Notification

{
    "notificationId": "a3b8c2d4-1e5f-4a6b-8c9d-0e1f2a3b4c5d",
    "relatedMessageId": "524f2619-49e0-4899-a26a-9ccb2c682b9a",
    "type": "NewMessage",
    "notificationReceiverHerId": 8142092,
    "notificationTriggeredByHerId": 8094866,
    "description": "New message received. (SVAR_LAB)",
    "createdAt": "2026-05-15T04:00:11.5833333+00:00",
    "offset": 1190794
}

Implementing the following check prevents re‑processing the same payload when you start from offset 0 or when you overlap V2 and V3 processing windows.

Best Practice Duplicate‑Check Logic

• Keep a persistent set of V2 id values you have already processed.
• When a notification arrives, compare relatedMessageId to that set.
• If it matches → skip the notification.

Alternative Duplicate-Check Logic

• If you only store businessDocumentIds, fetch the full message (GET /messages/) or its business document (GET /messages//business-document) to resolve the ID before deciding.

If you don't have any duplicate checks whatsoever, you should implement it immediately.

6. Changes to HelseID

• The api-specific claim herid is no longer requested in your HelseID client.

The functionality intended by the claim herid has been subsumed and expanded by configuration. If your HelseID-client still provides herid, no harm is done - but it no longer has any function.