Dimona via webservice

U kunt uw aangiften naar de RSZ versturen via een REST-webservice. Uw softwareleverancier integreert die in uw bestaande informaticasysteem.
De technische informatie op deze pagina is bedoeld voor IT-diensten en softwareontwikkelaars.

Gebruikt u de REST-webservice van de sociale zekerheid nog niet?

Voordat u de REST-webservice van de sociale zekerheid in gebruik neemt, moet u voor uzelf of uw opdrachtgever een account maken en de beveiliging regelen.

Iemand aanstellen als technisch beheerder

U kunt iemand van uw informaticadienst aanstellen om de kanalen van uw onderneming te beheren in de onlinedienst Chaman. Ga daarvoor naar de onlinedienst Toegangsbeheer en geef daar toegang tot Chaman aan de persoon in kwestie.

Het REST-kanaal activeren en configureren in Chaman

In de online service Chaman (Channel Management) configureert u de verschillende communicatiekanalen die bij de diensten van de sociale zekerheid horen. Om het REST-kanaal voor uw onderneming te activeren, moet u een X.509-certificaat uploaden dat uw onderneming of clienttoepassing identificeert. U moet dat certificaat dus hebben voordat u Chaman kunt configureren.

Een certificaat voor uw onderneming krijgen

Om ervoor te zorgen dat de oproepen van uw applicatie naar de REST-API's veilig zijn, hebt u een certificaat op naam van uw onderneming nodig. U hebt verschillende opties:

U bestelt het certificaat bij een erkende certificatie-autoriteit. Dit is de certificatie-autoriteit die wij momenteel ondersteunen:

Certificatie-autoriteit	Type certificaat	Link
GlobalSign	PersonalSign 3 Pro	https://shop.globalsign.com/en/belgian-government-services

U gebruikt een zelfondertekend (self-signed) certificaat op naam van uw onderneming. De procedure om dit type certificaat te genereren, beschrijven we hier voorlopig niet. Normaal gezien maakt de IT-dienst van uw onderneming dit type certificaat aan met een tool zoals OpenSSL. Houd rekening met de volgende beperkingen bij het aanmaken van uw zelfondertekend certificaat:

Geldigheidscriteria	Toegestane waarden
Algoritme om het sleutelpaar te maken	RSA of EC
Sleutelgrootte (bits)	voor RSA: 2048, 3072 of 4096 voor EC: P-384 of P-521
Digest-algoritme van de handtekening van het certificaat	SHA-256, SHA-384 of SHA-512
Key Usage van het certificaat	Digital Signature

Het REST-kanaal in Chaman configureren

Om het REST-kanaal te activeren en uw certificaat te configureren, meldt u zich aan de onlinedienst Chaman.

Als de contactgegevens van de technisch beheerder van uw onderneming nog niet in de onlinedienst staan, moet u die eerst invullen en opslaan. Daarna pas kunt u d volgende stappen uitvoeren.

Klik in Chaman onder ‘Webservices account’ op ‘Een webservice account toevoegen’. Vul dan het onderstaande formulier als volgt in:

Kies ‘REST’. Als u dat geselecteerd hebt, verschijnen de bijbehorende velden.
Voer de naam in die u aan uw REST-account wilt geven.
Kies de rechten die u aan dit account wilt toewijzen.
Upload het certificaat dat uw REST-client zal gebruiken. U moet een naam opgeven voor dat certificaat.
Druk op de knop ‘Bevestigen’ om het aanmaken van het REST-account te bevestigen.

Als u deze stappen doorlopen hebt, wordt de OAuth Client ID weergegeven die bij het account hoort. Deze Client ID heeft de vorm ‘self_service_expeditor_X’, waarbij X het afzendernummer is dat aan u toegewezen is.

Bewaar deze Client-ID, want hij wordt gebruikt bij het aanvragen van uw OAuth-toegangscode.

OAuth-beveiliging opzetten

De REST-webservice van de sociale zekerheid is beveiligd. Voordat u hem kunt gebruiken, moet u het OAuth-beveiligingsprotocol implementeren. Steun daarvoor op de volgende documentatie:

OAuth2 Integration Client Credential .pdf - Nieuw venster
Javacode om de OAuth te implementeren: ClientCredentialTokenGenerator.java Nieuw venster

De REST-webservice voor Dimona

Een bijzonderheid van de REST-webservice voor Dimona is dat de RSZ geen synchrone behandeling van de aangiften kan garanderen. Daarom is het functioneren van de webservice in 2 aparte transacties opgedeeld:

POST: een aangifte indienen, en
GET: het resultaat van de behandeling van de aangifte bekijken.

De behandelingstijd van een Dimona varieert. Dat wil zeggen dat u misschien meerdere ‘GET’-oproepen moet doen om het resultaat van de behandeling van uw aangifte te zien. U zult dus een ‘Retry’-mechanisme moeten implementeren, zoals beschreven in onze documentatie. We leggen u ook uit welke frequentie uw ‘Retry’ moet hebben om het Dimonasysteem niet te overspoelen met oproepen.

Zo werkt het: Functionele documentatie REST-webservice voor Dimona .pdf - Nieuw venster