guide editeur hubee

Récupérer les données de quotient familial dans HubEE

Ce guide de démarrage rapide est à destination des éditeurs qui débutent l'intégration de leur service informatique avec HubEE dans le cadre du cas d'usage “formulaire de collecte du quotient familial” proposé par API Particulier. Les données de l’usager collectées avec le formulaire sont stockées par HubEE sous la forme de fichiers contenus dans un télédossier pour chaque formulaire rempli.

Ce guide présente les étapes à suivre pour récupérer les nouveaux télédossiers et gérer les notifications associées.

Important

Si vous intégrez déjà HubEE pour d'autres abonnements vous devriez pouvoir utiliser votre intégration actuelle pour le cas d’usage FormulaireQF et ne devriez pas avoir besoin de ce guide.

Note

Pour aller plus loin

Ce guide est une version simplifiée d’intégration à Hubee vous permettant de mettre en place les fonctionnalités minimales pour faire tourner le service “formulaire de collecte du quotient familial”C’est pourquoi, des notes, sous la même forme que celle-ci, ponctuent cette documentation, afin de vous inviter à aller plus loin dans l’intégration Hubee afin notamment de la rendre compatible avec d’autres cas d’usages.

Nous vous conseillons de consulter la documentation officielle d'HubEE

Prérequis

Avant de poursuivre la lecture de ce guide, assurez-vous de :

Avoir déjà un compte sur Hubee en tant qu’éditeur. [En savoir plus](Todo vers prez)
Vos identifiants API HubEE à récupérer via le portail

Il est conseillé d'avoir le swagger à portée de main pour mieux comprendre les étapes de ce guide.

export HUBEE_CLIENT_ID=votre_token_à_récupérer_via_le_portail
export HUBEE_CLIENT_SECRET=votre_token_à_récupérer_via_le_portail

Cinématique

Présentation générale

Le processus de récupération des télédossiers (où se trouvent les données quotient familial et composition familiale de l’usager) se déroule en plusieurs étapes basées sur la récupération de notifications. Celles-ci sont des évènements qui signalent un changement de statut d'un télédossier.

Vous devrez traiter l'ensemble des notifications envoyées à votre SI.

La cinématique est la suivante :

