x-correlation-id

HTTP header. Zie ook: Werking en overzicht uitzonderingen MAGDA RESTful services.

Dit is het unieke transactie ID, gebruikt voor logging en foutafhandeling.

ja

idempotency-key

HTTP header. Zie ook: Werking en overzicht uitzonderingen MAGDA RESTful services.

Belangrijke opmerking: Deze key heeft als doel om, indien u beslist eenzelfde bericht te HERverzenden, ervoor te zorgen dat hetzelfde bericht niet meerdere keren ter beschikking gesteld wordt aan de ontvanger. De x-correlation-id is het unieke id per verzending. De idempotency-key dient echter gelijk gehouden te worden bij een herverzending van een zelfde bericht. Op die manier is het voor de documentendienst duidelijk dat het om een herverzending gaat.

nee

messageToSend

JSON-beschrijving van messageToSend

ja

upfile1

Document.

nee

upfile2

Document.

nee

upfile3

Document.

nee

upfile4

Document.

nee

upfile5

Document.

nee

upfile6

Document.

nee

…

delivery

String

• EBOX

• PAPER

• AUTOMATIC

• PAPER_AND_EBOX

Standaard: AUTOMATIC = het bericht wordt altijd afgeleverd in de eBox. Indien de ontvanger geen toestemming heeft gegeven voor gebruik eBox, gebeurt er ook een verzending via papier.

Opgelet: AUTOMATIC of PAPER_AND_EBOX delivery is enkel mogelijk wanneer u als verzender zowel aangesloten bent voor de PAPER als voor EBOX flow.

ja

eboxDeliveryData

Zie: eboxDeliveryData: MessageToPublish

nee

paperDeliveryData

Zie: paperDeliveryData: paperDeliveryData

nee

businessDataList

Array

Zie: BusinessDataToPublish

nee

recipient

ja

eboxType

String

• CITIZEN

• ENTERPRISE

Citizen: eBox burgers
Enterprise: eBox onderneming

eboxIdValue

String

INSZ nummer indien eboxType = "CITIZEN"

KBO nummer indien eboxType = "ENTERPRISE"

forTheAttentionOf

Belangrijke opmerking: enkel voor ebox onderneming

Indien bestemd voor een specifiek persoon binnen de onderneming

nee

id

String

Mogelijkheid om INSZnr mee te geven. Indien er ingelogd wordt met dat specifieke INSZnr ziet de persoon in kwestie dat er bericht is gericht aan zijn/haar INSZnr.

type

String

Belangrijke opmerking: enkel voor ebox onderneming

Hier moet "person" ingevuld worden indien er bij id een INSZnr wordt meegegeven. Indien de persoon met dat specifieke INSZnr zich aanmeldt, zal die persoon zien dat er een bericht specifiek voor hem/haar is.

name

String

Indien er geen INSZ nr wordt meegegeven, kan hier een naam worden ingevuld. 

Indien de persoon met die naam zich aanmeldt, zal die persoon niet zien dat er een bericht specifiek voor hem/haar is, maar wordt wel de naam weergegeven van de persoon voor wie het bedoeld is.

originalMessageId

String

Originele ID voor bidirectioneel gebruik.

nee

subject

Het onderwerp per ondersteunde taal.

ja

nl

Max 320 characters

fr

Max 320 characters

de

Max 320 characters

messageTypeId

String

Identificatie van bericht type. Voor ebox Burger is er slechts 1 bericht type: Persoonlijk geadresseerde brief met een standaard geldigheid van 3 jaar. Dit zal automatisch ingevuld worden door MAGDA.

Voor ebox Onderneming zijn er 2 bericht types, 1 met een geldigheid van 6 maanden en 1 met een geldigheid van 2 jaar. Dit zal automatisch ingevuld worden door MAGDA op basis van de informatie verkregen tijdens het aansluitingsproces. Indien de afnemer dit zelf wenst in te vullen, is dit ook mogelijk.

De geldigheid kan overschreven worden op basis van de datum die wordt meegeven bij expirationDate.

Dit id kan automatisch ingevuld worden door MAGDA op basis van de verkregen informatie na succesvol onboarden

nee

expirationDate

Date-time

Formaat: yyyy-MM-dd'T'HH:mm:ssXXX.

EBOX: Vervaldatum van het bericht in de eBox.

Indien PaperDeliveryData.documentAvailableUntilDate ook aangeboden wordt, wordt het maximum van deze beide datums genomen als vervaldatum van het bericht in de eBox

nee

senderOrganizationId

String

KBOnummer van de verzendende organisatie

Formaat: [0-1][0-9]{9}

Dit id wordt verkregen tijdens het onboarding proces en zal automatisch worden ingevuld door MAGDA op basis van de verkregen informatie na succesvol onboarden

nee

senderApplicationId

String

