Enveloppes — référence de l’API v1

Documents à signer, signataires, champs, cycle de vie. 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/envelopes — Créer une enveloppe (et l’envoyer)
get/envelopes — Lister les enveloppes
get/envelopes/{id} — Lire une enveloppe
post/envelopes/{id}/send — Envoyer un brouillon
post/envelopes/{id}/cancel — Annuler

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

post/api/v1/envelopes

Créer une enveloppe (et l’envoyer)

Une enveloppe = une requête : PDF en base64, signataires, champs. send: true envoie immédiatement. Le niveau se choisit par signature_level : simple (défaut), advanced (identité attestée obligatoire, sinon 422 identity_required) ou organization_seal (cachet sous mandat, signé en lot). En libre-service, le coût maximal est réservé à l’envoi (402 insufficient_credits sinon), débité à la complétion, rendu à l’annulation ou à l’expiration. Scope envelopes:write.

●POST /envelopes

curl -X POST https://preprod.signatik.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Contrat de mission n°1234",
  "message": "Merci de signer avant vendredi.",
  "expires_in_days": 30,
  "retention_days": 1,
  "send": false,
  "signature_level": "simple",
  "qualified_timestamp": true,
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "documents": [
    {
      "name": "Contrat de mission n°1234",
      "pdf_base64": "JVBERi0…"
    }
  ],
  "signers": [
    {
      "email": "jean.dupont@exemple.fr",
      "name": "Contrat de mission n°1234"
    }
  ],
  "fields": []
}'

●201 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "name": "Contrat de mission n°1234",
  "status": "draft",
  "mode": "live",
  "message": "Merci de signer avant vendredi.",
  "signature_level": "simple",
  "pades_level": "…",
  "qualified_timestamp": true,
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "batch_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "prepared": true,
  "created_at": "…",
  "expires_at": "2026-09-02T14:33:07Z",
  "completed_at": "2026-09-02T14:33:07Z",
  "sealed_at": "2026-09-02T14:33:07Z",
  "retention_days": 1,
  "documents_available": true,
  "purge_after": "2026-09-02T14:33:07Z",
  "purged_at": "2026-09-02T14:33:07Z",
  "documents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "sealed_sha256": "…",
      "revision": 1,
      "current_sha256": "…",
      "sealed_download_url": "…"
    }
  ],
  "evidence_download_url": "…",
  "signers": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "email": "jean.dupont@exemple.fr",
      "name": "Contrat de mission n°1234",
      "order": 1,
      "role": "gérant",
      "status": "pending",
      "signed_at": "2026-09-02T14:33:07Z",
      "sign_url": "…"
    }
  ]
}

Corps de la requête

Champ	Type	Description
`name`requis	string	≤ 200 car.
`message`	string	≤ 2000 car.
`expires_in_days`	integer	défaut : 30 · 1–90
`retention_days`	integer	1–90
`send`	boolean	défaut : false
`signature_level`	"simple" \| "advanced" \| "organization_seal"	défaut : "simple"
`qualified_timestamp`	boolean	défaut : true
`mandate_id`	uuid
`documents`requis	object[]	1–5 éléments
`name`requis	string	≤ 200 car.
`pdf_base64`requis	string
`signers`requis	object[]	1–10 éléments
`email`requis	string
`name`requis	string	≤ 200 car.
`order`	integer	défaut : 0 · 0–20
`phone`	string	≤ 30 car.
`authentication`	"otp_email" \| "otp_sms"[]	1–∞ éléments
`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
`fields`	object[]	défaut : []
`document_index`requis	integer	0–
`signer_index`requis	integer	0–
`type`requis	"signature" \| "text" \| "date" \| "checkbox"
`page`requis	integer	1–
`x`requis	number	0–100
`y`requis	number	0–100
`width`requis	number	0.5–100
`height`requis	number	0.5–100
`value`	string	≤ 1000 car.

Réponses

`201`	Enveloppe créée, avec `sign_url` par signataire
`400`	Corps invalide, PDF invalide, index de champ hors limites
`401`	Clé absente, mal formée ou révoquée (`unauthorized`)
`402`	Crédits insuffisants (libre-service)
`403`	Scope manquant sur la clé (`forbidden`)
`413`	Corps trop volumineux (5 PDF de 10 Mo max)
`422`	`identity_required`, `phone_required`, `mandate_required`, `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
`name`requis	string
`status`requis	"draft" \| "sent" \| "completed" \| "expired" \| "canceled"
`mode`requis	"live" \| "test"	test = bac à sable (clé sk_test_), jamais facturé
`message`requis	string \| null
`signature_level`requis	"simple" \| "advanced" \| "organization_seal"
`pades_level`requis	string \| null
`qualified_timestamp`requis	boolean
`mandate_id`requis	uuid \| null
`batch_id`requis	uuid \| null
`prepared`requis	boolean
`created_at`requis	string
`expires_at`requis	date-time \| null
`completed_at`requis	date-time \| null
`sealed_at`requis	date-time \| null
`retention_days`requis	integer
`documents_available`requis	boolean
`purge_after`requis	date-time \| null
`purged_at`requis	date-time \| null
`documents`requis	object[]
`id`requis	uuid
`name`requis	string
`sha256`requis	string	Empreinte du PDF original
`sealed_sha256`requis	string \| null	Empreinte du PDF scellé
`revision`requis	integer
`current_sha256`requis	string \| null
`sealed_download_url`requis	string \| null	Lien temporaire (1 h), null avant scellement ou après purge
`evidence_download_url`requis	string \| null	Dossier de preuve scellé (lien 1 h)
`signers`requis	object[]
`id`requis	uuid
`email`requis	string
`name`requis	string
`order`requis	integer
`role`requis	"signer" \| "agent"
`status`requis	"pending" \| "notified" \| "signed"
`signed_at`requis	date-time \| null
`sign_url`requis	string \| null	URL personnelle de signature (marque blanche : à injecter dans votre produit)
`signature`	object	Présent en signature avancée et cachet d’organisation
`level`requis	"advanced" \| "organization_seal"
`identity_id`requis	uuid \| null
`authentication`requis	string[]
`authentication_used`requis	string[]
`identity_confirmed_at`requis	date-time \| null
`certificate_serial`requis	string \| null
`certificate_subject`requis	string \| null
`certificate_fingerprint_sha256`requis	string \| null
`applied_at`requis	date-time \| null
`timestamp`requis	object \| null
`issuer`requis	string \| null
`serial`requis	string \| null
`gen_time`requis	string
`qualified`requis	boolean
`provider`requis	string \| null

