Mandats et lots — référence de l’API v1

Mandats de signature et cachets d’organisation en lot. Référence générée depuis les schémas de validation de l’API : ce que vous lisez est ce que le serveur vérifie.

post/signing-mandates — Créer un mandat de signature
get/signing-mandates — Lister les mandats
get/signing-mandates/{id} — Lire un mandat
post/signing-mandates/{id}/revoke — Révoquer un mandat
post/seal-batch — Cacheter un lot sous mandat

Base : https://preprod.signatik.com/api/v1 · authentification Authorization: Bearer sk_… · erreurs { "error": { "code", "message" } }.

post/api/v1/signing-mandates

Créer un mandat de signature

Le représentant légal signe l’acte de mandat en signature avancée (identité attestée requise). Une fois activé, les mandataires peuvent cacheter en lot les documents du périmètre. Scope mandates:manage.

●POST /signing-mandates

curl -X POST https://preprod.signatik.com/api/v1/signing-mandates \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "principal": {
    "legal_name": "ACME SAS",
    "representative": {
      "name": "Contrat de mission n°1234",
      "email": "jean.dupont@exemple.fr",
      "phone": "+33612345678"
    }
  },
  "agents": [
    {
      "name": "Contrat de mission n°1234",
      "email": "jean.dupont@exemple.fr",
      "phone": "+33612345678"
    }
  ],
  "scope": [
    "cmad"
  ],
  "valid_from": "2026-01-12",
  "valid_until": "2027-01-11",
  "message": "Merci de signer avant vendredi."
}'

●201 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "status": "pending",
  "principal": {
    "legal_name": "ACME SAS",
    "siren": "812345678",
    "is_merchant": true,
    "representative": {
      "name": "Contrat de mission n°1234",
      "role": "gérant",
      "email": "jean.dupont@exemple.fr"
    }
  },
  "agents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "email": "jean.dupont@exemple.fr"
    }
  ],
  "scope": [
    "…"
  ],
  "valid_from": "2026-01-12",
  "valid_until": "2027-01-11",
  "envelope_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "document_sha256": "…",
  "activated_at": "2026-09-02T14:33:07Z",
  "revoked_at": "2026-09-02T14:33:07Z",
  "created_at": "…"
}

Corps de la requête

Champ	Type	Description
`principal`requis	object
`legal_name`requis	string	≤ 200 car.
`siren`	string
`is_merchant`	boolean	défaut : true
`representative`requis	object
`name`requis	string	≤ 200 car.
`role`	string	≤ 100 car.
`email`requis	string
`phone`requis	string	≤ 30 car.
`identity_id`	uuid
`identity`	object
`method`requis	"partner_attested" \| "remote_id_check" \| "france_identite"
`given_name`requis	string	≤ 100 car.
`family_name`requis	string	≤ 100 car.
`birth_date`	string
`email`	string
`phone`	string	≤ 30 car.
`document_type`	"id_card" \| "passport" \| "residence_permit" \| "driving_licence" \| "other"
`document_number_hash`	string
`document_expires_on`	string
`verified_at`	date-time
`verified_by`	string	≤ 200 car.
`attestation_ref`	string	≤ 200 car.
`external_ref`	string	≤ 200 car.
`expires_in_days`	integer	1–3650
`agents`requis	object[]	1–20 éléments
`name`requis	string	≤ 200 car.
`email`requis	string
`phone`requis	string	≤ 30 car.
`scope`requis	"cmad" \| "contrat_mission" \| "avenant" \| "releve_heures" \| "autre"[]	1–∞ éléments
`valid_from`requis	string
`valid_until`requis	string
`message`	string	≤ 2000 car.

Réponses

`201`	OK
`400`	Corps invalide
`401`	Clé absente, mal formée ou révoquée (`unauthorized`)
`403`	Scope manquant sur la clé (`forbidden`)
`422`	`identity_required`
`429`	Limitation de débit (`rate_limited`, en-tête `Retry-After`)

Réponse 201

Champ	Type	Description
`id`requis	uuid
`status`requis	"pending" \| "active" \| "revoked" \| "expired"
`principal`requis	object
`legal_name`requis	string
`siren`requis	string \| null
`is_merchant`requis	boolean
`representative`requis	object
`name`requis	string
`role`requis	string \| null
`email`requis	string
`agents`requis	object[]
`id`requis	uuid
`name`requis	string
`email`requis	string
`scope`requis	string[]
`valid_from`requis	string
`valid_until`requis	string
`envelope_id`requis	uuid \| null	Enveloppe de l’acte de mandat, signée en avancé par le représentant
`document_sha256`requis	string \| null
`activated_at`requis	date-time \| null
`revoked_at`requis	date-time \| null
`created_at`requis	string

