Collecter le consentement utilisateur

Un Ask est le mandat que votre utilisateur signe. Il porte un ou plusieurs points de livraison — électricité, gaz, ou les deux — et c'est lui qui nous autorise à demander leurs données aux gestionnaires de réseau.

Le parcours

Créer un Ask avec POST/ask

Voici un exemple du corps de la requête POST/ask pour un Ask avec un contrat gas et un contrat electricity désigné par le contractId renvoyé par GET/search_contract.

Vous pouvez voir les détails de cet endpoint dans la documentation de l'endpoint POST/ask.

contracts

Vous indiquez ici les contrats pour lesquels vous souhaitez obtenir le consentement de l'utilisateur. Il y a 3 formes possibles

• Recommandé - le contractId (un UUID) d'un résultat de GET/search_contract. Cet endpoint confirme l'existence du point de livraison et, chez Enedis, vérifie le titulaire : le contractId n'est présent que pour un point Enedis dont le titulaire a été confirmé à partir du name envoyé. Vous pouvez directement le réutiliser ici. L'id renvoyé par l'ancienne recherche POST/integration/enedis/search_contract reste accepté.

• une description du contrat d'électricite (_energyType: electricity) avec le numéro de PDL et les informations du titulaire :

  {
    "_energyType": "electricity",
    "deliveryPointId": "00059461297239",
    "holder": {
      "_tag": "NaturalPerson",
      "fullName": "Jean Dupont"
    },
    "address": {
      "rueEtNumero": "17 avenue Charles de Gaulle",
      "codePostal": "75007",
      "commune": "Paris"
    }
  }
  

  Le deliveryPointId est ici le numéro de PDL (PRM), 14 chiffres.

• une description du contrat de gaz (_energyType: gas) avec le numéro de PCE et les informations du titulaire :

  {
    "_energyType": "gas",
    "deliveryPointId": "01059461297239",
    "holder": {
      "_tag": "NaturalPerson",
      "fullName": "Jean Dupont"
    },
    "address": {
      "rueEtNumero": "17 avenue Charles de Gaulle",
      "codePostal": "75007",
      "commune": "Paris"
    }
  }
  

  Le deliveryPointId est ici le numéro de PCE (14 chiffres, ou GI suivi de 6 chiffres).

  Les réseaux de distribution de gaz qui ne sont pas exploités par GRDF — les entreprises locales de distribution (ELD) comme Régaz-Bordeaux ou R-GDS — numérotent leurs points de livraison à leur façon. Lorsque l'adresse indique que le réseau n'est pas celui de GRDF, nous acceptons donc le deliveryPointId tel qu'il figure sur la facture (32 caractères maximum). Nous ne sommes pas intégrés à ces distributeurs : le contrat prend alors le statut NOT_VERIFIABLE (il figure sur le mandat, qui reste signable, mais aucune donnée ne pourra être récupérée pour ce point de livraison). Sur une adresse desservie par GRDF, un deliveryPointId qui n'est pas un PCE valide reste refusé avec une erreur 400.

Une entrée par point de livraison

Chaque élément de contracts décrit un point de livraison, donc une énergie. Un même Ask peut mélanger électricité et gaz : il faut alors deux entrées, une par point, et une seule signature couvre les deux. Il n'existe pas de forme qui demanderait « l'électricité et le gaz » en un seul élément, et un UUID de recherche Enedis désigne lui aussi un seul point.

Limite en nombre de contrats dans un Ask

Un Ask contient au plus 2000 contrats, quel que soit leur type (contractId de search_contract, _energyType: electricity ou _energyType: gas). Au-delà, POST/ask répond par une erreur 400.

thirdPartyRecipients : partager les données avec un tiers

Si vous collectez les données pour le compte d'une autre entreprise — un client à qui vous revendez une étude, un partenaire qui porte l'offre auprès de l'utilisateur —, déclarez-la comme DataThirdParty avec POST/data-third-party (nom, SIRET, site web, logo), puis citez son slug dans thirdPartyRecipients à la création de l'Ask :

