Bliv klar til at kode: Postkomponent
På denne side kan du læse om:
Forudsætninger
For at kunne påbegynde udviklingsarbejdet skal følgende forudsætninger være på plads:
- Du er oprettet som leverandørorganisation og har adgang til Fælleskommunalt Administrationsmodul.
- Dit it-system er registreret i Fælleskommunalt Administrationsmodul.
- Du har anmodet om og fået godkendt de nødvendige serviceaftaler for at kunne:
- Kalde Postkomponentens webservices.
- Modtage statuskvitteringer for post-forsendelser via Beskedfordeleren.
Du kan læse mere om serviceaftaler og finde vejledning til oprettelse i Fælleskommunalt Administrationsmodul.
Hvis du allerede har integreret til Beskedfordeler eller Adgangsstyring (for systemer), er du allerede godt på vej, her vil det blot være tilpasning til beskedtyper samt veksling af token.
SF1601 Afsend post
For at benytte Postkomponenten til at afsende post, skal du integrere til en række services, der falder i tre kategorier: Adgangsstyrring, Webservices og Beskedservices. Vi har i nedenstående samlet generelle informationer om disse, herunder vejledninger samt kodeeksempler, og du kan med fordel studere informationen, førend du går i dybden med de specifikke services for Postkomponenten:
Adgangsstyring
Postkomponenten inkluderer både Web- og Beskedservices, og adgangen til disse reguleres med Fælleskommunal Adgangsstyring for systemer.
Via Security Token Services kan et anvendersystem trække SAML tokens og benytte disse for at tilgå Postkomponentens services.
- Beskedservices (AMQP): SAML token indlejres i AMQP-forbindelsen vha. SASL
- Webservices (REST): SAML token veksles til Opaque token og indlejres i REST-kald
(Service til veksling af tokens er under udarbejdelse)
Webservices
Postkomponenten udstiller fem synkrone RESTful webservices, som anvendersystemer kan benytte til at afsende post – både via Digital Post og Fjernprint – samt fremsøge tilmeldingsstatus, organisation og kontaktpunkt.
Disse services er beskrevet i integrationsbeskrivelser for SF1601 Afsend post og er suppleret med tekniske specifikationer (OpenAPI/OAS).
Beskedservices
Via Beskedfordeleren er det muligt for anvendersystemer at modtage statuskvitteringer for post-forsendelser, der er sendt via Digital Post eller Fjernprint. Til dette formål udstiller Beskedfordeleren to services, der tillader anvendersystemet at modtage kvitteringerne enten via pull (AMQP) eller push (REST).
Integrationsbeskrivelsen for SF1461 Modtag beskeder via Beskedfordeler beskriver Beskedfordelerens services til modtagelse af beskeder og giver indblik i begreber, forretningsflow, specifikationer for endpoints etc.
Hvis du ikke tidligere har arbejdet med Beskedfordeleren, kan du med fordel læse vejledningen Kom godt i gang med Fælleskommunal Beskedfordeler, der med udgangspunkt i en demoklient (inkl. kildekode) beskriver trin-for-trin, hvorledes du sender og modtager beskeder.
Kodeeksempler - MeMo
Vi har udarbejdet seks kodeeksempler (XML) på, hvordan man implementerer seks centrale opmærkninger med MeMo i sin postbærende løsning.
Du kan hente kodeeksemplerne via nedenstående links
SF1606 Modtag post
Services
For at modtage post via Postkomponenten skal du udstille en callback webservices, som komponenten kan levere forsendelser til.
Callback Webservice
Anvendersystemer, der ønsker at modtage post, skal udstille en synkron RESTful webservice, som Postkomponenten kan levere forsendelser til. Kommunikationen mellem anvendersystem og Postkomponenten sikres med 2-vejs TLS, hvor Postkomponenten benytter Serviceplatformens OCES certifikat som klient certifikat.
Denne callback service er beskrevet i integrationsbeskrivelser for SF1606 Modtag post og er suppleret med tekniske specifikationer (OpenAPI/OAS).
(Bemærk at terminologien for anvendersystemer kan virke modsigende i forbindelse med callback services; systemerne siges at anvende en sådan service, trods de udstiller den).
Test
På det eksterne testmiljø vil det være muligt at teste integration til Postkomponenten. Det forudsætter, at du har indgået en aftale med en testkommune, der skal assistere dig med:
- Godkendelse af serviceaftaler
- Oprettelse hos Digital Post og/eller fjernprintleverandør af de breve/materialer, som du ønsker at sende fra dit anvendersystem.
Du kan læse mere om det eksterne testmiljø, herunder retningslinjer her.
Brugergrænseflade
Via brugergrænsefladen kan kommunen opsætte og registrere distributionsregler for indkommende post og registrere/opsætte fjernprintleverandør på dine afsendersystemer.
- Brugergrænseflade til Fælleskommunal Postkomponent (TEST)
- Brugergrænseflade til Fælleskommunal Postkomponent (PROD)
Teknologi
- Postkomponenten udstilles på Serviceplatformen med RESTful services med Opaque Token sikkerhed. Generelt benyttes XML til afsendelses af post, mens opslag services benytter JSON. Services er defineret i OpenAPI 3.x format.
- Statuskvittering modtages via Beskedfordeler enter ved pull på AMQP eller push på en RESTful service. Formatet af kvitteringen er i begge tilfælde XML, som er defineret i XSD ver. 1.1.
- Generelt skal anvendere benytte den Fælleskommunale sikkerhedsarkitektur, der baserer sig på OIOSAML med en mindre udvidelse. For at benytte RESTful services skal der veksles fra SAML token til et Opaque token via en generel service i den fælleskommunale infrastruktur.
- Er anvendersystemet alerede på den fælleskommunale infrastruktur og benytter Token, er det kun veksling til Opaque Token, som skal implementeres for at kunne benytte Postkomponenten. Veksling af Token skyldes at RESTful services rent størrelsesmæssigt ikke kan indeholde et SAML token, hvis man ønsker at benytte standardopbygning af en RESTful service.