[[:guide_callbacks|Français]] | [[:en:guide_callbacks|English]]
----

====== INTRODUCTION AUX CALLBACKS ======

==== 🔁 Callbacks – À quoi servent-ils ? ====

Lors de la création d’un dossier, il est indispensable de renseigner un ou plusieurs **callback_endpoints**, c’est-à-dire des URL(s) sur lesquelles ID360 enverra automatiquement des notifications (en HTTP POST) tout au long du processus d’identification.

Chaque callback_endpoint recevra un **payload** contenant des informations liées au dossier, notamment son statut et les étapes franchies par l’utilisateur.

=== 📌 Que peut-on configurer ? ===

Vous avez la possibilité de renseigner **une ou plusieurs URLs de callback**. Pour chaque callback, vous pouvez définir le niveau de notification souhaité :

  * **Callback finale uniquement** : vous recevez une seule notification à la fin du processus, indiquant que l’identification est terminée, avec les informations associées.
  * **Callbacks intermédiaires + finale** : vous êtes notifiés à chaque étape clé du parcours utilisateur (début, upload, validation des documents, etc.), en plus de la notification finale.

=== ⚠️ Attention à l’ordre d’arrivée des callbacks ===

Il est important de noter que dans certains cas, **des callbacks intermédiaires peuvent arriver après la callback finale**.  
Cela peut se produire si l’envoi initial d’une callback a échoué (par exemple si votre serveur était temporairement indisponible) : ID360 effectuera alors des **re-tentatives automatiques (retries)** pour garantir la bonne réception.

Ces retries peuvent provoquer un **désalignement temporel dans l’ordre des messages reçus**.

  * → Il est donc fortement recommandé de **vous baser sur le contenu du payload** plutôt que sur l’ordre d’arrivée des notifications.


==== LA CONSTRUCTION DU PAYLOAD ====

Ci-dessous un exemple de payload (format JSON) envoyé par ID360 à votre URL de callback : 

{{payload.png ? 289 × 286}}

==== PREREQUIS ====

En tant que service de confiance, nous avons la responsabilité de nous conformer aux normes en vigueur, notamment l'ETSI EN 319 401, qui exige l’utilisation des versions les plus récentes de TLS pour garantir la sécurité et la fiabilité de nos échanges.

Nous vous recommandons de vérifier que votre connexion est correctement configurée en **TLSv2 ou TLSv3**.

Si vous souhaitez autoriser nos adresses IP, nous vous invitons à contacter votre Customer Success Manager, qui se chargera de vous les communiquer.

====== CALLBACKS INTERMEDIAIRES ======

À chaque étape franchie par l'utilisateur, vous recevrez des notifications intermédiaires sous forme de callback, qui vous informeront de la nature et du statut de l'étape en question.
==== CONSTRUCTION ET CARACTERISTIQUES ====

{{callbackintermediaire.png?   251 × 255}}

Le **statut** d'une callback intermédiaire sera systématiquement défini sur « STARTED ».

Le bloc **steps_status** indique qu’un total de 7 étapes de contrôle a été identifié pour le parcours associé à ce payload.

La valeur **done = 1** signifie que seule l’étape ProfileDataStep (qui était de pousser le nom de famille par API) a été finalisée.

Le champ **enrollment_step** fournit des informations détaillées sur l’étape, notamment le résultat du contrôle, le type de vérification effectuée, ainsi que la liste des documents concernés. Le statut présent dans enrollment_step peut être OK, KO, FAILED, USER_PROCESSING, SYS_PROCESSING.

**Le type présent dans la variable enrollment_step est une information interne, à ce titre, il ne doit pas être utilisé ou exploité.**
==== LES ETAPES D’ENROLEMENT PAR NOM ====

=== Pièces d'identité ===

^ ‘enrollment_step’ > ‘name’ ^ Document(s) ^ Contrôle / Remarque ^  
| id_document | Pièce d’identité | La pièce d’identité a bien été reçue et lue par ID360 |  
| id_document_mandate | Pièce d’identité | La pièce d’identité de la personne présente dans le KBIS a bien été reçue et lue par ID360 |  
| fake_photo_id| Pièce d’identité | La photo présente sur la pièce d’identité est conforme |  
| phone_detection | Pièce d’identité | La détection d’attaque par présentation s’est bien déroulée | 
| image_forensics | Pièce d’identité | La détection de la monochromie s’est bien déroulée |

=== Moyens d’identification électronique ===