{
  "contracts": ["…"],
  "thirdPartyRecipients": ["mon-client-installateur"]
}

Le formulaire de consentement nomme alors ce tiers et affiche son logo, pour que l'utilisateur sache à qui ses données profitent. Par défaut, le formulaire indique que les données sont récoltées par votre entreprise ou par Switchgrid, et exploitées par votre entreprise pour le compte du tiers.

Si le tiers est lui-même déclaré comme tiers auprès d'Enedis (SGE) et récolte les données de son côté, créez-le avec collectsEnedisDataDirectly: true : le formulaire le cite alors parmi les entreprises qui récoltent les données auprès d'Enedis, aux côtés de votre entreprise et de Switchgrid, et précise qu'il les exploite pour son propre compte.

Délai de signature

Un Ask doit être signé dans les 2 mois qui suivent sa création. Passé ce délai, consentCollectionDetails.userUrl n'accepte plus de signature : la page affiche à l'utilisateur un message l'invitant à se rapprocher de vous pour obtenir un nouveau mandat. Il vous faut alors créer un nouvel Ask.

Suivre l'état des contrats

GET/ask/{askId} renvoie un statut par contrat, en plus du statut de l'Ask lui-même. C'est là que se lit ce qui bloque, point de livraison par point de livraison.

GRDF : la confirmation du signataire

Chez GRDF, la signature du mandat ne suffit pas : le signataire doit encore confirmer la demande par e-mail ou SMS avant que le contrat gaz ne s'ouvre. C'est le seul gestionnaire de réseau que nous intégrons dans ce cas — le détail est sur sa propre page, GRDF : la confirmation du signataire par e-mail ou SMS.

Dépôt de justificatif de contrat

Lorsque GET/search_contract ne trouve pas de contrat (aucun contractId dans la réponse, par ex. en raison d'une différence de nom dans la base du fournisseur, noms en 2 lettres, etc.), vous pouvez toujours créer un Ask avec une ou plusieurs entrées dans contracts de type electricity ou gas (le statut de l'Ask sera NOT_VALID) puis téléverser un justificatif — typiquement une facture d'électricité - pour prouver le lien entre la personne titulaire et le point de livraison concerné. Lorsque le justificatif est validé, le contrat est validé et l'Ask passe en statut PENDING_USER_ACTION, prêt à être signé par l'utilisateur.

Processus

{
  "contracts": [
    {
      "_energyType": "electricity",
      "deliveryPointId": "09284757283947",
      "holder": {
        "_tag": "NaturalPerson",
        "fullName": "Jean Dupont"
      },
      "address": {
        "rueEtNumero": "17 avenue Charles de Gaulle",
        "codePostal": "75007",
        "commune": "Paris"
      }
    }
  ],
  "consentDuration": "1 year"
}

Retirer des contrats avant la signature

Un Ask de nombreux contrats est NOT_VALID dès que l'un d'eux est NOT_VALID. Plutôt que de le recréer sans ces contrats, retirez-les avec POST/ask/{askId}/contracts/remove, en indiquant le seq de chacun — son index dans le tableau contracts envoyé à la création, à partir de 0 :

{ "contractSeqs": [12, 431, 977] }

• C'est possible tant que l'Ask n'est pas signé : CREATED, NOT_VALID ou PENDING_USER_ACTION. Vous pouvez retirer n'importe quel contrat, quel que soit son statut.
• Un contrat retiré prend le statut REMOVED. Il n'apparaît plus sur le mandat ni dans la preuve de signature, et ne compte plus dans le statut de l'Ask. Il est toujours renvoyé par GET/ask/{askId}, avec le même seq.
• Le statut de l'Ask est recalculé sur les contrats restants : une fois les derniers contrats NOT_VALID retirés, il passe à PENDING_USER_ACTION et vous recevez ask.verified. La réponse est l'Ask, tel que le renvoie GET/ask/{askId}.
• Retirer un contrat déjà retiré ne change rien. Retirer tous les contrats d'un Ask est refusé : révoquez l'Ask à la place.
• Si le signataire a ouvert le mandat avant un retrait, sa signature est refusée avec un message l'invitant à vérifier la nouvelle liste des compteurs ; la page affiche alors le mandat à jour.

