Référence JSON

Cette section documente champ par champ les artéfacts tels qu'ils circulent sur le réseau. Chaque exemple est la forme réelle que construit le code d'Agreely, et non une illustration. À lire en parallèle du protocole pour la cryptographie derrière chaque champ.

• La demande de consentement (cette page) : l'offre signée qu'une entreprise émet.
• Le reçu de consentement : le justificatif vérifiable que reçoit le citoyen.
• Documents DID : entreprise et citoyen.
• Vérifier un reçu : les quatre contrôles qu'effectue un auditeur.

#La demande de consentement (l'offre signée)

Lorsqu'une entreprise émet une demande de consentement, Agreely construit une offre sans nombres, signe ses octets JCS-canoniques avec la clé de l'entreprise, et enveloppe la signature comme une preuve Data Integrity companySig. Aucune valeur n'est un nombre (seulement des chaînes, des booléens et des objets), de sorte que les octets canoniques qu'un vérificateur redérive ne peuvent jamais diverger.

La référence client de l'entreprise n'est pas dans l'offre signée : elle suivrait chaque reçu et chaque dossier de vérification, et permettrait de les corréler d'une organisation à l'autre. Agreely ne l'ajoute qu'à la copie chiffrée qu'il conserve (voir au repos).

{
  "requestId": "0x4b08245219c0e1a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7081234",
  "issuer": "did:web:app.agreely.ca:c:acme",
  "consent": {
    "action": "grant",
    "items": [
      {
        "itemId": "0x9a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7081",
        "category": "phone number",
        "purpose": "billing",
        "sensitive": false,
        "automatedDecision": false,
        "legalBasis": "consent"
      }
    ]
  },
  "nonce": "0x7081234b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f",
  "validUntil": "2031-01-01T00:00:00Z",
  "createdAt": "2026-06-26T15:00:00Z",
  "expiresAt": "2026-07-26T15:00:00Z",
  "document": {
    "code": "acme-billing-v3",
    "name": "Consentement facturation v3",
    "version": "3",
    "effectiveDate": "2026-01-01"
  },
  "disclosure": {
    "purpose": { "fr": "…", "en": "…" },
    "categories": { "fr": "…", "en": "…" },
    "retention": { "fr": "…", "en": "…" },
    "withdrawal": { "fr": "…", "en": "…" },
    "recipients": { "fr": "…", "en": "…" },
    "rights": { "fr": "…", "en": "…" },
    "responsable": { "name": "…", "contact": "…" }
  },
  "disclosureVersion": "1",
  "disclosureHash": "0x…sha256…",
  "companySig": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-06-26T15:00:00Z",
    "verificationMethod": "did:web:app.agreely.ca:c:acme#kms-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3Ge8wQ5...base58btc..."
  }
}

#Champ par champ

Champ	Type	Signification
requestId	0x + 64 hex	La poignée du protocole : 32 octets aléatoires frais, jamais dérivés. L'identifiant public partout, jamais un uuid interne.
issuer	chaîne	Le DID de l'entreprise, did:web:app.agreely.ca:c:{slug}.
consent.action	chaîne	grant.
consent.items[].itemId	0x + 64 hex	Une poignée opaque aléatoire fraîche pour cet élément.
consent.items[].category	chaîne	La clé de catégorie normalisée (valeur canonique en minuscules), pas le libellé d'affichage.
consent.items[].purpose	chaîne	La clé de finalité normalisée.
consent.items[].sensitive	booléen	La cellule est déclarée sensible (son consentement doit alors être exprès).
consent.items[].automatedDecision	booléen	La cellule alimente une décision fondée exclusivement sur un traitement automatisé.
consent.items[].legalBasis	chaîne	Le motif que l'entreprise déclare pour la cellule; consent pour une demande de consentement.
nonce	0x + 64 hex	Nonce aléatoire à usage unique, lié au défi d'approbation afin que la réponse ne puisse être rejouée.
validUntil	RFC 3339	La durée de vie du consentement s'il est approuvé.
createdAt	RFC 3339	Quand l'offre a été créée.
expiresAt	RFC 3339	L'échéance de réponse (30 jours). Une demande en attente passé ce délai bascule à expired.
document	objet	Le descripteur du document de consentement : code, name, nameEn quand le document a un nom anglais, version, effectiveDate, et ipfsCid seulement quand la version est épinglée sur IPFS.
disclosure	objet	L'information bilingue donnée à la personne, section par section ({fr, en} par section; responsable vaut {name, contact}). Les sections means, withdrawal, refusalConsequences, crossBorder, automatedDecision et profiling n'y figurent que lorsque le document les porte.
disclosureVersion	chaîne	"1" : disclosureHash porte sur disclosure seul. "2" : au moins une cellule repose sur un motif autre que le consentement, et l'empreinte porte sur {disclosure, legalBasis}.
disclosureHash	0x + 64 hex	Le SHA-256 de la préimage canonique JCS que nomme disclosureVersion.
legalBasis	objet	Présent seulement en version "2" : pour chaque itemId d'une cellule qui ne repose pas sur le consentement, {basis, justificationFr, justificationEn?}.
minor	objet	Présent seulement quand la personne est mineure de moins de 14 ans : {isMinorUnder14: true, parentalConsentObtained}. Le nom du titulaire de l'autorité parentale n'entre jamais dans les octets signés.
companySig	objet	La preuve Data Integrity eddsa-jcs-2022 sur l'offre.

#Au repos

L'objet qu'Agreely stocke (chiffré sous la DEK du locataire) est l'offre, son companySig, et trois champs d'enveloppe qui ne sont pas couverts par companySig : subject (la propre référence client de l'entreprise, ref, et status, known ou unonboarded selon que le destinataire possède déjà un DID de citoyen), status et result :

{
  "...": "all offer fields above",
  "companySig": { "...": "the proof" },
  "subject": { "ref": "cust_8812", "status": "known" },
  "status": "pending",
  "result": { "receipts": null, "settledAt": null }
}

status progresse vers approved, refused, expired ou revoked_before_action; result est rempli lorsque la demande est réglée.

#Les formes exposées au SDK

L'API /v1 renvoie des vues allégées d'une demande plutôt que l'objet signé brut. La réponse d'émission (IssuedRequest) et la vue liste/affichage (ConsentRequest) sont documentées dans la référence de l'API et la spécification interactive.