Transaction API

Documenten en berichten versturen

Introductie

De Transaction API biedt toegang tot de Connect Postbus. Aanbieders kunnen berichten aanleveren via deze REST/JSON API. Het intermediair kan berichten uitsluitend via Aplaza ophalen op basis van het GRS-protocol dat gebaseerd is op SOAP XML. Aanbieders van berichten dienen een overeenkomst met Aplaza te hebben om gebruik te kunnen maken van deze API.

Voorwaarden berichtaanlevering

Ten aanzien van het succesvol aanleveren van berichten aan de API gelden een aantal voorwaarden waaraan voldaan moet worden.

Algemeen

Per request kan steeds maximaal 1 zip-bestand worden aangeleverd.
Het zip-bestand moet als base64-encoded string worden opgenomen in de request.
Een zip-bestand moet beperkt worden tot een maximale grootte van 50MB (base64-encoded), dit in verband met verwerkingstijd en time-out problemen.

Zip-bestand met documenten

Een zip-bestand met documenten mag meerdere documenten tegelijk bevatten voor verschillende ontvangers.
Een zip-bestand mag niet meer dan 100 documenten bevatten, dit in verband met verwerkingstijd en time-out problemen.
Een zip-bestand moet per document een bijgaand XML-bestand bevatten met metadata.
Het is niet mogelijk om in 1 XML-bestand metadata van meerdere documenten op te nemen. Ieder document heeft een eigen begeleidend XML-bestand.
Het is niet mogelijk om het document in het BY_DATA veld van het XML-bestand op te nemen. Het document moet als apart bestand naast de bijbehorende XML worden aangeleverd.
De bestandsnaam van het XML-bestand moet altijd met de prefix ‘0_200_2026_’ beginnen.
Het veld UN_ONTVAN bevat het postbusaansluitnummer van de ontvanger. Dit nummer wordt door Aplaza uitgegeven. Aanbieders van berichten moeten dus een administratie bijhouden van de aansluitnummers van de ontvangers waaraan ze berichten willen sturen. De nummers die Aplaza uitgeeft zijn numeriek, maar technisch gezien kan het veld ook alfabetische tekens bevatten.
Het veld UN_ZENDER bevat de POR-code van de aanbieder.

Voorbeeld XML-bestand:

<Contractdocument>
    <UN>
        <UN_ZENDER>A001</UN_ZENDER>
        <UN_ONTVAN>999999</UN_ONTVAN>
    </UN>
    <AL>
        <AL_VRWRKCD>0</AL_VRWRKCD>
        <AL_FUNCTIE>09</AL_FUNCTIE>
        <AL_DATACAT>33F</AL_DATACAT>
        <BY>
            <BY_VRWRKCD>0</BY_VRWRKCD>
            <BY_VOLGNUM>1</BY_VOLGNUM>
            <BY_BYLSRT>16</BY_BYLSRT>
            <BY_EXT>PDF</BY_EXT>
            <BY_URLBY>0_200_2026_PP12345.pdf</BY_URLBY>
            <BY_PROCESC>00002</BY_PROCESC>
            <BY_ENDBSTM>TP</BY_ENDBSTM>
            <BY_REACTIE>N</BY_REACTIE>
        </BY>
    </AL>
    <PP>
        <PP_VRWRKCD>0</PP_VRWRKCD>
        <PP_NUMMER>PP12345</PP_NUMMER>
        <PP_MYAAND>A001</PP_MYAAND>
        <VP>
            <VP_VRWRKCD>0</VP_VRWRKCD> 
            <VP_ANAAM>JANSEN</VP_ANAAM>
            <VP_VOORL>A.</VP_VOORL>
            <VP_GEBDAT>19700101</VP_GEBDAT>
        </VP>
    </PP>
</Contractdocument>

Zip-bestand met prolongatie- of mutatiebericht

