Agreely Docs
FR EN

Émettre une demande de consentement

Une vérification ne renvoie jamais allow tant qu'une personne n'a pas réellement accordé la cellule. Ce guide obtient cet octroi. Vous émettez une demande de consentement signée, Agreely envoie au destinataire par courriel un lien profond sécurisé, et son approbation produit un reçu et active la cellule.

Il vous faut une clé à portée issue, un domaine d'entreprise vérifié (la demande est signée par le DID de votre entreprise, qui ne se résout qu'une fois votre domaine vérifié) et un formulaire publié dans l'application entreprise, sous Information et consentement > Formulaires.

Émettre la demande

Une demande est toujours émise sous un formulaire publié (un document de consentement) : elle demande exactement les éléments que ce formulaire divulgue, de sorte que l'offre signée ne peut jamais s'écarter du texte que la personne lit. Passez soit documentCode, le code du formulaire (le serveur prend sa version publiée en vigueur), soit consentDocumentId, l'identifiant d'une version précise; agreely documents list ou GET /v1/consent-documents les donne. Un champ items est refusé (422). L'offre est signée sur le serveur, avec la clé de signature de votre entreprise hébergée par Agreely, et le courriel est envoyé après la validation.

const r = await agreely.consentRequests.create({
  customerId: "cust_8812",
  recipientEmail: "[email protected]",
  // the published form: its code, or consentDocumentId for one exact version
  documentCode: "infolettre",
  validUntil: "2031-01-01",
}, { idempotencyKey: "order-4471" });

console.log(r.requestId);     // 0x... 64 hex, the public handle
console.log(r.deepLink);      // the recipient's secure approval link
console.log(r.emailDelivered);
$r = $agreely->consentRequests()->create([
    'customerId'     => 'cust_8812',
    'recipientEmail' => '[email protected]',
    'documentCode'   => 'infolettre',
    'validUntil'     => '2031-01-01',
], ['idempotencyKey' => 'order-4471']);

echo $r->requestId;       // 0x... 64 hex
echo $r->deepLink;        // the recipient's secure approval link
var_dump($r->emailDelivered);
agreely documents list --json   # find the code of the published form

agreely request create \
  --customer cust_8812 --to [email protected] \
  --document-code infolettre \
  --valid-until 2031-01-01 --idempotency-key order-4471 --json
# -> {"requestId":"0x...","status":"pending","deepLink":"...","emailDelivered":true,"items":[...],"document":{...}}
curl -sS https://api.agreely.ca/v1/consent-requests \
  -H "Authorization: Bearer $AGREELY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4471" \
  -d '{
    "customerId": "cust_8812",
    "recipientEmail": "[email protected]",
    "documentCode": "infolettre",
    "validUntil": "2031-01-01"
  }'

La réponse est l'IssuedRequest : requestId (la poignée de protocole 0x-hex), status: "pending", le deepLink, emailDelivered, les libellés des éléments et le document (code, nom et version du formulaire auquel l'offre s'engage).

create n'est jamais ré-essayé automatiquement

Parce que l'émission envoie un courriel, le SDK ne la ré-essaie jamais automatiquement. Il attache un Idempotency-Key unique par appel; passez le vôtre (comme ci-dessus) pour qu'une nouvelle tentative rejoue le 201 d'origine au lieu d'émettre deux fois. Un rejeu renvoie la même demande, sans double émission ni double courriel.

Les champs

L'API accepte customerId, recipientEmail, validUntil (la fin du consentement s'il est approuvé : une date simple, soit la fin de ce jour dans le fuseau de votre entreprise, ou un instant avec son décalage, au plus 10 ans après le début) et documentCode ou consentDocumentId. La langue de l'offre suit la langue de correspondance de votre entreprise.

Pour choisir la langue du destinataire, ou pour déclarer un mineur (P-39.1, art. 4.1; A-2.1, art. 64.1 : un indicateur « est un mineur », le consentement parental et par qui il est donné), émettez la demande depuis l'application entreprise, sous Demandes ou depuis le dossier du client : ces champs y sont offerts, pas dans l'API.

Suivre la demande

const page = await agreely.consentRequests.list({ status: "pending" });
const one  = await agreely.consentRequests.get(r.requestId); // by the 0x handle

Une demande reste pending jusqu'à ce que le destinataire réponde. S'il ne répond pas dans la fenêtre de 30 jours, elle bascule de façon différée à expired. À l'approbation, elle devient approved, l'enregistrement d'application de la cellule passe à active, et la toute prochaine vérification de cette cellule renvoie allow. Les statuts possibles sont pending, approved, asks_declined (la personne a répondu en refusant chaque demande de consentement et n'a pris acte que des lignes d'information), refused, expired, revoked_before_action et erased (une approbation dont le consentement a été entièrement effacé).

Pour attendre le règlement plutôt que de sonder à la main, utilisez waitForSettlement (ou agreely request wait à la CLI). Il interroge get jusqu'à ce que la demande soit réglée, puis rend l'enregistrement final.

const settled = await agreely.consentRequests.waitForSettlement(r.requestId, {
  intervalMs: 2000,   // default
  timeoutMs: 120000,  // default; a client-side timeout throws AgreelyTimeoutError, not an outage
});

Ce que fait le destinataire

Le lien profond ouvre le flux d'approbation. Un destinataire pour la première fois crée un DID de citoyen et une clé d'accès; un destinataire de retour se connecte. Il passe en revue les cellules (category, purpose) exactes et approuve avec sa clé d'accès. Cette assertion par clé d'accès, plus la signature de votre entreprise, deviennent les deux preuves dans le reçu.

Ensuite