Denne beskrivelse er rettet mod personer, der skal integrere med Boligdok, eller som har en teknisk interesse i dette, såsom udviklere og løsningsarkitekter.
Boligdok tilbyder et REST-baseret API, som giver de nødvendige operationer for systemintegration med bygningssagkyndige, bestillere/mæglere og forsikringsselskaber. For alle tre aktørtyper er der API-funktioner til at hente bestillinger, der kræver handling. Dette kan inkludere leverede dokumenter til mægler, sager klar til tilbudsgivning hos forsikringsselskabet eller ordrer til bygningssagkyndig. Disse API-funktioner har dog nogle begrænsninger, såsom:
Som en løsning på dette har Boligdok udviklet et hændelsesbaseret interface, hvor hændelser leveres på en kø. Dette gør det muligt for alle parter at integrere effektivt, og der er etableret en arkitektur, der nemt muliggør tilføjelse af hændelsestyper.
En kø er en velkendt kommunikationsstruktur, som der findes standardkode til på alle udviklingsplatforme. Aktuelt har Boligdok valgt at basere sin kø på RabbitMQ (se også afsnittet RabbitMQ klientudvikling).
Meddelelser (message payload) kommer i JSON format og har følgende felter:
<butiksnummer>-<sagsnummer> for at danne et unikt sagsnummer.Her er et eksempel:
{
"id": "b22eefbd-ca5f-41b6-b286-72f578e6c8df",
"bestillingsId": "b6be9dc278df41ea92c98d381eaa6c48",
"sagsnummer": "S20210624160559",
"type": "DOKUMENTINFO",
"timestamp": "2021-06-24T16:06:37.674630",
"url": https://bolig-test.boligdok.dk/api/maegler/downloadFile/73165,
"dokumentId": 73165,
"sourceBestillingsId": null
}
Hvis der imod forventning skulle opstå fejl, kan man via Boligdoks API få gensendt den fejlede event. API-dokumentationen kan findes her. Der er ikke implementeret en dead-letter-queue, og uafhentede meddelelser fjernes efter 7 dage.
Kø-strukturen er topic-baseret. Som udgangspunkt stilles én kø til rådighed for hver bruger/aktør, dvs. topic er jeres Boligdok systemidentifikation. Hvis systemidentifikation er IDENT vil kønavn være: event.IDENT.
Hvis jeres infrastruktur kræver flere køer, opsættes dette i samarbejde med jer.
Der forbindes til kø-server med brugernavn og password. Forbindelsesstreng til testserver er: amqps://<brugernavn>:<password>@rmq-test.boligdok.dk:5671/external. Sikker protokol (amqps) på port 5671 skal benyttes. Virtual host er external. Produktionsserver er: rmq-prod.boligdok.dk.
Som udgangspunkt vil forsikringsselskaber kun få en kø, hvor samtlige events vil blive sendt ud på. Kø navnet vil være event.{forsikringsselskabsid}.
| Eventtype | Url til api | Beskrivelse |
|---|---|---|
| BESTILLINGSKVITTERING | /api/fs/bestilling/{id} | Sendes når bestilling modtages |
| TILBUDSRAPPORTER | /api/fs/bestilling/{id} | Sendes når bestilling er klar til tilbudsgivning |
| FORNYELSE | /api/fs/downloadFile/{id} | Sendes når der er modtaget en fornyet tilstandsrapport eller eleftersyn. Lige nu leveres url til dokumentet, men vi overvejer at ændre det til url mod bestillingen for at kunne levere al relevant information på én gang. |
| REVISION | /api/fs/downloadFile/{id} | Sendes når der er modtaget en revideret tilstandsrapport. Lige nu leveres url til dokumentet, men vi overvejer at ændre det til url mod bestillingen for at kunne levere al relevant information på én gang. |
| BESTILLINGANNULLERET | /api/fs/bestilling/{id} | Orientering om at bestilling er annulleret (af sælger/mægler) |
| SALGSOLGT | /api/fs/bestilling/{id} | Orientering om at ejendommen er solgt |
| SALGANNULLERET | /api/fs/bestilling/{id} | Orientering om at ejendommen er taget af |
| LEVERANDOERAENDRET | /api/fs/bestilling/{id} | Orientering om ændring af bygnings-sagkyndig |
| SAELGERACCEPT | /api/fs/bestilling/{id} | Meddelelse om accept af sælger-ansvarstilbud |
| VTR | /api/fs/downloadFile/{id} | Meddelelse om VTR-dokument. Dette er en særlig dokumenttype, der leveres i visse samarbejder. |
Der er to typer af bestillinger:
Når der foretages bestilling, vil selskabet modtage en BESTILLINGSKVITTERING. Der afventes herefter udarbejdelse af tilstandsrapport og el-eftersyn. Når begge er leveret, vil selskabet modtage en TILBUDSRAPPORTER. Selskabet kan nu hente bestillingsinformationer og dokumenter og udarbejde tilbud.
Der afsendes BESTILLINGSKVITTERING uanset hvad der er bestilt. Der kan derfor modtages meddelelse om bestilling, hvor der aldrig skal laves tilbud, f.eks. hvis der kun bestilles et energimærke. Det kan i bestillingen ses, hvad der er bestilt.
Inden rapportudarbejdelse er igangsat, kan bestillingen blive annulleret eller omfordelt til anden bygningssagkyndig. I dette tilfælde vil der hhv. blive afsendt BESTILLINGANNULLERET og LEVERANDOERAENDRET.
Efter TILBUDSRAPPORTER er modtaget, kan der forekomme REVISION, dvs. meddelelse om at der er modtaget en revideret tilstandsrapport.
Ligeledes kan der endnu senere i forløbet forekomme FORNYELSE. Denne hændelse kan kun forekomme på udvidede bestillinger og på salg, hvor liggetiden overstiger rapporternes gyldighedsperiode.
Hændelserne SALGSOLGT og SALGANNULLERET kan principielt forekomme på et vilkårligt tidspunkt i salgets livscyklus.
Disse bestillinger har et meget simplere forløb, idet der kun afsendes TILBUDSRAPPORTER ved modtagelsen af bestillingen. Ud over denne hændelse kan kun forekomme SALGSOLGT og SALGANNULLERET.
Alle hændelser meddeles på bestillingsniveau. For bestillinger, hvor der skal udarbejdes rapporter, kan det overordnede salg bestå af flere bestillinger således at de relevante dokumenter er leveret på flere bestillinger. Boligdok muliggør at mæglere kan bestille de forskellige produkter hver for sig, ligesom FORNYELSE oftest vil forekomme på en ny bestilling under salget. For at selskabet kan indhente alle relevante dokumenter med én operation ved f.eks. TILBUDSRAPPORTER, er der i API-funktionen til indhentning af bestillingsdata mulighed for at angive hvilket scope, der skal indhentes for. Scope SALG og TILBUD giver alle salgets dokumenter listet kronologisk med nyeste først. SALG giver alle salgets dokumenter, og TILBUD giver kun de, der er relevante for forsikringsselskabet til tilbudsgivning.
Som udgangspunkt vil bestillere, som f.eks. mæglersystemer, få én kø, hvor samtlige events vil blive sendt ud på. Kø navnet vil være event.{mæglersystemId}.
Hvis systemleverandøren har en systemarkitektur, der f.eks. er kundeopdelt, kan der være behov for at lade dette afspejle i kø-strukturen. Sådanne ønsker/behov koordineres med Boligdok.
| Eventtype | Url til api | Beskrivelse |
|---|---|---|
| BESIGTIGELSESINFO | /api/maegler/bestilling/{id} | Denne event sendes når byggesagkyndig har registreret besigtigelsesinformationer |
| BESTILLINGSKVITTERING | /api/maegler/bestilling/{id} | Sendes når bestilling er modtaget og der er tildelt en byggesagkyndig |
| DOKUMENTINFO | /api/maegler/downloadFile/{id} | Sendes når der bliver uploadet nyt dokument |
| BESTILLINGANNULLERET | /api/maegler/bestilling/{id} | Sendes når byggesagkyndig annullerer bestillingen |
| PRODUKTFJERNET | /api/maegler/bestilling/{id} | Sendes når byggesagkyndig fjerner et produkt |
| PRODUKTTILFOEJET | /api/maegler/bestilling/{id} | Senders når byggesagkyndig tilføjer et produkt. |
| LEVERANDOERAENDRET | /api/maegler/bestilling/{id} | Orientering om ændring af bygningssagkyndig |
Som udgangspunkt vil byggesagkyndige kun få en kø, hvor samtlige events vil blive sendt ud på. Kø navnet vil være event.{byggesagkyndigId}.
| Eventtype | Url til api | Beskrivelse |
|---|---|---|
| BESTILLINGSKVITTERING | /api/v2/bs/bestillinger/{id} | Sendes når bestilling er modtaget og der er tildelt en byggesagkyndig |
| BESTILLINGANNULLERET | /api/v2/bs/bestillinger/{id} | Sendes når mægler annullerer bestillingen |
| SALGSOLGT | /api/v2/bs/bestillinger/{id} | Sendes når Boligdok registrer at boligen er solgt |
| SALGANNULLERET | /api/v2/bs/bestillinger/{id} | Sendes hvis mægler tager boligen af markedet |
For dem, der skal udvikle integrationen mod køen, kan der henvises til denne web-site, hvor der er nyttige eksempler og dokumentation.