A. Récupération d'un token d'authentification
B. Récupération des notifications (à répéter jusqu'à ce que le tableau soit vide). Pour chaque notification :
- Cas n°1 : L'événement est un nouveau télédossier :
  1. Récupération du case
  2. Téléchargement des pièces jointes
  3. Mise à jour intermédiaire
  4. Mise à jour finale
  5. Suppression de la notification
- Cas n°2 : L'événement est un télédossier existant (cinématique simplifiée):
  1. Suppression de la notification

Les exemples sont fournis en bash et nécessitent l'installation de jq pour le traitement des réponses JSON.

graph LR
A[Récupération d'un token] --> B{Récupération des notifications}
B -- nouveau télédossier --> C[ Récupération du case ] --> D[ Téléchargement des pièces jointes ]
D --> E[Mise à jour intermédiaire ]
E --> F[Mise à jour finale ]
F --> I[Suppression de la notification]
B -- télédossier existant --> I

A. Récupération d'un jeton d'authentification

En premier il faut récupérer un jeton d'authentification.

export HUBEE_RESPONSE=$(curl -X POST https://auth.bas.hubee.numerique.gouv.fr/oauth2/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--user $HUBEE_CLIENT_ID:$HUBEE_CLIENT_SECRET \
-d 'scope=SI' \
-d 'grant_type=client_credentials')

echo $HUBEE_RESPONSE

Cette réponse JSON contient le jeton d'authentification à utiliser pour les requêtes suivantes.

export HUBEE_ACCESS_TOKEN=$(echo $HUBEE_RESPONSE | jq -r '.access_token')

B. Récupérer les notifications des nouveaux télédossiers

export HUBEE_RESPONSE=$(curl -X GET https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/notifications \
-d 'maxResults=1000' \
-d 'processCode=FormulaireQF' \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN")

echo $HUBEE_RESPONSE

Vous devrez récupérer plusieurs fois par jour les notifications pour traiter les nouveaux télédossiers.

Vous devez récupérer les notifications et les traiter jusqu'à ce que le tableau récupéré soit vide, il s'agit d'une "pile" à "dépiler".

Tip

Par exemple, si vous avez 2500 notifications non traitées, vous devrez faire 4 appels avec maxResults valant 1000.

Le premier appel renverra les 1000 premières notifications que vous traiterez et supprimerez.

Vous ferez un second appel qui renverra 1000 notifications que vous traiterez et supprimerez.

Vous ferez un troisième appel qui renverra 500 notifications que vous traiterez et supprimerez.

Un quatrième appel renverra un tableau vide.

Cette requête renvoie un tableau de notification qui pointent vers des case.

Cas n°1 : L'événement est un nouveau télédossier

Traitons d'abord celles qui représentent des nouveaux télédossiers : leur eventId est null.

Pour chacune de ces notification vous devrez :

récupérer le case
télécharger les pièces jointes (attachments)
mettre à jour le case pour indiquer qu'il est en cours de traitement
créer un évènement sur le case pour notifier que le télédossier est en cours de traitement
mettre à jour le case pour indiquer qu'il est traité
créer un événement sur le case pour notifier que le télédossier est traité
supprimer la notification.

Ici nous allons nous concentrer sur le traitement du premier case du tableau dont eventId est null.

export HUBEE_CASE_ID=$(echo $HUBEE_RESPONSE | jq -r '[.[] | select(.eventId == null) | .caseId][0]')
export HUBEE_NOTIFICATION_ID=$(echo $HUBEE_RESPONSE | jq -r '[.[] | select(.eventId == null) | .id][0]')

Cas n°1 - étape 1. Récupérer le `case`

export HUBEE_RESPONSE=$(curl -X GET https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN")

echo $HUBEE_RESPONSE

Le case contient un tableau d'attachments qui pointent vers les pièces jointes du télédossier.

Cas n°1 - étape 2. Télécharger les pièces jointes

export HUBEE_ATTACHMENTS=$(echo $HUBEE_RESPONSE | jq -r '[.attachments[] | {id: .id, file_name: .fileName}]')

jq -c '.[]' <<< $HUBEE_ATTACHMENTS | while read HUBEE_ATTACHMENT; do
    export HUBEE_ATTACHMENT_ID=$(echo $HUBEE_ATTACHMENT | jq -r '.id')
    export HUBEE_ATTACHMENT_FILE_NAME=$(echo $HUBEE_ATTACHMENT | jq -r '.file_name')

    curl -o $HUBEE_ATTACHMENT_FILE_NAME -X GET https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID/attachments/$HUBEE_ATTACHMENT_ID \
    -H "Authorization: Bearer $HUBEE_ACCESS_TOKEN"
done

Cas n°1 - étape 3. Mettre à jour le `case` au statut intermédiaire

export HUBEE_BODY='{
 "status": "IN_PROGRESS"
}'

export HUBEE_RESPONSE=$(curl -X PATCH https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d "$HUBEE_BODY")

echo $HUBEE_RESPONSE

Cas n°1 - étape 4. Créer un événement intermédiaire sur le `case`

export HUBEE_BODY='{
 "actionType": "STATUS_UPDATE",
  "notification": true,
  "caseNewStatus": "IN_PROGRESS"
}'

Note

Pour aller plus loin

Il est conseillé de passer le paramètre "message" avec un message explicite, par exemple ici "Nous avons bien reçu votre demande, elle est en cours de traitement par nos services. Cordialement, la commune de NOM_DE_LA_COMMUNE".

Cela permettra la mise en place futures de fonctionalités avancées (comme la notification aux usagers).

export HUBEE_RESPONSE=$(curl -X POST https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID/events \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d "$HUBEE_BODY")

echo $HUBEE_RESPONSE

Note

Pour aller plus loin

Les étapes 5 et 6 sont ici exécutées à la suite des étapes 3 et 4 mais une cinématique plus robuste devrait finaliser le traitement du case et sa notification après instruction du cas d'usage par votre SI.

Cette cinématique plus réaliste permet en outre de gérer les erreurs de traitement via le statut "REFUSED".

Cas n°1 - étape 5. Mettre à jour le `case` au statut final

export HUBEE_BODY='{
 "status": "DONE"
}'

export HUBEE_RESPONSE=$(curl -X PATCH https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d "$HUBEE_BODY")

echo $HUBEE_RESPONSE

Cas n°1 - étape 6. Créer un évènement final sur le `case`

export HUBEE_BODY='{
 "actionType": "STATUS_UPDATE",
  "notification": true,
  "caseNewStatus": "DONE"
}'

