# e-Tinglysning Web Services Dokumentation

Tinglysningsretten
version 0.2

## Oversigt

Denne dokumentation dækker referenceimplementationen af S2S Aktør HTTP XML Svarservices, som giver aktører mulighed for at modtage push-notifikationer om status på og resultater af anmeldelser til tinglysning fra e-Tinglysning (e-TL).

Svarservices skal implementeres af aktørens systemer som HTTP POST-endpoints. Operationerne i disse services giver e-TL mulighed for at aflevere hændelser fra den anmeldte sag til anmelder via XML-beskeder over HTTP.

## Opsætning af HTTP-endpoints

### Grundlæggende krav

Alle aktører skal implementere HTTP POST-endpoints for at modtage beskeder fra e-TL. Endpoints skal:

- Acceptere POST-forespørgsler

- Kun svare med HTTP-statuskoder (ingen data i svaret)

- Håndtere XML-data fra forespørgsler

- Understøtte krævede HTTP-headers

### OCES-certifikater og sikkerhed

Kald til Svarservices fra e-TL bruger OCES-certifikater (Offentlige Certifikater til Elektronisk Service) i version 3.0. De relevante certifikatpolitikker m.m. kan læses på certifikat.gov.dk og ca1.gov.dk.

HTTP-applikationen skal derfor konfigureres med:

- Gyldigt TLS-certifikat

- Tillid til OCES-certifikater

Dette sikrer, at der er tillid til forespørgsler fra e-TL.

### HTTP Headers

Alle forespørgsler fra e-TL indeholder følgende headers:

Header | Beskrivelse
--- | ---
`Tinglysning-Message-Id` | Unikt UUID for hver forespørgsel
`RelatesTo` | Reference til oprindelig aktør-request (hvis relevant)

UUID-standardens version 4 benyttes.

### Endpoint struktur

Endpoints følger navngivningsmønstret: <BASE_URL>/<SERVICE_NAME>/<OPERATION>

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

## Systemidentifikatorer og endpoints

### Systemidentifikator i anmeldelser

Ved oprettelse af anmeldelser via S2S HTTP XML API kan aktører specificere en systemidentifikator (1-8) i XML-dokumentet, som angiver hvilket system, der skal modtage beskeder. Hvis ingen systemidentifikator angives sendes beskeder som standard til system 1.

Systemer konfigureres via administrationsside på tinglysning.dk.

## Servicekategorier

### Anmeldelse Services

#### AnmeldelseSvar

Håndterer notifikationer relateret til anmeldelsesprocessen:

Operation | Beskrivelse
--- | ---
AnmeldelseKvitteringModtag | Kvittering for modtaget anmeldelse
AnmeldelseStatusModtag | Statusændringer på anmeldelser
AnmeldelseSvarModtag | Endelige svar på anmeldelser
AnmaerkningStatusModtag | Ændringer til anmærkninger og frister

#### BilbogAnmeldelseSvar

Håndterer notifikationer relateret til anmeldelsesprocessen:

Operation | Beskrivelse
--- | ---
AnmeldelseKvitteringModtag | Kvittering for modtaget anmeldelse
AnmeldelseStatusModtag | Statusændringer på anmeldelser
BilbogAnmeldelseSvarModtag | Endelige svar på anmeldelser
BilbogAnmaerkningStatusModtag | Ændringer til anmærkninger og frister

#### AndelsbogAnmeldelseSvar

Håndterer notifikationer relateret til anmeldelsesprocessen:

Operation | Beskrivelse
--- | ---
AnmeldelseKvitteringModtag | Kvittering for modtaget anmeldelse
AnmeldelseStatusModtag | Statusændringer på anmeldelser
AndelsbogAnmeldelseSvarModtag | Endelige svar på anmeldelser
AndelsbogAnmaerkningStatusModtag | Ændringer til anmærkninger og frister

#### PersonbogAnmeldelseSvar

Håndterer notifikationer relateret til anmeldelsesprocessen:

Operation | Beskrivelse
--- | ---
AnmeldelseKvitteringModtag | Kvittering for modtaget anmeldelse
AnmeldelseStatusModtag | Statusændringer på anmeldelser
PersonbogAnmeldelseSvarModtag | Endelige svar på anmeldelser
PersonbogAnmaerkningStatusModtag | Ændringer til anmærkninger og frister

### Administrative Services

#### BrugerformularSvar

Service til godkendelsesnotifikationer for brugerformularer:

Operation | Beskrivelse
--- | ---
BrugerformularSvarModtag | Godkendelses-/afvisningsnotifikationer

#### UnderskriftsmappeSvar

Service til underskriftsmappe notifikationer:

Operation | Beskrivelse
--- | ---
UnderskriftsmappeNotifikationModtag | Notifikationer om underskriftsprocessen

#### AbonnementSvar

Service til abonnementshændelsesnotifikationer:

Operation | Beskrivelse
--- | ---
AbonnementNotifikationModtag | Ændringer til objekter med abonnement

### Fejlhåndtering

#### FejlService

Central fejlrapporteringsservice:

Operation | Beskrivelse
--- | ---
FejlModtag | Fejlrapporter fra e-TL systemet

## XML Skema Dokumentation

Komplet XSD skema dokumentation er tilgængelig i: XSD Dokumentation.

XML-beskedindholdet bygger på e-TL’s etablerede XML-skemaer.

## Target Namespaces

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

## Integrationsmønstre

### Push-notifikationer

Alle services følger et push-notifikationsmønster hvor:

- e-TL sender HTTP POST-forespørgsler indeholdende XML-data til aktørens endpoints

- Endpoint skal svare med HTTP-statuskoder for at indikere succes/fejl (2xx, 4xx, 5xx)

- Svar fra endpoints må derudover ikke indeholde data

### Beskedstruktur

Alle beskeder følger etablerede standarder:

- XML-baserede beskedformater baseret på e-TL’s OIO XML-skemaer

- Struktureret beskedindhold med krævede felter

- Validering mod XML-skemaer

### Fejlhåndtering og gensendelse

- Beskeder gemmes i et kø-system for pålidelig levering

- Automatisk gensendelse i tilfælde af fejl

- Logning af alle forespørgsler og svar