Dit id wordt verkregen tijdens het onboarding proces en en zal automatisch worden ingevuld door MAGDA op basis van de verkregen informatie na succesvol onboarden

nee

registeredMail

Boolean

• true

• false

Indicatie of het over een aangetekende zending gaat.

Standaard: false

nee

attachments

Array

Zie: AttachmentToPublish

nee

bodyMainContent

Boolean

• true

• false

Als de waarde = "true": dan wordt de bodyContent beschouwd als de hoofdinhoud. In dat geval wordt bodyContent dan ook verplicht.

Als de waarde = "false": dan wordt de bodyContent niet beschouwd als de hoofdinhoud maar als een annex. In dat geval is bodyContent niet verplicht.

Belangrijke opmerking: een bericht wordt als "gelezen" aanzien van zodra de MainContent is geraadpleegd.

Standaard: false

ja

bodyContent

nee

nl

String

fr

String

de

String

businessDataList

Array

Zie: BusinessDataToPublish

nee

paymentData

Object

Zie: paymentData

nee

replyAuthorized

Boolean

• true

• false

Aanduiding of er antwoord mag gestuurd worden.

Standaard: false

ja

registeredMail

Boolean

• true

• false

Indicatie of het over een aangetekende zending gaat.

Belangrijke opmerking: Indien registeredMail = "true" dan is retourAddress verplicht

Standaard: false

nee

acknowledgmentOfReceipt

Boolean

• true

• false

Aanduiding of de ontvanger een document moet tekenen om ontvangst te bevestigen. Dit document wordt vervolgens gestuurd naar het retourAddress.

Belangrijke opmerking: Indien acknowledgmentOfReceipt = "true" dan is retourAddress verplicht

Standaard: false

nee

side

String

• RV

• RS

• RV_NEWSHEETPERATTACHMENT

Aanduiding recto verso.

Standaard: RV

• RV_NEWSHEETPERATTACHMENT laat toe om elke bijlage te starten op een afzonderlijke pagina.

nee

offset

integer

• 0

• 1

• 2

• 3

• 4

Duidt aan op welke pagina de print van de PDF moet starten.

keycommunicatedViaChannel = NO_DOWNLOAD_KEY

• No Offset + side = RV => verso eerste blad

• No Offset + side = RS => recto tweede blad

• Offset = 0 => recto eerst blad (eerste derde vrij houden in het eerste blad van uw PDF → Om er uw logo en adres balk te kunnen laten printen)

• Offset = 1 + side = RV => verso eerste blad

• Offset = 1 + side = RS => recto tweede blad

• Offset = 2 + side = RV => recto tweede blad

• Offset = 3 + side = RV => verso tweede blad

keycommunicatedViaChannel = SAME_PAGE

• No Offset => recto tweede blad

• Offset = 1 + side = RS => recto tweede blad

• Offset = 2 + side = RV => recto tweede blad

• Offset = 3 + side = RV => verso tweede blad

keycommunicatedViaChannel = SEPARATE_PAGE

• No Offset => recto derde blad

• Offset = 2 + side = RS => recto derde blad

• Offset = 3 + side = RV => verso tweede blad

• Offset = 4 + side = RV => recto derde blad

keycommunicatedViaChannel = SEPARATE_LETTER

• No Offset => recto tweede blad

• Offset = 1 + side = RS => recto tweede blad

• Offset = 2 + side = RV => recto tweede blad

• Offset = 3 + side = RV => verso tweede blad

Andere combinaties worden niet toegelaten en leiden tot een Bad request

nee

documentType

String

Type van het document. Bijvoorbeeld "factuur", "informatieve brief",... Dit veld kan door de verzender gebruikt worden indien hij graag voor eigen rapportering/overzichten een opsplitsing maakt tussen verschillende types documenten.

nee

priority

String

• dlp1

• dlp3

Aanduiding binnen hoeveel dagen de verzending moet afgeleverd worden: 1 dag, of 3 dagen.

Belangrijke opmerking: verzendingen die na 18u verstuurd worden, worden pas de dag erna verwerkt.

Standaard: dlp3

nee

documentAvailableUntilDate

Date

De ontvanger kan de originele digitale documenten downloaden via een QR code/link en een persoonlijke sleutel die hij eveneens per brief ontvangt. Deze datum verwijst naar de datum tot wanneer de ontvanger deze documenten kan downloaden.

Maximum bewaartermijn is 3 jaar.

Dit veld wordt op een datum van 3 maand in de toekomst gezet indien deze niet meegegeven wordt.

Indien EBoxDeliveryData.expirationDate ook aangeboden wordt, wordt het maximum van deze beide datums genomen.

Formaat: yyyy-MM-dd

nee

keyCommunicatedViaChannel

string

• SAME_PAGE

• SEPARATE_PAGE

