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, de bout en bout#

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 provenant de GET/integration/enedis/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

• un UUID obtenu via POST/integration/enedis/search_contract. Cet endpoint permet de confirmer l'existence d'un contrat dans la base Enedis. Vous obtenez alors un UUID, que vous pouvez directement réutiliser ici

• 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.

Limites en nombre de contrats dans un Ask

Aujourd'hui, on limite selon le type de contrat :

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 POST/integration/enedis/search_contract ne trouve pas de contrat (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"
}

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, vous pouvez utiliser l'endpoint POST/ask/{askId}/revoke. Pour l'instant, il n'est pas possible de révoquer partiellement un Ask (seulement certains contrats).