Submissions
Envoyer un document à signer, suivre son statut, récupérer le PDF final et l'audit eIDAS.
Une submission est une instance concrète de signature : un PDF + une liste de signataires + un statut.
Depuis un template figé
POST /v1/submissions avec un template_id pré-créé. Idéal pour des PDF identiques réutilisés.
Depuis un PDF inline
POST /v1/submissions/from_pdf avec un PDF base64 ou URL. Idéal pour des PDF générés dynamiquement.
Depuis un template
curl -X POST https://api.getinkr.eu/v1/submissions \
-H "Authorization: Bearer $INKR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"template_id": "tpl_01J5HZ...",
"signing_order": "preserved",
"expires_at": "2026-06-15T23:59:59Z",
"redirect_url": "https://app.example.com/contracts/42/signed",
"metadata": { "internal_contract_id": "k_42" },
"submitters": [
{
"role": "Partenaire",
"email": "alice@example.com",
"name": "Alice Dupont",
"external_id": "partner_42",
"metadata": { "department": "sales" },
"fields": { "raison_sociale": "ACME SARL" }
}
],
"send_email": true
}'signing_order : preserved (les submitters signent dans l'ordre de l'array, le 2e ne reçoit son mail qu'après signature du 1er) ou random (tous reçoivent leur mail en même temps).
Depuis un PDF inline
Utilise cette variante si ton PDF est généré dynamiquement à chaque appel (contrats, factures, émargements avec lignes variables). Inkr crée un template interne archivé immédiatement et fait pointer la submission dessus.
curl -X POST https://api.getinkr.eu/v1/submissions/from_pdf \
-H "Authorization: Bearer $INKR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"documents": [
{ "name": "Émargement S20", "pdf_base64": "JVBERi0xLjQK..." }
],
"submitters": [
{
"role": "Employé",
"email": "bob@example.com",
"fields": [
{
"name": "signature_employe",
"type": "signature",
"required": true,
"areas": [{ "page": 0, "x": 0.5, "y": 0.9, "w": 0.3, "h": 0.05 }]
}
]
}
],
"send_email": true
}'Le PDF peut faire jusqu'à 10 MiB en base64 (overhead 33% inclus). Pour des PDF plus gros, passe par pdf_url (URL HTTPS publique) à la place.
Statuts
Une submission passe par 8 statuts possibles :
| Status | Sens |
|---|---|
created | Créée mais pas encore envoyée (rare si send_email: true). |
sent | Email envoyé au premier submitter, en attente de signature. |
viewed | Au moins un submitter a ouvert le signing URL. |
partially_signed | Au moins un mais pas tous les submitters ont signé. |
completed | Tous les submitters ont signé. PDF final disponible. |
declined | Un submitter a refusé de signer. |
expired | expires_at dépassé. |
cancelled | Annulée via DELETE. |
Récupérer un PDF signé
curl https://api.getinkr.eu/v1/submissions/sub_01J5HZ.../documents \
-H "Authorization: Bearer $INKR_API_KEY"Retourne une URL Supabase signée TTL 1h pour télécharger le PDF final avec les signatures embedded et le footer eIDAS SES.
Audit log eIDAS
Disponible uniquement quand status: "completed" :
curl https://api.getinkr.eu/v1/submissions/sub_01J5HZ.../audit_log \
-H "Authorization: Bearer $INKR_API_KEY" \
-o audit.pdfLe PDF contient le détail de tous les événements horodatés : envoi, ouverture, IP, user-agent, signature, hash SHA-256 final.
Lister les submissions
curl "https://api.getinkr.eu/v1/submissions?status=completed&limit=50&cursor=..." \
-H "Authorization: Bearer $INKR_API_KEY"Filtres supportés : status, template_id, created_after, created_before. Cursor pagination.
Submitters (endpoints dédiés)
Pour interroger les submitters individuellement (utile pour matcher avec ta DB via external_id) :
# Lister tous les submitters d'un user
curl "https://api.getinkr.eu/v1/submitters?status=signed&limit=50" \
-H "Authorization: Bearer $INKR_API_KEY"
# Détail d'un submitter (avec values signées)
curl https://api.getinkr.eu/v1/submitters/sbm_01J5HZ... \
-H "Authorization: Bearer $INKR_API_KEY"
# Mettre à jour email/phone/name d'un submitter en pending
curl -X PATCH https://api.getinkr.eu/v1/submitters/sbm_01J5HZ... \
-H "Authorization: Bearer $INKR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "email": "alice.new@example.com" }'PATCH submitter n'est autorisé que si status est pending ou opened. Si l'email change et que send_email était actif, un nouveau mail part automatiquement vers la nouvelle adresse.