# e-Tinglysning Web Services Documentation

Tinglysningsretten
1.0.0

## Overview

This documentation covers the reference implementation of S2S Actor HTTP XML Reply Services, which enable actors to receive push notifications about the statuses and results of land registration applications from the digital land registration system, e-Tinglysning (e-Tinglysning).

Reply Services must be implemented by the actor’s systems as HTTP POST endpoints. The endpoints in these services allow e-Tinglysning to deliver events from the submitted application to the applicant via XML messages over HTTP.

## HTTP Endpoint Setup

### Basic Requirements

All actors must implement HTTP POST endpoints to receive messages from e-Tinglysning. Endpoints must:

- Accept POST requests

- Only respond with HTTP status codes (no response body)

- Handle XML data in the request body

- Support required HTTP headers

### OCES Certificate and Security

Calls to Reply Services from e-Tinglysning use OCES certificates (Offentlige Certifikater til Elektronisk Service, or Public Certificates for Electronic Service in English) version 3.0. The relevant certificate policies etc. are available at certifikat.gov.dk and ca1.gov.dk, both primarily in Danish, but .

The HTTP application must therefore be configured with:

- A valid TLS certificate

- Trust of OCES certificates

This ensures that requests from e-Tinglysning are trusted.

### HTTP Headers

All requests from e-Tinglysning contain the following headers:

Header | Description
--- | ---
`Tinglysning-Message-Id` | Unique UUID for each request
`Tinglysning-Relates-To` | Reference to original actor request (if relevant)

Requests for copies of notifications will contain the `Tinglysning-Sekvensnummer` header with the assigned sequence number. This header is only relavant for the endpoints used in AnmeldelseKopiSvar.

The UUID standard version 4 is used.

### Endpoint Structure

To ensure a consistent and predictable integration, all endpoints must follow a fixed naming pattern. This pattern replaces the previous SOAP-based routing where the action was specified in a `<wsa:Action>` header.

#### Naming Pattern

The structure for an endpoint is as follows:

`<BASE_URL>/<SERVICE_NAME>/<OPERATION>`