• SEPARATE_LETTER

• NO_DOWNLOAD_KEY

Indicatie of de persoonlijke sleutel op een aparte pagina of via een aparte brief moet verstuurd worden. Indien de documenten klasse 3 of klasse 4 inhoud bevatten, moet de persoonlijke sleutel op een aparte pagina of via een aparte brief verstuurd worden.

Standaard: SEPARATE_PAGE

Belangrijke info: indien je geen download mogelijkheid wil voorzien, kies je voor NO_DOWNLOAD_KEY. De download mogelijk is voorzien in geval de ontvanger de originele digitale handtekening(en) wil kunnen controleren, dus vooral omwille van rechtsgeldigheid. Indien je als verzender deze optie niet nodig hebt, is het soms beter van te kiezen voor NO_DOWNLOAD_KEY aangezien de download mogelijks voor extra oproepen naar de helpdesk kan zorgen.

nee

address

Mogelijkheid om te kiezen voor aflevering naar:

• adres

• rijksregisternummer van burger

• ondernemingsnummer

Een geldige vraag bevat slechts 1 van de vermelde elementen.

nee

title

String

nee

firstName

String

1 van deze 3 velden moet verplicht ingevuld zijn

lastName

String

organisation

String

line1

String

ja

line2

String

nee

postalCode

String

ja

city

String

ja

region

String

nee

country

String

ISO2 or ISO3 country code

ja

retourAddress

ja indien aangetekend

belangrijke opmerking: ook al zijn de zendingen niet aangetekend, wordt het toch aangeraden van een retour adress te voorzien, zodat verzender zelf de brieven terug krijgt indien er geen aflevering was

title

String

nee

firstName

String

1 van deze 3 velden moet verplicht ingevuld zijn

lastName

String

organisation

String

line1

String

ja

line2

String

nee

postalCode

String

(ja → om de kans op een goede aflevering te verhogen)

city

String

(ja → om de kans op een goede aflevering te verhogen)

region

String

nee

country

String

ISO2 country code

ja

sendPaperIfNotReadByDate

Date-Time

Met dit element kan een uitgestelde papieren verzending gerealiseerd worden: enkel mogelijk bij gebruik van AUTOMATIC verzending van een document.

Indien deze datum ingevuld is én de bestemmeling heeft consent gegeven voor het gebruik van EBOX, dan gebeurt er alsnog een papieren verzending indien de bestemmeling het ebox bericht niet heeft gelezen voor de ingestelde datum. Deze datum moet in de toekomst gelegen zijn met een maximum van 30 dagen.

Indien de bestemmeling geen EBOX consent heeft gegeven, wordt deze datum genegeerd en vertrekt de papieren zending onmiddellijk. In dat geval zal dit kenbaar gemaakt worden via een exception header in het antwoord.

In beide gevallen krijgt de caller synchroon zowel een paper message Id als een ebox message ID terug, waarmee verdere processing opgevolgd kan worden.

nee

receiverSsin

String

Rijksregisternummer: laat toe om bij een papieren verzending naar een burger, het adres van de burger op te vragen via het rijksregisternummer van de burger. Het adres wordt automatisch synchroon opgehaald tijdens de verwerking van een POST messages request.

Kan niet in combinatie met blok address of receiverEnterpriseNumber (zie veld hieronder) gebruikt worden.

Indien dit veld in combinatie met een ebox verzending gebruikt wordt, dan is dit enkel mogelijk indien het ebox bericht gericht is aan hetzelfde rijksregisternummer.

Belangrijke opmerking: opvraging van het adres op basis van rijksregisternummer kan enkel indien de verzender hiervoor gemachtigd is

nee

receiverEnterpriseNumber

String

Ondernemingsnummer: laat toe om bij een papieren verzending naar een onderneming, het adres van de onderneming op te vragen via het ondernemingsnummer van de onderneming. Het adres wordt automatisch synchroon opgehaald tijdens de verwerking van een POST messages request.

Kan niet in combinatie met blok address of receiverSsin (zie veld hierboven) gebruikt worden.

Indien dit veld in combinatie met een ebox verzending gebruikt wordt, dan is dit enkel mogelijk indien het ebox bericht gericht is aan hetzelfde ondernemingsnummer.

nee

attachmentTitle

Belangrijke opmerking: het is mogelijk dat de HIP (applicatie waarmee iemand zijn ebox berichten bekijkt) geen rekening houdt met de info die via dit veld wordt meegegeven

nee

nl

String

fr

String

de

String

httpPartName

String

De naam van de Content-Disposition dat de corresponderende binary bevat:

bvb upfile1, upfile2, upfile3, …

ja

mainContent

Boolean

• true

• false

Als de waarde = "true": dan wordt het attachment beschouwd als de hoofdinhoud.

