Aller au contenu principal

Gestion des réponses API asynchrones

Mise à jour

Contrôle par service de match verification et réponses asynchrones

Sis ID utilise les réseaux bancaires pour vérifier les comptes bancaires et leurs titulaires, en s'appuyant sur des bases de données externes. Cette approche implique un réseau complexe d'échanges d'API, pouvant générer des réponses asynchrones pour une part significative des vérifications Sis ID.

Pour gérer ce processus, Sis ID recommande l'implémentation suivante, adaptable aux spécificités du projet.

 

Considérations générales

  • L'API Sis ID renvoie un contrôle qui peut être soit en attente (pending), soit non en attente, selon les réponses des fournisseurs de données et des sous-services obtenues dans le délai de réponse de l'API.

  • SepaMail Diamond, historiquement lié au produit API, possède un ensemble de propriétés dédiées. Les autres bases de données bancaires similaires sont regroupées sous les propriétés MatchVerificationService, associées aux codes de raison MV-X.

  • Pour un contrôle en attente, le consommateur de l'API doit utiliser deux modes :

    • Récupération : Interroger l'API pour vérifier si le contrôle est toujours en attente en utilisant des méthodes de type GET.

    • Relance : Soumettre un nouveau contrôle identique après la période de récupération.

Ces modes s'appliquent aussi bien aux contrôles unitaires (POST/checks) qu'aux contrôles par lot (PUT/audition/import).

Générer un contrôle en PENDING

Les données suivantes peuvent être utilisées pour générer un contrôle PENDING dans l’environnement STAGING.
Veuillez noter que cet environnement est bouchonné et n’utilise qu’un ensemble limité d’IBANs pour déclencher des appels vers un service SepaMail STAGING, permettant ainsi d’observer un cas de contrôle PENDING.

En cas d’échec à générer un contrôle PENDING, veuillez vous référer aux sections ci-dessous pour obtenir un aperçu du corps de réponse attendu dans une telle situation.

 

Personne physique

Utiliser un IBAN valide commençant par FR76300040000
ET
Modifiez une des propriétés suivantes : firstName, lastName ou birthdate pour générer d'autres cas PENDING

Exemple de requête. Les données ne peuvent pas être ré-utilisées.

{
"entity": {
"physicalPersonIdentifier": {
"firstName": "John",
"lastName": "Dodo",
"birthdate": "1839-01-19"
},
"paymentIdentity": {
"iban": "FR7630004000031234567890143"
}
}
}

 

Personne morale

Utiliser un IBAN valide commençant par FR76300040000
ET
Modifiez le registrationId au profit d'un SIREN français valide pour générer d'autres cas PENDING

Exemple de requête. Les données ne peuvent pas être ré-utilisées.

{
"entity": {
"company": {
"countryCode": "FR",
"registrationId": "824 003 958 "
},
"paymentIdentity": {
"iban": "FR7630004003860002004957783"
}
}
}

 

Déterminer l'état PENDING d'un contrôle

La propriété status d'un contrôle n'est pas pertinente pour déterminer si un contrôle est fonctionnellement en attente. Elle indique uniquement si le contrôle a été traité avec succès par Sis ID, indépendamment de son état d'attente ou non.

Indicateurs utiles :

  • Un contrôle en attente a toujours "classification": "MEDIUM"

  • Il n'existe actuellement pas de propriété dédiée pour identifier explicitement l'état PENDING d'un contrôle.

 

État PENDING des contrôles unitaires (POST/checks)

État PENDING pour SepaMail Diamond :
Pour identifier un contrôle en attente pour SepaMail Diamond, utilisez les propriétés suivantes dans la réponse :

  • "sepamailVerificationStatus": "PENDING"

  • "reasons" contient "SD-P"

Exemple de réponse :

{
  "classification": "MEDIUM",
  "status": "SUCCEEDED",
  "withDeferredResult": true,
  "reasons": ["S-NR", "I-NR", "CLH-SINR", "COH-SINR", "SD-P"],
  "sepamailVerificationStatus": "PENDING",
  "reasonLabels": {
    "reason.code.SD-P": "Vérification en cours par le service SEPAmail DIAMOND."
  }
}

 

État PENDING pour d'autres services de vérification :

  • Recherchez "MV-P" dans le tableau "reasons" pour identifier les contrôles en attente autres que SepaMail Diamond.

 

État PENDING dans les contrôles par lot (PUT/audition/import)

Indicateurs au niveau du lot :

  • La propriété nbPendingSepamail indique le nombre de contrôles SepaMail en attente dans le lot.

  • Cette propriété ne concerne que les comptes bancaires français et n'inclut pas les autres services bancaires.

Exemple de réponse pour un lot :

{
  "nbItems": 387,
  "nbPendingSepamail": 15,
  "completed": false
}

Indicateurs au niveau des contrôles :

  • Utilisez l'endpoint GET/audition/import/id/controls pour récupérer chaque contrôle du lot et appliquer les mêmes critères que pour les contrôles unitaires.

 

Stratégie de récupération des contrôles asynchrones

Pour les contrôles identifiés comme en attente (PENDING), le consommateur de l'API doit utiliser les routes unitaires (GET/audition/id) ou par lot (GET/audition/import/id/controls) pour suivre l'évolution des contrôles.

Nous recommandons d'implémenter cette stratégie de polling en suivant une suite de Fibonacci, chaque pull correspondant à un F dans la suite suivante :

  • F0 : 30 secondes après l'envoi du contrôle

  • F1 : 1 minute après F0

  • F2 : 2 minutes après F0

  • F3 : 5 minutes après F0 (en moyenne, 80% des réponses sont disponibles)

  • F4 : 10 minutes après F0

  • F5 : 15 minutes après F0

  • Fn : 20 minutes après F0 (100% des résultats devraient être disponibles)

 

Important : La stratégie de récupération des contrôles doit être arrêtée à ce stade.
Les contrôles SepaMail Diamond dont le résultat n'a pas été retourné après 20 minutes doivent être considérés comme “en erreur” / “timeout”.

 

Relance de contrôle

Si le contrôle reste en attente après l'implémentation de la stratégie de récupération, le consommateur de l'API peut relancer un nouveau contrôle identique en utilisant les routes POST ou PUT.

Associé à

Articles associés