Aller au contenu
Documentation

Ouvrir le lot et envoyer le code

Ouvrir le lot des parcours d'un groupe, en relever les parcours par paquets, et envoyer au signataire un seul code de sécurité pour tous.

3 min de lecture Mise à jour le 9 novembre 2026

1Ouvrir le lot

POST https://staging-api.docage.com/Transactions/ConsentBatches
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "TransactionIds": ["cccccccc-0000-4000-8000-000000000001", "cccccccc-0000-4000-8000-000000000004"] }

Les parcours d'un groupe (voir Vérifier les parcours), mille au plus. Le premier fixe le groupe du lot — son organisation, son niveau, le canal et la coordonnée du code — : mettez en tête un parcours que la vérification a admis. Un parcours d'un autre groupe sera écarté plus tard, avec sa raison.

JSON
{
  "BatchId": "abababab-0000-4000-8000-000000000009",
  "SignatureLevel": 1,
  "RequiresSecurityCode": true,
  "RequiresQualifiedDevice": false,
  "QualifiedSetup": null,
  "Channel": 1,
  "RecipientMasked": "c***@example.com",
  "ConsentText": "J'atteste avoir pris connaissance du contenu de chacun des documents que je signe et j'accepte sans réserve les conditions. …",
  "TransactionIds": ["cccccccc-0000-4000-8000-000000000001", "cccccccc-0000-4000-8000-000000000004"],
  "ExpiresAtUtc": "2026-11-09T10:45:02.123Z"
}
Propriété Ce qu'elle dit
BatchId L'identifiant du lot, pour chaque étape suivante.
RequiresSecurityCode Le niveau demande un code : relevez les parcours, puis envoyez le code (ci-dessous). Faux : passez directement à la signature.
RequiresQualifiedDevice Signature qualifiée : le certificat du signataire doit être sur un dispositif qualifié (carte, clé).
ConsentText La formule de consentement, dans la langue du compte : à montrer telle quelle au signataire, qui l'accepte avant de signer.
ExpiresAtUtc La fin de vie du lot ouvert : une demi-heure pour relever et recevoir le code.

2Relever les parcours, par vingt-cinq

Quand le niveau demande un code, chaque parcours est relevé : rejugé, l'empreinte de ses documents notée — c'est elle que le code autorisera.

POST https://staging-api.docage.com/Transactions/ConsentBatches/abababab-0000-4000-8000-000000000009/Manifest
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "TransactionIds": ["cccccccc-0000-4000-8000-000000000001", "cccccccc-0000-4000-8000-000000000004"] }
JSON
[
  { "Id": "cccccccc-0000-4000-8000-000000000001", "Result": "Success" },
  { "Id": "cccccccc-0000-4000-8000-000000000004", "Result": "Ce parcours ne relève pas du même groupe que les autres (niveau de signature, organisation ou coordonnée du code) : signez-le dans un autre lot" }
]

Vingt-cinq parcours au plus par requête ; un lot de mille se relève en quarante requêtes, que vous pouvez faire trois à la fois. Success, ou la raison qui écarte le parcours du lot.

3Envoyer le code

POST https://staging-api.docage.com/Transactions/ConsentBatches/abababab-0000-4000-8000-000000000009/SendCode
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
JSON
{
  "BatchId": "abababab-0000-4000-8000-000000000009",
  "Fingerprint": "7F3A-91C2",
  "TransactionIds": ["cccccccc-0000-4000-8000-000000000001"],
  "Channel": 1,
  "RecipientMasked": "c***@example.com",
  "SentAtUtc": "2026-11-09T10:15:02.123Z",
  "ExpiresAtUtc": "2026-11-09T10:25:02.123Z",
  "CodeFormat": "numeric",
  "CodeLength": 6
}
Propriété Ce qu'elle dit
Fingerprint L'empreinte courte du lot. Le message du code la porte aussi : montrez-la au signataire, pour qu'il reconnaisse son code.
TransactionIds Les parcours que le code autorise : ceux qui ont été relevés. Signez ceux-ci.
Channel Le canal du code : 0 SMS, 1 email ; RecipientMasked, la coordonnée qui l'a reçu, masquée.
ExpiresAtUtc La fin de validité du code — dix minutes d'office.
CodeFormat, CodeLength La forme du code à saisir : numeric ou alphanumeric, sa longueur.

Le message du code dit le nombre de parcours et l'empreinte : « Code de sécurité pour signer 2 parcours (lot 7F3A-91C2) : 482913. Ce code est valable 10 minutes. » Un nouvel appel renvoie un code pour les mêmes parcours — trois envois au plus —, le précédent ne vaut plus.

Les refus

400 dit pourquoi :

  • le premier parcours n'entre pas dans un lot, avec sa raison (voir Vérifier les parcours) ;
  • « Une signature groupée compte au plus 1000 parcours » ;
  • « Ce lot ne demande pas de code de sécurité : il s'autorise directement » ;
  • « Aucun parcours de ce lot n'a été relevé : relevez-les avant de demander le code » ;
  • « Le code de ce lot est déjà parti : ouvrez un nouveau lot pour d'autres parcours » ;
  • « Trop de codes envoyés pour ce lot : ouvrez un nouveau lot » ;
  • « L'envoi du code de sécurité a échoué, réessayez dans quelques instants » ;
  • « Ce lot a expiré : recommencez la signature groupée ».

Et :

  • 403 : l'appel n'est pas fait dans la session d'un compte (une clé API, par exemple) ;
  • 429 : plus de dix envois en un quart d'heure pour le même utilisateur — patientez.

Les pièges

  • Un code par SMS est facturé à l'organisation des parcours, comme tout SMS — sauf pour des parcours d'essai.
  • Un parcours dont un code est demandé depuis son invitation, après le relevé, sort du lot : le code ne le signera pas.
  • Suite : Signer le lot, avant ExpiresAtUtc.