Agreely Docs
FR EN

Protéger une fonctionnalité en 5 minutes

L'objectif : avant que votre code utilise un renseignement personnel à une fin donnée, il demande à Agreely si la personne a autorisé cet usage, et respecte la réponse. Toute l'intégration tient en un seul appel.

1. Installer et s'authentifier

npm install @agreely/sdk      # or: composer require agreely/sdk
export AGREELY_API_KEY=agr_live_xxx

Une clé à portée check est tout ce qu'il vous faut pour protéger des fonctionnalités.

2. Trouver la cellule

Une cellule de consentement est une catégorie de données croisée avec une finalité : Phone number x Billing. Utilisez les libellés exacts, lisibles par un humain, que déclare votre catalogue; le serveur les normalise (rogner, réduire les espaces, mettre en minuscules, ignorer les accents), de sorte que la casse, l'espacement et les accents n'ont pas d'importance. Le libellé français est accepté, et le libellé anglais l'est lorsque l'entreprise en a déclaré un pour la cellule; un libellé non déclaré refuse, tout comme un libellé ambigu, qui une fois normalisé désigne plus d'une cellule (deux libellés qui ne diffèrent que par les accents, par exemple). Ne les normalisez jamais vous-même.

agreely catalog --json    # discover your declared (category, purpose) cells

3. Encapsuler l'usage de données

import { Agreely } from "@agreely/sdk";

const agreely = new Agreely({ apiKey: process.env.AGREELY_API_KEY! });

async function chargeCard(customerId: string) {
  if (!(await agreely.check(customerId, "Phone number", "Billing"))) {
    return; // denied: do not use the phone number for billing
  }
  // allowed: proceed
}

check() renvoie un booléen et allow est le seul true. Une cellule révoquée, expirée ou effacée vaut false, tout comme une cellule fondée sur le consentement qui n'a jamais été accordée. Une cellule déclarée sur une autre base que le consentement répond allow avec le statut necessity.

4. Traiter les raisons quand cela compte

Pour l'expérience utilisateur ou la journalisation, checkDetailed() vous dit pourquoi :

const d = await agreely.checkDetailed(customerId, "Phone number", "Billing");
switch (d.status) {
  case "active":     /* allow */ break;
  case "necessity":  /* allow on the declared non-consent basis (d.basis) */ break;
  case "none":       /* never granted: ask for consent */ break;
  case "revoked":    /* withdrawn: stop, never re-ask automatically */ break;
  case "expired":    /* lapsed: re-ask */ break;
  case "relationship_ended":         /* P-39.1 s. 12 / A-2.1 s. 65.1, first para.: use ends with the purposes; do not re-ask automatically */ break;
  case "requires_depersonalization": /* depersonalized-only ground: never answer it by asking consent */ break;
  case "basis_not_in_regime":        /* the catalog cell needs a re-declaration */ break;
  default:                           /* an unknown status: treat it as a deny */ break;
}

Branchez toujours sur d.decision pour la décision elle-même; le status est le pourquoi. Une réponse adossée à un consentement porte aussi d.tier (full, manual ou verbal) et d.validUntil, la fin du consentement : c'est votre code qui décide du palier qu'un usage accepte, et validUntil ne sert jamais de durée de cache. Le vocabulaire complet est dans la référence de l'API.

Un refus est un 200 normal. checkDetailed le renvoie; il ne lève une exception que sur une clé refusée ou sans la portée voulue (401, 403), un abonnement suspendu (402), une erreur de validation, une limite de débit ou une panne.

5. Connaître le mode de défaillance

La vérification fonctionne en refus par défaut. Si Agreely est injoignable, check() renvoie false (refus) et checkDetailed() lève AgreelyUnavailableError. C'est la valeur par défaut sûre : une panne n'accorde jamais l'accès en silence. Il en va de même lorsque la facturation de l'entreprise est suspendue (un 402) : check() renvoie false et checkDetailed() lève AgreelyBillingInactiveError. Si une catégorie précise et à faible risque a réellement besoin de continuer à fonctionner pendant une panne, voir composer avec les pannes pour l'exception d'ouverture en cas de panne délibérée et auditée.

Ensuite