Note

Pour aller plus loin

Il est conseillé de passer le paramètre "message" avec un message explicite, par exemple "La prise en charge de votre demande de mise à jour du Quotient Familial est terminée. Cordialement, la commune de NOM_DE_LA_COMMUNE".

Cela permettra la mise en place futures de fonctionalités avancées (comme la notification aux usagers).

export HUBEE_RESPONSE=$(curl -X POST https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID/events \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d "$HUBEE_BODY")

echo $HUBEE_RESPONSE

Cas n°1 - étape 7. Supprimer la `notification`

export HUBEE_RESPONSE=$(curl -X DELETE https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/notifications/$HUBEE_NOTIFICATION_ID \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN")

echo $HUBEE_RESPONSE

Cas n°2 : L’événement est un télédossier existant

Récupérons une notification pour un télédossier existant.

export HUBEE_CASE_ID=$(echo $HUBEE_RESPONSE | jq -r '[.[] | select(.eventId != null) | .caseId][0]')
export HUBEE_NOTIFICATION_ID=$(echo $HUBEE_RESPONSE | jq -r '[.[] | select(.eventId != null) | .id][0]')

Étape unique dans le cadre d’une intégration simplifiée : Pour les notifications des télédossiers existants, vous devrez simplement les supprimer.

export HUBEE_RESPONSE=$(curl -X DELETE https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/notifications/$HUBEE_NOTIFICATION_ID \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN")

echo $HUBEE_RESPONSE

Note

Pour aller plus loin

Cette cinématique est simplifiée et nous vous conseillons de mettre en place la cinématique complète suivante:

graph LR
D{Récupération de l'évènement} -- status == RECEIVED --> E((Suppression des notifications))
D -- status:SENT --> F{Paramètre actionType} -- actionType == ATTACH_DEPOSIT --> H[Téléchargement des PJs] --> G[Patch de l'event] --> E
F -- actionType != ATTACH_DEPOSIT --> G

Dans les cas ou il faut mettre à jour l'évènement, il faudra le passer au statut "RECEIVED":

export HUBEE_BODY='{
 "status": "RECEIVED"
}'

export HUBEE_RESPONSE=$(curl -X PATCH https://api.bas.hubee.numerique.gouv.fr/teledossiers/v1/cases/$HUBEE_CASE_ID/events/$HUBEE_EVENT_ID \
-H "Authorization: Bearer $HUBEE_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d "$HUBEE_BODY")

echo $HUBEE_RESPONSE

Contenu d'un JSON envoyé sur HubEE

Le fichier ressemble à ceci :

{
  "external_id": "external_id",
  "pivot_identity": {
    "codePaysLieuDeNaissance": "99135",
    "anneeDateDeNaissance": 1979,
    "moisDateDeNaissance": 10,
    "jourDateDeNaissance": 15,
    "codeInseeLieuDeNaissance": null,
    "prenoms": ["David"],
    "sexe": "M",
    "nomUsuel": "Heinemeier Hansson",
    "family_name": "Heinemeier Hansson",
    "given_name": "David",
    "gender": "male",
    "birthdate": "1979-10-15",
    "birthplace": null,
    "birthcountry": "99135"
  },
  "quotient_familial": {
    "version": "v2",
    "regime": "CNAF",
    "quotientFamilial": 2550,
    "annee": 2024,
    "mois": 2,
    "allocataires": [
      {
        "nomNaissance": "Heinemeier Hansson",
        "nomUsuel": "Heinemeier Hansson",
        "prenoms": "David",
        "anneeDateDeNaissance": "1979",
        "moisDateDeNaissance": "10",
        "jourDateDeNaissance": "15",
        "sexe": "M"
      }
    ],
    "enfants": [
      {
        "nomNaissance": "Heinemeier Hansson",
        "nomUsuel": "Heinemeier Hansson",
        "prenoms": "Jean",
        "sexe": "M",
        "anneeDateDeNaissance": "2016",
        "moisDateDeNaissance": "12",
        "jourDateDeNaissance": "13"
      }
    ]
  }
}

Les données d'identité pivot

Les données d'identité pivot correspondent aux champs originaux envoyés par FranceConnect, documentés ici : https://partenaires.franceconnect.gouv.fr/fcp/fournisseur-service (dans la section Données Usager).

Les données de quotient famililal

Les données de quotient familial proviennent de l'API quotient familial V2, documentée ici : https://particulier.api.gouv.fr/developpeurs/openapi#tag/Quotient-familial/paths/~1api~1v2~1composition-familiale-v2/get

Si votre usager a eu une erreur Le dossier allocataire n'a pas été trouvé auprès de la CNAF en essayant de récupérer son quotient familial via FranceConnect, il lui sera proposé d'entrer son numéro d'allocataire pour récupérer ses données sur l'API quotient familial V1, documentée ici : https://particulier.api.gouv.fr/developpeurs/openapi#tag/Quotient-familial/paths/~1api~1v2~1composition-familiale/get

Le champ "version" renseigne de quelle API proviennent les données. Dans le cas de la V1, les champs sont légèrement différents.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guide editeur hubee

Récupérer les données de quotient familial dans HubEE

Prérequis

Cinématique

Présentation générale

A. Récupération d'un jeton d'authentification

B. Récupérer les notifications des nouveaux télédossiers

Cas n°1 : L'événement est un nouveau télédossier

Cas n°1 - étape 1. Récupérer le `case`

Cas n°1 - étape 2. Télécharger les pièces jointes

Cas n°1 - étape 3. Mettre à jour le `case` au statut intermédiaire

Cas n°1 - étape 4. Créer un événement intermédiaire sur le `case`

Cas n°1 - étape 5. Mettre à jour le `case` au statut final

Cas n°1 - étape 6. Créer un évènement final sur le `case`

Cas n°1 - étape 7. Supprimer la `notification`

Cas n°2 : L’événement est un télédossier existant

Contenu d'un JSON envoyé sur HubEE

Les données d'identité pivot

Les données de quotient famililal

Clone this wiki locally

guide editeur hubee

Récupérer les données de quotient familial dans HubEE

Prérequis

Cinématique

Présentation générale

A. Récupération d'un jeton d'authentification

B. Récupérer les notifications des nouveaux télédossiers

Cas n°1 : L'événement est un nouveau télédossier

Cas n°1 - étape 1. Récupérer le case

Cas n°1 - étape 2. Télécharger les pièces jointes

Cas n°1 - étape 3. Mettre à jour le case au statut intermédiaire

Cas n°1 - étape 4. Créer un événement intermédiaire sur le case

Cas n°1 - étape 5. Mettre à jour le case au statut final

Cas n°1 - étape 6. Créer un évènement final sur le case

Cas n°1 - étape 7. Supprimer la notification

Cas n°2 : L’événement est un télédossier existant

Contenu d'un JSON envoyé sur HubEE

Les données d'identité pivot

Les données de quotient famililal

Clone this wiki locally

Cas n°1 - étape 1. Récupérer le `case`

Cas n°1 - étape 3. Mettre à jour le `case` au statut intermédiaire

Cas n°1 - étape 4. Créer un événement intermédiaire sur le `case`

Cas n°1 - étape 5. Mettre à jour le `case` au statut final

Cas n°1 - étape 6. Créer un évènement final sur le `case`

Cas n°1 - étape 7. Supprimer la `notification`