Tester la création d'un Ask

Avec le header HTTP switchgrid-test-env: true sur POST/ask, l'Ask est créé en environnement de test : nous n'appelons aucun gestionnaire de réseau, et le résultat de la vérification ne dépend que du numéro de point de livraison et du code postal que vous envoyez. C'est le moyen de rejouer chaque statut de contrat — VALID, NOT_VALID, puis la signature — sans PRM, PCE ni RTPL réel.

En test, tout identifiant bien formé est accepté : le contrat passe en VALID et l'Ask en PENDING_USER_ACTION, même si le point n'existe chez aucun gestionnaire de réseau. Seuls les identifiants ci-dessous ont un comportement particulier, et ce sont eux qui permettent de provoquer un NOT_VALID.

Enedis : PRM de test

Le statusText du contrat NOT_VALID indique que le code postal ne correspond pas à celui du contrat. Tout autre PRM à 14 chiffres est VALID, y compris s'il n'existe pas chez Enedis : le cas « PRM introuvable » ne se rejoue pas en test, mais le cas « code postal différent » suffit à parcourir tout le circuit NOT_VALID, jusqu'au dépôt de justificatif.

GRDF : PCE de test

Le statusText du contrat NOT_VALID indique que le point de livraison n'est pas valide selon le gestionnaire de réseau. Pour le PCE 00000000000001, nous envoyons au signataire un e-mail qui joue le rôle de celui de GRDF : le détail est sur la page GRDF.

ESR : RTPL de test

Un contrat électricité est rattaché à Strasbourg Électricité Réseaux (ESR) d'après son adresse : utilisez une adresse à Strasbourg. Les trois RTPL de test sont domiciliés au code postal 67000.

Par exemple, ESR00000C50001 avec le code postal 67200 donne un contrat NOT_VALID, avec le même statusText que le cas Enedis. Ce que chaque RTPL renvoie ensuite, endpoint par endpoint, est décrit sur la page ESR.

Rejouer le dépôt de justificatif

Le dépôt de justificatif se teste de bout en bout à partir d'un contrat NOT_VALID :

Révoquer un Ask

Si vous souhaitez révoquer un Ask, signé ou non, vous pouvez utiliser l'endpoint POST/ask/{askId}/revoke. C'est aussi ainsi qu'on annule un lien de consentement jamais envoyé : l'Ask passe en REVOKED, et status=!REVOKED l'écarte de GET/ask. Pour l'instant, il n'est pas possible de révoquer partiellement un Ask (seulement certains contrats). La révocation ne touche que cet Ask : les autres Asks qui portent sur les mêmes points de livraison gardent leur consentement et leurs accès.

Effacement des données (RGPD)

Le titulaire d'un point peut demander l'effacement de ses données (RGPD, article 17). Vous êtes le responsable de traitement : transmettez-nous sa demande à contact@switchgrid.tech, avec l'Ask concerné. Si la demande nous parvient directement, nous vous la transmettons.

Nous effaçons alors, pour ce point de livraison et les consentements visés :

• le consentement, révoqué : le contrat passe en REVOKED, avec un statusText qui mentionne l'effacement RGPD, et l'abonnement aux données chez le gestionnaire de réseau prend fin ;
• les données collectées, partout où nous les conservons : courbes de charge, index, et fichiers bruts du gestionnaire de réseau. Un fichier partagé avec d'autres points (requête groupée) est réécrit sans ce point.

Seules la preuve du consentement et de sa révocation, et la trace de la demande d'effacement (le nom du titulaire qui l'a faite, sa date et la manière dont elle nous est parvenue) sont conservées, pendant 5 ans : le délai de prescription de droit commun (article 2224 du Code civil), pendant lequel ces preuves peuvent être demandées.

Côté API, les données effacées sont signalées comme telles : _status: "erased" dans les commandes, erreur 410 DataErased pour une requête qui ne porte plus rien. Voir Données effacées (RGPD).