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