^ ‘enrollment_step’ > ‘name’ ^ Document(s) ^ Contrôle / Remarque ^  
| ar24| PVID | AR24 a communiqué les résultats de l’enrôlement à ID360 |  
| france_connect| France Connect | France Connect a communiqué les résultats de l’enrôlement à ID360 |  
| france_connect_plus| France Connect+ | France Connect+ a communiqué les résultats de l’enrôlement à ID360 |  
| id_num| Identité Numérique La Poste | L’identité Numérique La Poste a communiqué les résultats de l’enrôlement à ID360 |  

=== Selfie ===

^ ‘enrollment_step’ > ‘name’ ^ Document(s) ^ Contrôle / Remarque ^  
| facecomparison | Selfie + pièce d’identité | ID360 a bien reçu l’image du selfie extraite de la vidéo |  
| liveness | Selfie | La vidéo correspondant au challenge effectué par l’utilisateur a bien été reçue côté ID360 (deux fois pour deux challenges) |  

=== Documents complémentaires ===

^ ‘enrollment_step’ > ‘name’ ^ Document(s) ^ Contrôle / Remarque ^  
| property_tax_notice | Avis de taxes foncières de l’état français| Le document a bien été reçu et lu par ID360 |  
| proof_of_address | Justificatif de domicile | Le document a bien été reçu et lu par ID360 |  
| pay_slip | Bulletin de salaire d’un salarié français | Le document a bien été reçu et lu par ID360 |  
| kbis| Extrait de Kbis | Le document a bien été reçu et lu par ID360 |  
| income_tax_notice| Avis d’imposition de l’état français | Le document a bien été reçu et lu par ID360 |  
| bank_details | RIB de banques françaises | Le document a bien été reçu et lu par ID360 |  
| free_document | Document libre | Le document a bien été reçu et lu par ID360 |  
| mandate | Mandat en lien avec le KBIS | Le document a bien été reçu et lu par ID360 |  

=== Autres contrôles ===

^ ‘enrollment_step’ > ‘name’ ^ Document(s) ^ Contrôle / Remarque ^  
| phone| Numéro de téléphone | L’utilisateur a renseigné son numéro de téléphone |  
| otp| Code OTP | Le code OTP a bien été saisi par l’utilisateur |  
| email | Adresse email | L’utilisateur a renseigné son adresse email |    
====== CALLBACK FINALE ======

La callback finale vous signalera la fin du processus d’identification et vous donnera des informations sur cette dernière. 
{{callbackfinale.png?386 × 137 }}


Le statut d’une callback finale sera : 
**OK, KO, FAILED ou CANCELED.** 

Dans le cas d’un KO, comme dans l’exemple ci-contre, la raison vous informera de la cause de ce KO.

Dans le steps_status la valeur « done » sera égale à la valeur « total ».
\\
\\
\\
Dans le cadre de cette callback, vous devez renvoyer un code 2XX (par exemple 204) dans un délai inférieur à 10 secondes.

Si cette réponse n’est pas reçue, jusqu’à 6 nouvelles tentatives (retries) seront effectuées selon le planning suivant :

^ Tentative ^ Secondes ^ Minutes ^ Minutes cumulées ^
| 1         | 10       | 0,17     | 0,17     |
| 2         | 80       | 1,33     | 1,50     |
| 3         | 270      | 4,50     | 6,00     |
| 4         | 640      | 10,67    | 16,67    |
| 5         | 1250     | 20,83    | 37,50    |
| 6         | 2160     | 36,00    | 73,50    |
| 7         | 3430     | 57,17    | 130,67   |

Ces intervalles sont calculés selon la formule : //
10 x (n+1)^3// (n correspondant au numéro de la tentative) — le résultat étant exprimé en secondes.

====== LES CALLBACKS ENDPOINTS ======

Dans le body de l'étape de la création d'un dossier utilisateur : 


<code json>
"callback_endpoints": [
  {
    "url": "https://votre-serveur.com/callback",
    "on": [
      "F"
    ],
    "headers": [
      {
         "name": "Authorization", value: "Bearer abc123"
      }
    ]
  }
]
</code>
  
=== 📝 Détails des champs ===

  * **`url`** : l’adresse du endpoint à appeler (POST) lorsqu’un événement est déclenché.
  * **`on`** : liste des événements pour lesquels ce callback sera exécuté.
  * **`headers`** : liste de headers personnalisés à inclure dans la requête (ex : authentification, trace, etc.).

----

=== 🎯 Liste des statuts possibles dans `on` ===

  * **`F`** – Failed
  * **`C`** – Canceled
  * **`E`** – End (OK ou KO)
  * **`I`** – Intermediate 
  * **`UP`** – Mie User Processing
  * **`SP`** – Mie Sys Processing

----

=== 💬 Commentaire ===

  * Vous pouvez définir plusieurs endpoints en les ajoutant à la liste `"callback_endpoints"`.
  * Chaque callback sera déclenché uniquement pour les statuts spécifiés dans `"on"`.