# e-Tinglysning Web Services Documentation

Tinglysningsretten
version 0.2

## 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-TL).

Reply Services must be implemented by the actor’s systems as HTTP POST endpoints. The operations in these services allow e-TL 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-TL. 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-TL 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-TL are trusted.

### HTTP Headers

All requests from e-TL contain the following headers:

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

The UUID standard version 4 is used.

### Endpoint Structure

Endpoints follow the naming pattern: <BASE_URL>/<SERVICE_NAME>/<OPERATION>

Example: https://eksempel.dk/AnmeldelseSvar/AnmeldelseStatusModtag

## System Identifiers and Endpoints

### System Identifier in Applications

When creating applications via the S2S HTTP XML API, actors can specify a system identifier (1-8) in the XML document, which indicates the system that should receive messages. If no system identifier is specified, messages are by default sent to system 1.

Systems are configured through the administration page on tinglysning.dk.

## 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

### Administrative Services

#### BrugerformularSvar

Service for user form approval notifications:

Operation | Description
--- | ---
BrugerformularSvarModtag | 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-TL system

## XML Schema Documentation

Complete XSD schema documentation is available at: XSD Documentation.

XML message content is built on e-TL’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-TL 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-TL 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