Als de waarde = "false": dan wordt het attachment niet beschouwd als de hoofdinhoud maar als een annex.

Belangrijke opmerking: een bericht wordt als "gelezen" aanzien van zodra de MainContent is geraadpleegd.

Standaard: false

ja

digest

Object

digestValue

String

Digest value die wordt teruggeven door de cryptografische hash functie, base64url (https://tools.ietf.org/html/rfc4648#section-5)

ja

digestMethod

Array

Cryptografische hash functie die gebruikt wordt voor de digest, bv. sha_256

ja, 

attachmentSigned

Boolean

• true

• false

Aanduiding of attachment getekend is.

Standaard: false

nee

Een businessData element bevat businessData gelinkt aan het verzonden bericht. Een business data element bestaat uit een naam en een reeks waarden, waarbij minimaal een sleutel en een reeks waarden nodig zijn.

key

String

Sleutel van het business element

ja

name

nee

nl

String

fr

String

de

String

description

nee

nl

String

fr

String

de

String

values

Array

ja

nl

String

fr

String

de

String

paymentDataId

String

eigen id van de verzender

ja

totalAmount

Number (double)

het verschuldigde bedrag, met BTW

formaat: ^\d*(.\d){0,1}\d{0,1}$

nee

amount

Number (double)

het verschuldigde bedrag, zonder BTW

formaat: ^\d*(.\d){0,1}\d{0,1}$

ja

vatAmount

Number (double)

BTW

formaat: ^\d*(.\d){0,1}\d{0,1}$

ja

currency

String

Munteenheid, volgens ISO 4217

Momenteel ondersteunen onze bronnen enkel EUR.

ja

dueDate

Date-time

Datum waarop betaling ten laatste moet uitgevoerd zijn.

Formaat: yyyy-MM-dd'T'HH:mm:ssXXX bv. 2019-10-06T01:00:00.000+0000

Opgelet: deze datum moet kleiner zijn dan of gelijk aan de vervaldatum van het ebox bericht zelf

ja

iban

String

Het IBAN (International Bank Account Number) nummer, volgens ISO 13616:2007

ja

bic

String

Bank Identifier Code

nee

reference

String

Mededeling bij betaling

nee

beneficiary

name

String

ja

address

nee

title

String

nee

firstName

String

maximum aantal karakters: 320

nee

lastName

String

maximum aantal karakters: 320

nee

organisation

String

nee

line1

String

maximum aantal karakters: 320

ja

line2

String

nee

postalCode

String

maximum aantal karakters: 20

nee

city

String

maximum aantal karakters: 120

nee

region

String

nee

country

formaat: ISO2 country code

maximum aantal karakters: 8

ja

remittanceInformationUnstructured

String

Ongestructureerde mededeling

maximum aantal karakters: 140

nee

remittanceInformationStructured

gestructureerde mededeling

de som van aantal karakters van reference, type en issuer mag maximum 280 zijn

nee

reference

String

ja

type

String

nee

issuer

String

nee

qrCode

QrCodeToPublish

data

String

deep link QR code

maximum aantal karakters: 320

ja

type

String

type zoals bepaald door de bank

maximum aantal karakters: 320

ja

httpPartName

String

QR Image as HttpPart

ja

delivery

delivery = 'EBOX' of delivery = 'AUTOMATIC' en er zit geen eboxDeliveryData blok in de payload

400 BAD REQUEST

The data block eboxDeliveryData is required when deliveryChannel is EBOX or AUTOMATIC

delivery

delivery = 'EMAIL ' en er zit geen emailDeliveryData blok in de payload

400 BAD REQUEST

The data block emailDeliveryData is required when deliveryChannel is EMAIL

delivery

delivery = 'PAPER' of delivery = 'AUTOMATIC' en er zit geen paperDeliveryData blok in de payload

400 BAD REQUEST

The data block paperDeliveryData is required when delivery is PAPER or AUTOMATIC

acknowledgmentOfReceipt 

acknowledgmentOfReceipt = 'true' en er is geen retourAddress voorzien

400 BAD REQUEST

The data block retourAddress is required when acknowledgmentOfReceipt = true

acknowledgmentOfReceipt

acknowledgmentOfReceipt = 'true' en registeredMail = 'false'

400 BAD REQUEST

The option acknowledgmentOfReceipt is only allowed to be true when registeredMail is true

emailDeliveryData/sender/email

emailDeliveryData/sender/email is leeg

400 BAD REQUEST

A Sender Email address should be provided or created in your MAGDA setup

emailDeliveryData/sender/name

emailDeliveryData/sender/name is leeg

400 BAD REQUEST

A Sender Name should be provided or created in your MAGDA setupis true

elke eigenschap

indien een eigenschap geen waarde heeft, dient u deze weg te laten (en dus niet aan te bieden met een null value

400 BAD REQUEST