Dimona via web service

Vous pouvez envoyer vos déclarations à l'ONSS via un web service REST. Votre fournisseur de logiciels intègre celui-ci dans votre système informatique existant.
Les informations techniques présentes sur cette page s'adressent aux services informatiques et aux développeurs de logiciels.

Vous n'utilisez pas encore le web service REST de la sécurité sociale ?

Avant de pouvoir utiliser le web service REST de la sécurité sociale, vous devez créer un compte pour vous-même ou pour votre donneur d'ordre et paramétrer la sécurité.

Désigner une personne comme gestionnaire technique

Vous pouvez déléguer la gestion de vos canaux à votre service informatique, via Chaman. Pour cela, vous devez vous rendre dans le service en ligne Gestion des accès et attribuer l'autorisation d'accès au service en ligne Chaman pour les personnes concernées.

Activer et configurer le canal REST dans Chaman

Le service en ligne Chaman (Channel Management) vous permet de configurer les différents canaux de communication associés aux services de la Sécurité Sociale. L'activation du canal REST pour votre entreprise nécessite le chargement d'un certificat X.509 d'authentification qui identifie votre entreprise ou votre application cliente. Préalablement à la configuration Chaman, vous devez donc disposer de ce certificat.

Obtenir un certificat d'authentification pour votre entreprise

Pour permettre la sécurisation des appels effectués par votre application sur les API REST, vous devez disposer d'un certificat d'authentification au nom de votre entreprise.
Plusieurs options s'offrent à vous :

Vous pouvez commander ce certificat auprès d'une autorité de certification reconnue. Voici la liste des autorités de certification actuellement supportées :

Autorité de certification	Type de certificat	Lien
GlobalSign	PersonalSign 3 Pro	https://shop.globalsign.com/en/belgian-government-services

Vous pouvez utiliser un certificat self-signed au nom de votre entreprise. La procédure pour générer ce type de certificat n'est pour l'instant pas décrite ici. La génération de ce type de certificat est généralement prise en charge par le service informatique de votre entreprise via l'utilisation d'un outil tel que OpenSSL. Veuillez respecter les contraintes suivantes lors de la création de votre certificat self-signed :

Critère à respecter	Valeurs admises
Algorithme de génération de la paire de clés	RSA ou EC
Taille des clés (bits)	Pour RSA : 2048, 3072 ou 4096 Pour EC : P-384 ou P-521
Algorithme de digest associé à la signature du certificat	SHA-256, SHA-384 ou SHA-512
Key Usage du certificat	Digital Signature

Configuration du canal REST dans Chaman

Pour procéder à l'activation du canal REST et à la configuration de votre certificat d'authentification, connectez-vous au service en ligne Chaman.

Lorsque vous accédez à Chaman, si les coordonnées de contact du gestionnaire technique de votre entreprise ne sont pas disponibles, vous devrez les compléter (et les enregistrer) avant de pouvoir réaliser les actions ci-dessous.

Dans Chaman, dans la section associée aux canaux web services, cliquez sur “Ajouter un compte Web service". Complétez ensuite le formulaire visible ci-dessous de la manière suivante :

Choisissez le type REST. Une fois sélectionné, la liste des champs associés s'affichera.
Entrez le nom que vous voulez donner à votre compte REST.
Choisissez la ou les permissions que vous souhaitez attribuer à ce compte.
Chargez le certificat d'authentification qui sera utilisé par votre client REST. Vous devez spécifier un nom pour ce certificat.
Appuyez sur le bouton "Valider" pour confirmer la création du compte REST.

À la fin de cette étape, le Client ID OAuth associé à ce compte sera affiché. Ce Client ID prend la forme "self_service_expeditor_X" (où X est le numéro d'expéditeur qui vous a été attribué).

Veuillez conserver ce Client ID car cette information sera utilisée lors de la demande d'obtention de votre access-token OAuth.

Mettre en place la sécurité OAuth

Le web service REST de la sécurité sociale est sécurisé. Avant de pouvoir l'utiliser, vous devez implémenter le protocole de sécurité OAuth. Référez-vous pour cela à la documentation suivante :

OAuth2 Integration Client Credential .pdf - Nouvelle fenêtre
Code Java pour implémenter OAuth : ClientCredentialTokenGenerator.java Nouvelle fenêtre

Le web service REST pour Dimona

Le web service REST pour Dimona se distingue par le fait que l'ONSS ne peut garantir un traitement synchrone des déclarations. Par conséquent, le web service fonctionne en 2 transactions distinctes :

POST : introduire une déclaration, et
GET : visualiser le résultat du traitement de la déclaration.

Le temps de traitement d'une Dimona varie. Il se peut dès lors que vous deviez effectuer plusieurs appels "GET" pour voir le résultat du traitement de votre déclaration. Vous devrez donc implémenter un mécanisme de "Retry", comme décrit dans notre documentation. Nous vous expliquons également la fréquence que doit avoir votre "Retry" pour ne pas inonder d'appels le système Dimona.
Retrouvez ici la procédure : Documentation fonctionnelle du web service REST pour Dimona .pdf - Nouvelle fenêtre