Een zip-bestand met een prolongatie- of mutatiebericht mag maximaal 1 EDIFACT-bestand bevatten voor 1 ontvanger.
- Het is dus niet mogelijk om in een zip-bestand een EDIFACT-bestand aan te leveren dat zowel prolongatie als mutatieberichten bevat.
- Het is dus niet mogelijk om in een zip-bestand een combinatie van documenten en EDIFACT-bestanden aan te leveren.
Het prolongatiebericht EDIFACT-bestand moet in de bestandsnaam altijd met de prefix ‘0_770_7703’ beginnen.
Het mutatiebericht EDIFACT-bestand moet in de bestandsnaam altijd met de prefix ‘0_770_7702’ beginnen.
Het aansluitnummer van de ontvanger, dat door Aplaza wordt uitgegeven, moet in de UNB-regel worden verwerkt.

Beheer OpenID client

Op ANVA Hub kan door de beheerder een OpenID client aangemaakt en geconfigureerd worden. Indien ondersteuning nodig is bij het aanmaken en configureren van een OpenID client, dan kan hier een support ticket worden ingediend bij de Servicedesk. Voor gebruik met de Connect Postbus adviseren we het volgende:

Ken de rollen Basic en Postbusbeheerder toe aan de OpenID client.
Ken de toegang voor Systeem toe aan de OpenID client om gebruik te kunnen maken van de client credential grant.
Vernieuw het secret regelmatig om de security te bevorderen.

Token opvragen

POST /identity/token HTTP/1.1 
Host: api.anva.{{tld}} 
Authorization: Basic {{base64-encoded clientid:clientsecret}} 
Content-Type: application/x-www-form-urlencoded 
scopes=Basic%20POboxadministrator%20orgCode%3A{{organisatiecode}}&grant_type=client_credentials

Regel 1 betreft het endpoint voor het genereren van een token op basis van oAuth 2.0 + OpenID Connect.
Regel 2 bevat het domein waarbij {{tld}} een placeholder is voor het top-level-domain .cloud voor acceptatieomgeving en .io voor productieomgeving.
Regel 3 betreft de header van de request. Hierin moet de key Authorization worden opgenomen, met als value Basic + een base64 encoded string van de combinatie van het client id en het client secret.
Regel 5 bevat de rollen (Basic en POboxadministrator) waarvoor het token gegenereerd moet worden. Deze rollen moeten dus door de beheerder zijn toegekend aan de OpenID client.
Regel 5 bevat de organisatiecode waarbij de OpenID client is aangemaakt.

Zip-bestand versturen naar Connect Postbus

Request

Hieronder zie je een voorbeeld van een request waarmee een zip-bestand kan worden aangeleverd aan de Connect Postbus.

POST /transaction/aplaza HTTP/1.1 
Host: api.anva.{{tld}} 
Content-Type: application/json 
Authorization: Bearer {{jwt}} 
Cache-Control: no-cache 

{ 
  "data": { 
    "items": [ 
      { 
        "message": "{{base64-encoded ZIP-bestand}}" 
      } 
    ] 
  } 
}

Response

De request voor het uploaden van een zip-bestand levert weer een response op. Afhankelijk van het resultaat van de verwerking wordt de http status code en response body opgesteld. De meest voorkomende situaties:

200 OK
- Het zip-bestand en alle daarin aanwezige bestanden zijn succesvol verwerkt.
- In de body van de response wordt per bestand onder andere een id, de bestandsnaam en status teruggegeven.
- Status ‘compleet’ betekent dat het bestand succesvol is verwerkt.

207 Multi-Status
- Het zip-bestand is succesvol verwerkt, maar sommige bestanden uit het zip-bestand konden niet worden verwerkt.
- In de body van de response wordt per bestand onder andere een id, bestandsnaam en status teruggegeven.
- De aanbieder dient bij deze status te controleren welke bestanden niet succesvol zijn verwerkt. Aan de hand van de errorMessage kan men achterhalen wat de oorzaak is van de niet geslaagde verwerking, zoals bijvoorbeeld een onbekend postbusaansluitnummer.