get/api/v1/signing-mandates

Lister les mandats

●GET /signing-mandates

curl -X GET https://preprod.signatik.com/api/v1/signing-mandates \
  -H "Authorization: Bearer sk_test_…"

●200 — exemple de réponse

{
  "data": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "status": "pending",
      "principal": {
        "legal_name": "ACME SAS",
        "siren": "812345678",
        "is_merchant": true,
        "representative": {
          "name": "Contrat de mission n°1234",
          "role": "gérant",
          "email": "jean.dupont@exemple.fr"
        }
      },
      "agents": [
        {
          "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
          "name": "Contrat de mission n°1234",
          "email": "jean.dupont@exemple.fr"
        }
      ],
      "scope": [
        "…"
      ],
      "valid_from": "2026-01-12",
      "valid_until": "2027-01-11",
      "envelope_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "document_sha256": "…",
      "activated_at": "2026-09-02T14:33:07Z",
      "revoked_at": "2026-09-02T14:33:07Z",
      "created_at": "…"
    }
  ]
}

Réponses

`200`	OK
`401`	Clé absente, mal formée ou révoquée (`unauthorized`)
`403`	Scope manquant sur la clé (`forbidden`)
`429`	Limitation de débit (`rate_limited`, en-tête `Retry-After`)

Réponse 200

Champ	Type	Description
`data`requis	SigningMandate[]
`id`requis	uuid
`status`requis	"pending" \| "active" \| "revoked" \| "expired"
`principal`requis	object
`legal_name`requis	string
`siren`requis	string \| null
`is_merchant`requis	boolean
`representative`requis	object
`name`requis	string
`role`requis	string \| null
`email`requis	string
`agents`requis	object[]
`id`requis	uuid
`name`requis	string
`email`requis	string
`scope`requis	string[]
`valid_from`requis	string
`valid_until`requis	string
`envelope_id`requis	uuid \| null	Enveloppe de l’acte de mandat, signée en avancé par le représentant
`document_sha256`requis	string \| null
`activated_at`requis	date-time \| null
`revoked_at`requis	date-time \| null
`created_at`requis	string

get/api/v1/signing-mandates/{id}

Lire un mandat

●GET /signing-mandates/{id}

curl -X GET https://preprod.signatik.com/api/v1/signing-mandates/env_8f2c… \
  -H "Authorization: Bearer sk_test_…"

●200 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "status": "pending",
  "principal": {
    "legal_name": "ACME SAS",
    "siren": "812345678",
    "is_merchant": true,
    "representative": {
      "name": "Contrat de mission n°1234",
      "role": "gérant",
      "email": "jean.dupont@exemple.fr"
    }
  },
  "agents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "email": "jean.dupont@exemple.fr"
    }
  ],
  "scope": [
    "…"
  ],
  "valid_from": "2026-01-12",
  "valid_until": "2027-01-11",
  "envelope_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "document_sha256": "…",
  "activated_at": "2026-09-02T14:33:07Z",
  "revoked_at": "2026-09-02T14:33:07Z",
  "created_at": "…"
}

Paramètres de chemin

id uuid

Réponses

`200`	OK
`401`	Clé absente, mal formée ou révoquée (`unauthorized`)
`403`	Scope manquant sur la clé (`forbidden`)
`404`	Introuvable
`429`	Limitation de débit (`rate_limited`, en-tête `Retry-After`)

Réponse 200

Champ	Type	Description
`id`requis	uuid
`status`requis	"pending" \| "active" \| "revoked" \| "expired"
`principal`requis	object
`legal_name`requis	string
`siren`requis	string \| null
`is_merchant`requis	boolean
`representative`requis	object
`name`requis	string
`role`requis	string \| null
`email`requis	string
`agents`requis	object[]
`id`requis	uuid
`name`requis	string
`email`requis	string
`scope`requis	string[]
`valid_from`requis	string
`valid_until`requis	string
`envelope_id`requis	uuid \| null	Enveloppe de l’acte de mandat, signée en avancé par le représentant
`document_sha256`requis	string \| null
`activated_at`requis	date-time \| null
`revoked_at`requis	date-time \| null
`created_at`requis	string

