Meldingsutveksling

Endepunktene for meldingsutveksling:

Når man bruker APIet til meldingsutveksling samarbeider APIet med meldingstjeneren for å ivareta denne funksjonen. Meldingstjeneren vet om mottaker er en EDI-bruker eller en annen API-bruker og kan dermed kryptere og signere for sending over EDI, eller tilgjengeliggjøre meldingen for en annen API-bruker.

Meldings-APIet er sikret med HelseID, og man kan derfor ikke sende meldinger hvor avsender ikke stemmer med autentisert klient, og man kan heller ikke laste ned meldinger som er adressert til en annen mottaker enn den som er knyttet til påloggingen. Se mer informasjon i kapittel om HelseID.

Man kan se for seg tre scenarier i en utveksling mellom API-brukere og EDI-brukere. API til EDI, EDI til API og API til API. EDI til EDI håndteres av dagens EDI-løsning og er ikke relevant for API eller Meldingstjener.

API til EDI

Figur 2 illustrerer en API-bruker A1 som sender en fagmelding til EDI-bruker E1. Meldingstjeneren står for EbXml-kommunikasjonen med E1, og tilgjengeliggjør en Applikasjonskvittering til A1.

Figur 2 API til EDI

1. API-bruker bruker POST /Messages for å sende en fagmelding. Meldingstjeneren, som ved hjelp av Adresseregisteret vet at mottakeren er en EDI-bruker, starter en normal EDI meldingsutveksling med E1 med transportkvitteringer og Applikasjonskvittering.
2. Fagmelding overleveres til E1 via EDI
3. Meldingstjeneren mottar en transportkvittering og oppdaterer status på fagmeldingen
   1. A1 kan om ønskelig spørre etter status på en melding ved å bruke GET /Messages/{id}/Status
4. Applikasjonskvittering mottas og persisteres
5. Transportkvittering (leveres umiddelbart)
6. A1 mottar applikasjonskvittering.
   1. Merk at dette ikke er en push, men at API-brukeren først bruker GET /Messages/Unread for å få en liste over uleste meldinger etterfulgt av GET /Messages/{id}/BusinessDocument for å hente ned fagmeldingen. Denne bør igjen følges opp med en PUT /Messages/{id}/Read når meldingen er persistert hos A1 slik at den ikke hentes på nytt ved neste kall til GET /Messages/Unread
   2. API-brukeren kan velge å bare motta fagmeldinger med GET /Messages/Unread endepunktet. Status på en fagmelding (GET /Messages/{id}/Status) TEST inneholder også status på applikasjonskvitteringen og dette kan brukes som en enklere implementasjon for API-brukere som ikke ønsker å forholde seg til en XML i denne sammenhengen.

EDI til API

Figur 3 illustrerer en EDI-bruker E1 som sender en fagmelding til API-bruker A1.

Figur 3 EDI til API

1. E1 sender en fagmelding til A1. Denne mottas av Meldingstjeneren ettersom A1 er endret til denne adressen i Adresseregisteret
2. Meldingstjeneren svarer med transportkvittering så snart meldingen er persistert
3. A1 mottar fagmeldingen ved å bruke GET /Messages/Unread for å få tilbake Id på den uleste meldingen og deretter GET /Messages/{id}/BusinessDocument for å hente fagmeldingen
4. A1 leverer en applikasjonskvittering med POST /Messages, alternativt med POST /Messages/{id}/Apprec
5. Meldingstjeneren videreformidler applikasjonskvitteringen
6. Meldingstjeneren mottar transportkvittering og oppdaterer status på applikasjonskvitteringen

API til API

Figur 4 illustrerer en API-bruker A1 som sender en fagmelding til API-bruker A2.

Figur 4 Api til Api

1. A1 sender en fagmelding med POST /Messages til A2 som persisteres i meldingstjeneren
2. A2 henter ID til den uleste medlingen med GET /Messages/Unread og deretter fagmeldingen med GET /Messages/{id}/BusinessDocument
3. A2 sender en applikasjonskvittering med POST /Messages til A1, alternativt med POST /Messages/{id}/Apprec
4. A1 henter applikasjonskvitteringen enten
   1. som en XML med GET /Messages/Unread og GET /Messages/{id}/BusinessDocument
   2. som en Status-json med GET /Messages/{id}/Status

