É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 et 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é).

Émettre la demande

items sont des ids d'entrées de catalogue et/ou des paires brutes {category, purpose}, résolues côté serveur vers vos entrées de catalogue actives déclarées. L'offre est signée sur le backend (votre clé de signature ne le quitte jamais) et le courriel est envoyé après la validation.

const r = await agreely.consentRequests.create({
  customerId: "cust_8812",
  recipientEmail: "[email protected]",
  // catalog entry ids AND/OR raw {category, purpose} pairs:
  items: ["<catalogEntryId>", { category: "Email address", purpose: "Newsletter" }],
  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]',
    'items'          => ['<catalogEntryId>', ['category' => 'Email address', 'purpose' => 'Newsletter']],
    '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 request create \
  --customer cust_8812 --to [email protected] \
  --item "Email address:Newsletter" --item <catalogEntryId> \
  --valid-until 2031-01-01 --idempotency-key order-4471 --json
# -> {"requestId":"0x...","status":"pending","deepLink":"...","emailDelivered":true,"items":[...]}
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]",
    "items": ["<catalogEntryId>", {"category":"Email address","purpose":"Newsletter"}],
    "validUntil": "2031-01-01"
  }'

La réponse est l'IssuedRequest : requestId (la poignée de protocole 0x-hex), status: "pending", le deepLink, emailDelivered et les libellés des éléments.

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.

Champs facultatifs

Au-delà de customerId, recipientEmail, items et validUntil (au-delà de cette date, l'offre expire), une demande accepte deux entrées facultatives :

  • la langue du destinataire (français ou anglais), pour que l'offre lui soit présentée dans sa langue;
  • les champs relatifs au mineur (article 4.1) : un indicateur « est un mineur », le consentement parental, et par qui il est donné.

La référence /v1 interactive donne les noms de champ exacts et leurs contraintes.

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. Une demande réglée est l'un de pending, approved, refused, expired ou revoked_before_action.

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