guide editeur hubee

Récupérer les nouveaux télédossiers sur HubEE

Ce guide de démarrage rapide est à destination des éditeurs qui débutent l'intégration de leur SI avec HubEE dans le cas d'usage du formulaire de collecte du quotient familial. Il 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 cas d'usages vous devriez pouvoir utiliser votre intégration actuelle pour les démarches FormulaireQF.

Note

Ce guide présente des étapes simplifiées pour faciliter votre démarrage mais vous retrouverez des informations plus complètes dans ces notes. Nous vous conseillons d'en prendre connaissance et de consulter la documentation officielle d'HubEE. Vous pourrez ainsi réaliser une intégration compatible avec les autres cas d'usages supportés par HubEE.

Prérequis

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 se déroule en plusieurs étapes basées sur la récupération des 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 :

Récupération d'un token d'authentification
Récupération des notifications (à répéter jusqu'à ce que le tableau soit vide). Pour chaque notification :
- Dans le cas où 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
- Dans le cas où 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

1. 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')

2. 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 jusqu'à ce que le tableau récupéré soit vide.

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

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]')

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.

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

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

4. Créer un évènement intermédiaire sur le `case`

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

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

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 traitement réel du télédossier par votre SI. Cette cinématique plus réaliste permet en outre de gérer les erreurs de traitement via le statut "REFUSED".

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

6. Créer un évènement final sur le `case`

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

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

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

Traiter les notifications des télédossiers existants

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]')

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

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 != STATUS_UPDATE --> 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guide editeur hubee

Récupérer les nouveaux télédossiers sur HubEE

Prérequis

Cinématique

Présentation générale

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

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

1. Récupérer le `case`

2. Télécharger les pièces jointes

3. Mettre à jour le `case` au statut intermédiaire

4. Créer un évènement intermédiaire sur le `case`

5. Mettre à jour le `case` au statut final

6. Créer un évènement final sur le `case`

7. Supprimer la `notification`

Traiter les notifications des télédossiers existants

Clone this wiki locally

guide editeur hubee

Récupérer les nouveaux télédossiers sur HubEE

Prérequis

Cinématique

Présentation générale

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

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

1. Récupérer le case

2. Télécharger les pièces jointes

3. Mettre à jour le case au statut intermédiaire

4. Créer un évènement intermédiaire sur le case

5. Mettre à jour le case au statut final

6. Créer un évènement final sur le case

7. Supprimer la notification

Traiter les notifications des télédossiers existants

Clone this wiki locally

1. Récupérer le `case`

3. Mettre à jour le `case` au statut intermédiaire

4. Créer un évènement intermédiaire sur le `case`

5. Mettre à jour le `case` au statut final

6. Créer un évènement final sur le `case`

7. Supprimer la `notification`