get/api/v1/envelopes

Lister les enveloppes

Plus récentes d’abord. Scope envelopes:read.

●GET /envelopes

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

●200 — exemple de réponse

{
  "data": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "status": "…",
      "created_at": "…",
      "completed_at": "2026-09-02T14:33:07Z"
    }
  ],
  "limit": 1,
  "offset": 1
}

Paramètres de requête

`limit`	integer
`offset`	integer \| null

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	object[]
`id`requis	uuid
`name`requis	string
`status`requis	string
`created_at`requis	string
`completed_at`requis	date-time \| null
`limit`requis	integer
`offset`requis	integer

get/api/v1/envelopes/{id}

Lire une enveloppe

Statut, signataires, documents avec liens de téléchargement temporaires (1 h) une fois scellée. Après purge, les liens sont null mais la preuve reste vérifiable via /verify.

●GET /envelopes/{id}

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

●200 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "name": "Contrat de mission n°1234",
  "status": "draft",
  "mode": "live",
  "message": "Merci de signer avant vendredi.",
  "signature_level": "simple",
  "pades_level": "…",
  "qualified_timestamp": true,
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "batch_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "prepared": true,
  "created_at": "…",
  "expires_at": "2026-09-02T14:33:07Z",
  "completed_at": "2026-09-02T14:33:07Z",
  "sealed_at": "2026-09-02T14:33:07Z",
  "retention_days": 1,
  "documents_available": true,
  "purge_after": "2026-09-02T14:33:07Z",
  "purged_at": "2026-09-02T14:33:07Z",
  "documents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "sealed_sha256": "…",
      "revision": 1,
      "current_sha256": "…",
      "sealed_download_url": "…"
    }
  ],
  "evidence_download_url": "…",
  "signers": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "email": "jean.dupont@exemple.fr",
      "name": "Contrat de mission n°1234",
      "order": 1,
      "role": "gérant",
      "status": "pending",
      "signed_at": "2026-09-02T14:33:07Z",
      "sign_url": "…"
    }
  ]
}

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`	Enveloppe introuvable
`429`	Limitation de débit (`rate_limited`, en-tête `Retry-After`)

Réponse 200

Champ	Type	Description
`id`requis	uuid
`name`requis	string
`status`requis	"draft" \| "sent" \| "completed" \| "expired" \| "canceled"
`mode`requis	"live" \| "test"	test = bac à sable (clé sk_test_), jamais facturé
`message`requis	string \| null
`signature_level`requis	"simple" \| "advanced" \| "organization_seal"
`pades_level`requis	string \| null
`qualified_timestamp`requis	boolean
`mandate_id`requis	uuid \| null
`batch_id`requis	uuid \| null
`prepared`requis	boolean
`created_at`requis	string
`expires_at`requis	date-time \| null
`completed_at`requis	date-time \| null
`sealed_at`requis	date-time \| null
`retention_days`requis	integer
`documents_available`requis	boolean
`purge_after`requis	date-time \| null
`purged_at`requis	date-time \| null
`documents`requis	object[]
`id`requis	uuid
`name`requis	string
`sha256`requis	string	Empreinte du PDF original
`sealed_sha256`requis	string \| null	Empreinte du PDF scellé
`revision`requis	integer
`current_sha256`requis	string \| null
`sealed_download_url`requis	string \| null	Lien temporaire (1 h), null avant scellement ou après purge
`evidence_download_url`requis	string \| null	Dossier de preuve scellé (lien 1 h)
`signers`requis	object[]
`id`requis	uuid
`email`requis	string
`name`requis	string
`order`requis	integer
`role`requis	"signer" \| "agent"
`status`requis	"pending" \| "notified" \| "signed"
`signed_at`requis	date-time \| null
`sign_url`requis	string \| null	URL personnelle de signature (marque blanche : à injecter dans votre produit)
`signature`	object	Présent en signature avancée et cachet d’organisation
`level`requis	"advanced" \| "organization_seal"
`identity_id`requis	uuid \| null
`authentication`requis	string[]
`authentication_used`requis	string[]
`identity_confirmed_at`requis	date-time \| null
`certificate_serial`requis	string \| null
`certificate_subject`requis	string \| null
`certificate_fingerprint_sha256`requis	string \| null
`applied_at`requis	date-time \| null
`timestamp`requis	object \| null
`issuer`requis	string \| null
`serial`requis	string \| null
`gen_time`requis	string
`qualified`requis	boolean
`provider`requis	string \| null

post/api/v1/envelopes/{id}/send

Envoyer un brouillon

Passe l’enveloppe de draft à sent et notifie les signataires. Réserve les crédits en libre-service.

●POST /envelopes/{id}/send

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

●200 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "name": "Contrat de mission n°1234",
  "status": "draft",
  "mode": "live",
  "message": "Merci de signer avant vendredi.",
  "signature_level": "simple",
  "pades_level": "…",
  "qualified_timestamp": true,
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "batch_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "prepared": true,
  "created_at": "…",
  "expires_at": "2026-09-02T14:33:07Z",
  "completed_at": "2026-09-02T14:33:07Z",
  "sealed_at": "2026-09-02T14:33:07Z",
  "retention_days": 1,
  "documents_available": true,
  "purge_after": "2026-09-02T14:33:07Z",
  "purged_at": "2026-09-02T14:33:07Z",
  "documents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "sealed_sha256": "…",
      "revision": 1,
      "current_sha256": "…",
      "sealed_download_url": "…"
    }
  ],
  "evidence_download_url": "…",
  "signers": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "email": "jean.dupont@exemple.fr",
      "name": "Contrat de mission n°1234",
      "order": 1,
      "role": "gérant",
      "status": "pending",
      "signed_at": "2026-09-02T14:33:07Z",
      "sign_url": "…"
    }
  ]
}

Paramètres de chemin

id uuid

Réponses

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

Réponse 200

Champ	Type	Description
`id`requis	uuid
`name`requis	string
`status`requis	"draft" \| "sent" \| "completed" \| "expired" \| "canceled"
`mode`requis	"live" \| "test"	test = bac à sable (clé sk_test_), jamais facturé
`message`requis	string \| null
`signature_level`requis	"simple" \| "advanced" \| "organization_seal"
`pades_level`requis	string \| null
`qualified_timestamp`requis	boolean
`mandate_id`requis	uuid \| null
`batch_id`requis	uuid \| null
`prepared`requis	boolean
`created_at`requis	string
`expires_at`requis	date-time \| null
`completed_at`requis	date-time \| null
`sealed_at`requis	date-time \| null
`retention_days`requis	integer
`documents_available`requis	boolean
`purge_after`requis	date-time \| null
`purged_at`requis	date-time \| null
`documents`requis	object[]
`id`requis	uuid
`name`requis	string
`sha256`requis	string	Empreinte du PDF original
`sealed_sha256`requis	string \| null	Empreinte du PDF scellé
`revision`requis	integer
`current_sha256`requis	string \| null
`sealed_download_url`requis	string \| null	Lien temporaire (1 h), null avant scellement ou après purge
`evidence_download_url`requis	string \| null	Dossier de preuve scellé (lien 1 h)
`signers`requis	object[]
`id`requis	uuid
`email`requis	string
`name`requis	string
`order`requis	integer
`role`requis	"signer" \| "agent"
`status`requis	"pending" \| "notified" \| "signed"
`signed_at`requis	date-time \| null
`sign_url`requis	string \| null	URL personnelle de signature (marque blanche : à injecter dans votre produit)
`signature`	object	Présent en signature avancée et cachet d’organisation
`level`requis	"advanced" \| "organization_seal"
`identity_id`requis	uuid \| null
`authentication`requis	string[]
`authentication_used`requis	string[]
`identity_confirmed_at`requis	date-time \| null
`certificate_serial`requis	string \| null
`certificate_subject`requis	string \| null
`certificate_fingerprint_sha256`requis	string \| null
`applied_at`requis	date-time \| null
`timestamp`requis	object \| null
`issuer`requis	string \| null
`serial`requis	string \| null
`gen_time`requis	string
`qualified`requis	boolean
`provider`requis	string \| null

post/api/v1/envelopes/{id}/cancel

Annuler

Possible en draft ou sent. Les liens de signature deviennent inactifs (410 gone) et les crédits réservés sont rendus.

●POST /envelopes/{id}/cancel

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

●200 — exemple de réponse

{
  "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "name": "Contrat de mission n°1234",
  "status": "draft",
  "mode": "live",
  "message": "Merci de signer avant vendredi.",
  "signature_level": "simple",
  "pades_level": "…",
  "qualified_timestamp": true,
  "mandate_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "batch_id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
  "prepared": true,
  "created_at": "…",
  "expires_at": "2026-09-02T14:33:07Z",
  "completed_at": "2026-09-02T14:33:07Z",
  "sealed_at": "2026-09-02T14:33:07Z",
  "retention_days": 1,
  "documents_available": true,
  "purge_after": "2026-09-02T14:33:07Z",
  "purged_at": "2026-09-02T14:33:07Z",
  "documents": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "name": "Contrat de mission n°1234",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "sealed_sha256": "…",
      "revision": 1,
      "current_sha256": "…",
      "sealed_download_url": "…"
    }
  ],
  "evidence_download_url": "…",
  "signers": [
    {
      "id": "8f2c1d4e-0b7a-4c1e-9f0d-6a3b2c1d0e9f",
      "email": "jean.dupont@exemple.fr",
      "name": "Contrat de mission n°1234",
      "order": 1,
      "role": "gérant",
      "status": "pending",
      "signed_at": "2026-09-02T14:33:07Z",
      "sign_url": "…"
    }
  ]
}

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
`name`requis	string
`status`requis	"draft" \| "sent" \| "completed" \| "expired" \| "canceled"
`mode`requis	"live" \| "test"	test = bac à sable (clé sk_test_), jamais facturé
`message`requis	string \| null
`signature_level`requis	"simple" \| "advanced" \| "organization_seal"
`pades_level`requis	string \| null
`qualified_timestamp`requis	boolean
`mandate_id`requis	uuid \| null
`batch_id`requis	uuid \| null
`prepared`requis	boolean
`created_at`requis	string
`expires_at`requis	date-time \| null
`completed_at`requis	date-time \| null
`sealed_at`requis	date-time \| null
`retention_days`requis	integer
`documents_available`requis	boolean
`purge_after`requis	date-time \| null
`purged_at`requis	date-time \| null
`documents`requis	object[]
`id`requis	uuid
`name`requis	string
`sha256`requis	string	Empreinte du PDF original
`sealed_sha256`requis	string \| null	Empreinte du PDF scellé
`revision`requis	integer
`current_sha256`requis	string \| null
`sealed_download_url`requis	string \| null	Lien temporaire (1 h), null avant scellement ou après purge
`evidence_download_url`requis	string \| null	Dossier de preuve scellé (lien 1 h)
`signers`requis	object[]
`id`requis	uuid
`email`requis	string
`name`requis	string
`order`requis	integer
`role`requis	"signer" \| "agent"
`status`requis	"pending" \| "notified" \| "signed"
`signed_at`requis	date-time \| null
`sign_url`requis	string \| null	URL personnelle de signature (marque blanche : à injecter dans votre produit)
`signature`	object	Présent en signature avancée et cachet d’organisation
`level`requis	"advanced" \| "organization_seal"
`identity_id`requis	uuid \| null
`authentication`requis	string[]
`authentication_used`requis	string[]
`identity_confirmed_at`requis	date-time \| null
`certificate_serial`requis	string \| null
`certificate_subject`requis	string \| null
`certificate_fingerprint_sha256`requis	string \| null
`applied_at`requis	date-time \| null
`timestamp`requis	object \| null
`issuer`requis	string \| null
`serial`requis	string \| null
`gen_time`requis	string
`qualified`requis	boolean
`provider`requis	string \| null