Component | Description
--- | ---
<BASE_URL> | The base URL for the actor’s service environment.
<SERVICE_NAME> | The name of the specific service being called. Corresponds to the previous service name.
<OPERATION> | The name of the operation to be performed. This value is identical to the previous action value (excluding the urn:<namespace># prefix).

#### Example of Transition from SOAP to HTTP

Where a SOAP-based request was previously sent to the AnmeldelseSvar service with a `<wsa:Action>` header set to `urn:#AnmeldelseStatusModtag`, the new REST endpoint will look like this:

`https://example.com/AnmeldelseSvar/AnmeldelseStatusModtag`

The operation (AnmeldelseStatusModtag) is now part of the URL path, separated from the service name by a forward slash (/). A specific HTTP header is not used to specify the operation.

## System Identifiers and Endpoints

### System Identifier in Applications

When creating "anmeldelser", "brugerformular" and "underskriftsmappedokumenter" via the HTTP XML API, actors can specify a system identifier (1–8) in the XML document, which indicates which system should receive messages. If no system identifier is specified, messages are by default sent to system 1.

Endpoints for systems are configured on the Administration page on tinglysning.dk under S2S Param.

All S2S messages submitted via the SOAP API that result in an asynchronous response will be delivered via the SOAP Svarservices. All S2S messages submitted via the HTTP XML API that result in an asynchronous response will be delivered via the XML Svarservices.

### Transition from SOAP to HTTP

When the SOAP Svarservices are phased out, all responses will be delivered via the XML Svarservices, and the endpoint for system 1 will be used as the default.

If the user clears the SOAP Svarservices endpoint on the Administration page on tinglysning.dk under S2S Param, all actor messages will be delivered through the XML Svarservices. This allows a full transition to the XML Svarservices. This functionality takes effect with release R53.

All non-subscription responses and non-AnmaerkningStatusModtag actor messages caused by SOAP messages will be sent to system identifier 1 (Standard) when the SOAP Svarservices field is cleared.

All subscription responses and AnmaerkningStatusModtag actor messages caused by SOAP messages will be sent to system identifier 2 (Subscription) when the SOAP Svarservices field is cleared.

### Subscription responses

The system identifier for system 2 is dedicated to handling subscription responses. All subscription responses will be sent to system 2, regardless of which system identifier was originally specified in the request.

If the endpoint for system 2 is not specified, the corresponding message will not be sent, but instead archived for 30 days. After 30 days the message and its XML are deleted.

If actors discover that they have mistakenly not set an endpoint for system 2, they must contact the Tinglysningsretten within 30 days to have the subscription messages resent. If an endpoint is set but delivery errors occur, the same approach as described in Message retention and error handling will be used.

Subscription responses include all responses from the AbonnementSvar service and responses from the operations AnmaerkningStatusModtag, BilbogAnmaerkningStatusModtag, AndelsbogAnmaerkningStatusModtag and PersonbogAnmaerkningStatusModtag. Actors may still use system identifier 2 like any of the other system identifiers 1–8. Only subscription responses will not be retried if no endpoint is specified for system 2.

Subscriptions created through the SOAP API will deliver responses via the SOAP Svarservices. Subscriptions created through the HTTP XML API will deliver messages via the XML Svarservices, except when the SOAP Svarservices endpoint is cleared as described in Transition from SOAP to HTTP.

### Message retention and error handling

Message delivery are retried once per hour for up to 60 hours if an delibery error occur. All actor messages that cannot be delivered are stored for 30 days.

After 30 days, the message and its XML are deleted. If actors discover they are not receiving messages due to an error, they must contact Tinglysningsretten within 30 days to have the messages resent.

### Endpoint requirements

If endpoints from the S2S HTTP XML API that result in asynchronous replies are to be used, an endpoint must be specified for system identifier 1 (Standard) and for any other system identifier that is used when utilizing the XML Svarservices. Otherwise, the S2S message will be rejected upon submission via the HTTP XML API with the following error message: `Aktør med CVR <CVR> har ikke konfigureret et XML Svarservices endpoint for system identifikator <SYSTEM_IDENTIFIKATOR>.`.

Endpoints that result in asynchronous replies are marked with integration pattern "Workflow", or with a note in the description about asynchronous replies.

An endpoint does not need to be set for system identifier 2 (Subscription) if subscription reception is not desired.

## Service Categories

### Application Services

#### AnmeldelseSvar

Handles notifications related to the application process:

Operation | Description
--- | ---
AnmeldelseKvitteringModtag | Receipt for received application
AnmeldelseStatusModtag | Status changes on applications
AnmeldelseSvarModtag | Final responses to applications
AnmaerkningStatusModtag | Changes to remarks and deadlines

#### BilbogAnmeldelseSvar

Handles notifications related to the application process:

Operation | Description
--- | ---
AnmeldelseKvitteringModtag | Receipt for received application
AnmeldelseStatusModtag | Status changes on applications
BilbogAnmeldelseSvarModtag | Final responses to applications
BilbogAnmaerkningStatusModtag | Changes to remarks and deadlines

#### AndelsbogAnmeldelseSvar

Handles notifications related to the application process:

Operation | Description
--- | ---
AnmeldelseKvitteringModtag | Receipt for received application
AnmeldelseStatusModtag | Status changes on applications
AndelsbogAnmeldelseSvarModtag | Final responses to applications
AndelsbogAnmaerkningStatusModtag | Changes to remarks and deadlines

#### PersonbogAnmeldelseSvar

Handles notifications related to the application process:

Operation | Description
--- | ---
AnmeldelseKvitteringModtag | Receipt for received application
AnmeldelseStatusModtag | Status changes on applications
PersonbogAnmeldelseSvarModtag | Final responses to applications
PersonbogAnmaerkningStatusModtag | Changes to remarks and deadlines

#### AnmeldelseKopiSvar

Receives copies of notifications from the application process:

Endpoint | Description
--- | ---
AnmeldelseSvarModtag | Final responses to applications
AnmaerkningStatusModtag | Changes to remarks and deadlines
AndelsbogAnmeldelseSvarModtag | Final responses to applications
AndelsbogAnmaerkningStatusModtag | Changes to remarks and deadlines
BilbogAnmeldelseSvarModtag | Final responses to applications
BilbogAnmaerkningStatusModtag | Changes to remarks and deadlines
PersonbogAnmeldelseSvarModtag | Final responses to applications
PersonbogAnmaerkningStatusModtag | Changes to remarks and deadlines

### Administrative Services

#### BrugerformularSvar

Service for user form approval notifications:

Operation | Description
--- | ---
BrugerformularNotifikationModtag | Approval/rejection notifications

#### UnderskriftsmappeSvar

Service for signature folder notifications:

Operation | Description
--- | ---
UnderskriftsmappeNotifikationModtag | Notifications about the signature process

#### AbonnementSvar

Service for subscription event notifications:

Operation | Description
--- | ---
AbonnementNotifikationModtag | Changes to objects with subscriptions

### Error Handling

#### FejlService

Central error reporting service:

Operation | Description
--- | ---
FejlModtag | Error reports from the e-Tinglysning system

## XML Schema Documentation

Complete XSD schema documentation is available at: XSD Documentation.

XML message content is built on e-Tinglysning’s established XML schemas.

## Target Namespaces

Service Type | Namespace
--- | ---
Application Services | `http://rep.oio.dk/tinglysning.dk/svarservice/message/anmeldelse/1/`
Administrative Services | `http://rep.oio.dk/tinglysning.dk/svarservice/message/administration/1/`
Error Services | `http://rep.oio.dk/tinglysning.dk/svarservice/message/fejlservice/1/`

## Integration Patterns

### Push Notifications

All services follow a push notification pattern where:

- e-Tinglysning sends HTTP POST requests containing XML data to the actor’s endpoints

- Endpoints must respond with HTTP status codes to indicate success/failure (2xx, 4xx, 5xx)

- Responses from endpoints must not include data

### Message Structure

All messages follow established standards:

- XML-based message formats based on e-Tinglysning OIO XML schemas

- Structured message content with required fields

- Validation against XML Schemas

### Error Handling and Retry

- Messages are stored in a queue system for reliable delivery

- Automatic retry in case of errors

- Logging of all requests and responses