post/api/v1/signing-mandates/{id}/revoke

Révoquer un mandat

●POST /signing-mandates/{id}/revoke

curl -X POST https://preprod.signatik.com/api/v1/signing-mandates/env_8f2c…/revoke \
  -H "Authorization: Bearer sk_test_…"

●200 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "status": "pending",
  "principal": {
    "legal_name": "ACME SAS",
    "siren": "812345678",
    "is_merchant": true,
    "representative": {
      "name": "Contrat de mission n°1234",
      "role": "gérant",
      "email": "jean.dupont@exemple.fr"
    }
  },
  "agents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "email": "jean.dupont@exemple.fr"
    }
  ],
  "scope": [
    "…"
  ],
  "valid_from": "2026-01-12",
  "valid_until": "2027-01-11",
  "envelope_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "document_sha256": "…",
  "activated_at": "2026-09-02T14:33:07Z",
  "revoked_at": "2026-09-02T14:33:07Z",
  "created_at": "…"
}

Paramètres de chemin

id uuid

Réponses

`200`	OK
`401`	Clé absente, mal formée ou révoquée (`unauthorized`)
`403`	Scope manquant sur la clé (`forbidden`)
`404`	Introuvable
`409`	`invalid_status`
`429`	Limitation de débit (`rate_limited`, en-tête `Retry-After`)

Réponse 200

Champ	Type	Description
`id`requis	uuid
`status`requis	"pending" \| "active" \| "revoked" \| "expired"
`principal`requis	object
`legal_name`requis	string
`siren`requis	string \| null
`is_merchant`requis	boolean
`representative`requis	object
`name`requis	string
`role`requis	string \| null
`email`requis	string
`agents`requis	object[]
`id`requis	uuid
`name`requis	string
`email`requis	string
`scope`requis	string[]
`valid_from`requis	string
`valid_until`requis	string
`envelope_id`requis	uuid \| null	Enveloppe de l’acte de mandat, signée en avancé par le représentant
`document_sha256`requis	string \| null
`activated_at`requis	date-time \| null
`revoked_at`requis	date-time \| null
`created_at`requis	string

post/api/v1/seal-batch

Cacheter un lot sous mandat

Jusqu’à 500 enveloppes organization_seal du même mandat. Le mandataire reçoit une authorization_url, vérifie la liste et saisit un seul code à usage unique. Le jeton porte sur l’empreinte de la liste des empreintes : ajouter un document invalide le lot (409 batch_mismatch).

●POST /seal-batch

curl -X POST https://preprod.signatik.com/api/v1/seal-batch \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "agent_email": "marie.leroy@exemple.fr",
  "envelope_ids": [
    "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f"
  ],
  "expires_in_hours": 72
}'

●201 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "status": "pending",
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "principal": "…",
  "agent": {
    "name": "Contrat de mission n°1234",
    "email": "jean.dupont@exemple.fr"
  },
  "envelope_ids": [
    "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f"
  ],
  "batch_sha256": "…",
  "authorization_url": "…",
  "expires_at": "…",
  "authorized_at": "2026-09-02T14:33:07Z",
  "applied_at": "2026-09-02T14:33:07Z",
  "created_at": "…"
}

Corps de la requête

Champ	Type	Description
`mandate_id`requis	uuid
`agent_email`	string
`envelope_ids`requis	uuid[]	1–500 éléments
`expires_in_hours`	integer	défaut : 72 · 1–168

Réponses

`201`	OK
`400`	Corps invalide
`401`	Clé absente, mal formée ou révoquée (`unauthorized`)
`403`	Scope manquant sur la clé (`forbidden`)
`404`	Mandat ou enveloppe introuvable
`409`	`mandate_not_active`, `mandate_expired`, `invalid_status`
`422`	`agent_not_in_mandate`
`429`	Limitation de débit (`rate_limited`, en-tête `Retry-After`)

Réponse 201

Champ	Type	Description
`id`requis	uuid
`status`requis	"pending" \| "authorized" \| "applied" \| "expired" \| "canceled"
`mandate_id`requis	uuid
`principal`requis	string
`agent`requis	object
`name`requis	string
`email`requis	string
`envelope_ids`requis	uuid[]
`batch_sha256`requis	string	Empreinte de la liste des empreintes : l’ajout d’un document invalide le jeton
`authorization_url`requis	string \| null
`expires_at`requis	string
`authorized_at`requis	date-time \| null
`applied_at`requis	date-time \| null
`created_at`requis	string