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.

API-versjonering gjøres ved hjelp av headeren "api-version" med versjonsnummer som verdi. Denne headeren skal settes på alle kall til APIet. Støttet verdi er: "1"

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 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
   2. API-brukeren kan velge å bare motta fagmeldinger med GET /Messages 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 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 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 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.

Sende til et begrenset utvalg av mottakere

I visse tilfeller kan det være behov for å IKKE sende meldingen til alle mottakerne som er definert i fagmeldingen (hovedmottaker og alle kopimottakere). I ReceiverHerIdsSubset kan det sendes inn en liste med Her-Id'er til mottakere som meldingen skal sendes til. Dette vil det begrense utsendingen slik at BARE mottakere definert i denne listen vil motta meldingen.

Her-Id'er i ReceiverHerIdsSubset må stemme overens med Her-id'er til mottakerne som er definert som hovedmottaker eller kopimottakere i fagmeldingen. Det er ikke mulig å sende inn en Her-Id til en mottaker som ikke allerede finnes i fagmeldingen.

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 vises vedlegg 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 fagmelding samt metadata om fagmeldingen. Se tabellen under for hvilke felter som er påkrevd for hvilke meldingstyper ('Known none-MsgHead messages' og 'MsgHead based messages').

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]

Endepunktet krever et sett query-parametere med felter for å søke etter uleste meldinger.

Respons: Endepunktet returnerer en liste med uleste meldinger.

NB! Man kan via query-parameterne velge om man vil inkludere metadata eller ikke. Hvis man ikke inkluderere metadata vil meldingene i listen populeres med id-referanse på meldingen og HER-id for mottaker av meldingen. Inkluderer man metadata vil alle felter i meldingene bli populert.

[GET /Messages/{id}]

Endepunktet krever en id-referanse til en melding. Denne hentes ut ved et kall til GET /Messages

Respons: Endepunktet returnerer metadata om en fagmelding.

[GET /Messages/{id}]/BusinessDocument

Endepunktet krever en id-referanse til en melding. Denne hentes ut ved et kall til f.eks GET /Messages

Respons: Endepunktet returnerer fagmeldingen i XML-format.

[GET /Messages/{id}/Status]

Endepunktet krever en id-referanse.

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 og HER-id.

Respons: 204 No Content, som indikerer at meldingen er markert som lest

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

Endepunktet krever en request-url med id-referanse til meldingen det skal sendes applikasjonskvittering for og HER-id for avsender av applikasjonskvitteringen. I tillegg kreves en 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.