# e-Tinglysning Web Services Dokumentation

Tinglysningsretten
1.0.0

## 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. Endepunkterne i disse services giver e-Tinglysning 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-Tinglysning. 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-Tinglysning.

### HTTP Headers

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

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

Forespørgsler for kopisvar vil have headeren `Tinglysning-Sekvensnummer` som indeholder sekvensnummeret for kopisvaret. Dette er kun relevant for endepunkter til AnmeldelseKopiSvar.

UUID-standardens version 4 benyttes.

### Endpoint struktur

For at sikre en ensartet og forudsigelig integration skal alle endpoints følge et fast navngivningsmønster. Dette mønster erstatter den tidligere SOAP-baserede routing, hvor handlingen blev specificeret i en `<wsa:Action>`-header.

#### Navngivningsmønster

Strukturen for et endpoint er som følger:

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

Komponent | Beskrivelse
--- | ---
<BASE_URL> | Den grundlæggende URL for aktørens service-miljø.
<SERVICE_NAME> | Navnet på den specifikke service, der kaldes. Svarer til det tidligere service-navn.
<OPERATION> | Navnet på den operation, der skal udføres. Denne værdi er identisk med den tidligere action-værdi (fratrukket urn:<namespace>#).

#### Eksempel på overgang fra SOAP til HTTP

Hvor en SOAP-baseret anmodning tidligere blev sendt til servicen AnmeldelseSvar med en `<wsa:Action>`-header sat til `urn:#AnmeldelseStatusModtag`, vil det nye REST-endpoint se således ud:

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

Operationen (AnmeldelseStatusModtag) er nu en del af URL-stien og adskilt fra servicenavnet med en skråstreg (/). Der benyttes ikke en specifik HTTP-header til at angive operationen.

## Systemidentifikatorer og endpoints

### Systemidentifikator i anmeldelser

Ved anmeldelser, oprettelse af brugerformular og dokumenter i underskriftsmappen via 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.

Endpoints for systemer konfigureres på Administration side på tinglysning.dk under S2S Param.

Alle S2S beskeder indsent via SOAP API’et som giver anledning til et asynkront svar vil resultere i svar via SOAP Svarservices. Alle S2S beskeder indsent via HTTP XML API’et som giver anledning til et asynkront svar vil resultere i svar via XML Svarservices.

### Overgang fra SOAP til HTTP

Når SOAP Svarservices udfases vil alle svar blive leveret via XML Svarservices, og endpointed for system 1 vil blive anvendt som standard.

Hvis brugeren sletter SOAP Svarservices endepunkt på Administration siden på tinglysning.dk under S2S Param, vil alle aktørbeskeder blive leveret gennem XML Svarservices. Dette tillader fuld overgang til XML Svarservices. Denne funktionalitet træder i kraft med release R53.

Alle ikke-abonnementsvar og ikke-anmærkningstatusmodtag aktørbeskeder forårsaget af SOAP-beskeder vil blive sendt til systemidentifikator 1 (Standard), når SOAP Svarservices feltet er blanket ud.

Alle abonnementsvar og anmærkningstatusmodtag aktørbeskeder forårsaget af SOAP-beskeder vil blive sendt til systemidentifikator 2 (Abonnement), når SOAP Svarservices feltet er blanket ud.

### Abonnement svar

Systemidentifikatoren for system 2 er dedikeret til håndtering af abonnement svar. Alle abonnement svar vil blive sent til system 2, uafhængigt af hvilken systemidentifikator der oprindeligt blev angivet i anmodningen.

Hvis endepunktet for system 2 ikke er angivet, vil den pågældende besked ikke blive sent, men i stedet arkiveret i 30 dage. Efter 30 dage slettes beskeden sammen med XML’en.

Hvis aktører opdager, at de fejlagtigt ikke har haft sat et endpoint for system 2, skal de kontakte Tinglysningsretten inden for 30 dage for at få abonnement beskederne gensendt. Hvis der er sat et endpoint, men der opstår fejl ved levering, følges sammen tilgang som beskrevet i Beskedopbevaring og fejlhåndtering.

Abonnement svar indebærer alle svar fra AbonnementSvar servicen og svar fra operationerne AnmaerkningStatusModtag, BilbogAnmaerkningStatusModtag, AndelsbogAnmaerkningStatusModtag og PersonbogAnmaerkningStatusModtag. Aktører kan stadig bruge systemidentifikator 2 som enhver af de andre 1-8 systemidentifikatorer. Kun abonnement svar vil ikke blive forsøgt gensent hvis der ikke er angivet et endpoint for system 2.

Abonnementer oprettet igennem SOAP API’et vil give besvarer igennem SOAP Svarservices. Abonnementer oprettet igennem HTTP XML API’et vil give beskeder igennem XML Svarservices, med undtagelse af hvis SOAP Svarservices endpoint udblankes som beskrevet i Overgang fra SOAP til HTTP.

### Beskedopbevaring og fejlhåndtering

Beskeder forsøges gensent en gang i timen i op til 60 timer. Alle aktørbeskeder som ikke kan leveres opbevares i 30 dage.

Efter 30 dage slettes beskeden sammen med XML’en. Hvis aktører opdager, at de ikke modtager beskeder på grund af en fejl, skal de kontakte Tinglysningsretten inden for 30 dage for at få beskederne gensendt.

### Endepunktkrav

Hvis endpoints fra S2S HTTP XML API som giver asynkrone svar skal anvendes, skal der angives et endpoint for systemidentifikator 1 (standard) og enhver anden systemidentifikator der bruges ved anvendelse af XML Svarservices. Ellers vil S2S beskeden blive afvist ved indsendelse via HTTP XML API’et, med følgende fejlbesked `Aktør med CVR <CVR> har ikke konfigureret et XML Svarservices endpoint for system identifikator <SYSTEM_IDENTIFIKATOR>.`.

Endpoints der giver asynkrone svar er angivet med integrationsmønsteret "forløb", eller med notat om asynkront svar i beskrivelsen.

Et endpoint behøver ikke at være sat for systemidentifikator 2 (Abonnement) hvis ikke der ønskes modtagelse af abonnementer.

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

#### AnmeldelseKopiSvar

Modtager kopier af notifikationer relateret til anmeldelsesprocessen:

Endpoint | Beskrivelse
--- | ---
AnmeldelseSvarModtag | Endelige svar på anmeldelser
AnmaerkningStatusModtag | Statusændringer på anmeldelser
AndelsbogAnmeldelseSvarModtag | Endelige svar på anmeldelser
AndelsbogAnmaerkningStatusModtag | Statusændringer på anmeldelser
BilbogAnmeldelseSvarModtag | Endelige svar på anmeldelser
BilbogAnmaerkningStatusModtag | Statusændringer på anmeldelser
PersonbogAnmeldelseSvarModtag | Endelige svar på anmeldelser
PersonbogAnmaerkningStatusModtag | Statusændringer på anmeldelser

### Administrative Services

#### BrugerformularSvar

Service til godkendelsesnotifikationer for brugerformularer:

Operation | Beskrivelse
--- | ---
BrugerformularNotifikationModtag | 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-Tinglysning’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-Tinglysning 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-Tinglysning 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