Sende til flere mottakere (kopimottakere)

I tillegg til å sende en fagmelding til en hovedmottaker kan man samtidig sende fagmeldingen til flere mottakere (kopimottakere), ved å legge disse til i fagmeldingen. Mottakerne kan være både API-brukere og EDI-brukere. Meldingsflyten for hver mottaker vil da være som beskrevet ovenfor, avhengig av om mottakeren er en API-bruker eller en EDI-bruker.

Kombinasjon av Objects og Messages APIene

Man kan bruke referansen som returneres fra Objects-APIet (DEFT) i fagmeldinger som har støtte for dette. Man bruker da Filereference-elementet istedenfor en Base64Container. Under visesvedlegg av begge typer, ett som filreferanse og ett som base64.

<RefDoc>
    <IssueDate V="2023-10-03T08:32:13.4909691Z" />
    <MsgType V="A" DN="Vedlegg" />
    <MimeType>image/png</MimeType>
    <Description>Capture.PNG</Description>
    <FileReference>https://api.deft.prod.nhn.no/Objects/dda2fbfc-271f-4794-8ae3-191c6f75232a_trust-me-im-a-dolphin.exe.</FileReference>
</RefDoc>
<RefDoc>
    <IssueDate V="2023-10-03T08:32:13.4884712Z" />
    <MsgType V="A" DN="Vedlegg" />
    <MimeType>image/png</MimeType>
    <Description>Bounce.png</Description>
    <Content>
        <Base64Container
            xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
            xmlns="http://www.kith.no/xmlstds/base64container">iVBORw0KGgoAA\....uQmCC</Base64Container>
    </Content>
</RefDoc>

Api-detaljer

NB! Detaljert beskrivelse av datatyper, request- og response-objekter, HTTP-statuskoder o.l. finnes i Swagger-UIet.

[POST/Messages]

Endepunktet forventer en json-body med innhold som under. Selve fagmeldingen sendes i json-feltet BusinessDocument. Det forventes en string som er base64-encodet XML. Det påkreves at encodingen til XML-en er UTF-8, og at dette deklareres i første linje. Eksempel: <?xml version="1.0" encoding="UTF-8"?>.

R = Required field

Respons: Endepunktet returnerer en 201 med en referanse til den lagrede ressursen, som senere kan brukes for å hente status på meldingen.

[GET /Messages]

NB! Ikke implementert ennå

Endepunktet krever et query-objekt med ulike felter for å hente ut meldinger, samt med støtte for paginering og sortering.

Respons: Endepunktet returnerer en liste med objekter som inneholder metadata om en fagmelding.

[GET /Messages/Unread]

Endepunktet krever et query-object som definerer hvilke HerId'er meldingen(e) skal være sendt til

Respons: Endepunktet returnerer en liste med objekter som inneholder ID-er til uleste meldinger per HER-ID

[GET /Messages/{id}]

NB! Ikke implementert ennå

Endepunktet krever en referanse (Id) til en melding. Denne hentes ut ved et kall til f.eks GET /Messages/Unread

Respons: Endepunktet returnerer metadata om en fagmelding.

[GET /Messages/{id}]/BusinessDocument

Endepunktet krever en referanse (Id) til en melding. Denne hentes ut ved et kall til f.eks GET /Messages/Unread

Respons: Endepunktet returnerer fagmeldingen i XML-format.

[GET /Messages/{id}/Status]

Endepunktet krever en id-referanse (guid).

Respons: Endepunktet returnerer en liste av objekter som inneholder status på responser fra hver mottaker/kopimottaker av fagmeldingen.

//todo: Denne er under utbedring, ettersom vi har inkludert Acknowledge, men ikke MessageError. PBI er opprettet.

[PUT /Messages/{id}/Read/{herId}]

Endepunktet krever en id-referanse (guid) og herId (int).

Respons: 204 No Content

[POST /Messages/{id}/Apprec{appRecSenderHerId}]

Endepunktet krever en id-referanse (guid) og herId (int). I tillegg kreves en json-body med ønsket Apprec-resultat.

Respons: Endepunktet returnerer en 201 med en referanse til den lagrede ressursen, som senere kan brukes for å hente status på meldingen.