Référence API
Liste complète des 24 endpoints REST v1, conventions et lien vers la spec OpenAPI 3.1.
L'API Inkr expose 24 endpoints REST sous https://api.getinkr.eu/v1. Cette page les liste tous avec un lien vers la doc détaillée.
Conventions globales
| Convention | Valeur |
|---|---|
| Base URL | https://api.getinkr.eu/v1 |
| Auth | Authorization: Bearer sk_test_xxx ou sk_live_xxx sur tous les endpoints, health inclus |
| Idempotency | Header Idempotency-Key obligatoire sur les 5 POST de création de document |
| Pagination | Cursor via ?cursor=<opaque>&limit=<n> (défaut 20, max 100) |
| Réponse paginée | { "data": [...], "has_more": bool, "next_cursor": string | null } à la racine |
| Format IDs | Strings préfixées : tpl_, sub_, sbm_, evt_, whk_, dlv_ + 24 caractères base62 |
| Erreurs | Enveloppe normée { "error": { "type", "code", "message" } } |
| Timestamps | ISO 8601 UTC partout |
| Rate limit | 100 rpm (sk_test) / 1000 rpm (sk_live), headers X-RateLimit-* sur chaque réponse |
Endpoints
Meta
| Méthode | Path | Idempotency | Description |
|---|---|---|---|
GET | /v1/health | non | Valide la clé et renvoie son environnement. Authentifié. |
Templates
PDF figés réutilisables avec leurs champs positionnés. Documentation détaillée.
| Méthode | Path | Idempotency | Description |
|---|---|---|---|
GET | /v1/templates | non | Lister les templates (filtres status, created_via). |
POST | /v1/templates | oui | Créer un template depuis un PDF + champs. |
GET | /v1/templates/{id} | non | Récupérer un template et ses champs. |
DELETE | /v1/templates/{id} | non | Archiver un template. Renvoie 200. |
Submissions
Instances de signature envoyées à 1 ou N signataires. Documentation détaillée.
| Méthode | Path | Idempotency | Description |
|---|---|---|---|
GET | /v1/submissions | non | Lister les submissions (filtres status, template_id). |
POST | /v1/submissions | oui | Créer une submission depuis un template. |
POST | /v1/submissions/from_pdf | oui | Créer depuis un PDF inline avec coordonnées explicites. |
POST | /v1/submissions/from_html | oui | Créer depuis un HTML inline à variables tag. |
POST | /v1/submissions/from_docx | oui | Créer depuis un DOCX inline à variables tag. |
GET | /v1/submissions/{id} | non | Récupérer une submission et ses submitters. |
DELETE | /v1/submissions/{id} | non | Annuler une submission. Renvoie 200. |
GET | /v1/submissions/{id}/documents | non | URLs signées du PDF original et du PDF signé (TTL 1h). |
GET | /v1/submissions/{id}/audit_log | non | Télécharger l'audit PDF eIDAS. Réponse binaire. |
Submitters
Signataires individuels d'une submission. Documentation détaillée.
| Méthode | Path | Idempotency | Description |
|---|---|---|---|
GET | /v1/submitters | non | Lister les submitters (filtres status, submission_id, email). |
GET | /v1/submitters/{id} | non | Récupérer un submitter avec ses values signées. |
PATCH | /v1/submitters/{id} | non | Mettre à jour email, phone ou name (status pending ou opened). |
POST | /v1/submitters/{id}/embed_token | non | Régénérer un token d'embed (TTL custom). |
Webhooks
Events submission envoyés en push HTTP signé HMAC. Documentation détaillée.
| Méthode | Path | Idempotency | Description |
|---|---|---|---|
GET | /v1/webhook_endpoints | non | Lister les endpoints webhook configurés. |
POST | /v1/webhook_endpoints | non | Créer un endpoint. Révèle le secret une seule fois. |
GET | /v1/webhook_endpoints/{id} | non | Détail et état de santé de l'endpoint. |
DELETE | /v1/webhook_endpoints/{id} | non | Désactiver un endpoint. Renvoie 200. |
POST | /v1/webhook_endpoints/{id}/test | non | Envoyer un event webhook.test et récupérer la réponse brute. |
Events
| Méthode | Path | Idempotency | Description |
|---|---|---|---|
GET | /v1/events | non | Journal des transitions (filtres type, submission_id). Seule source pour les events de granularité submitter. |
Codes HTTP
| Code | Sens |
|---|---|
200 | Succès. Les DELETE renvoient 200 avec un objet de confirmation, pas 204. |
201 | Ressource créée. |
400 | JSON invalide, ID d'URL mal formé ou Idempotency-Key manquante. |
401 | Clé API manquante, invalide ou révoquée. |
404 | Ressource inexistante ou hors scope. |
409 | Conflit d'état : objet déjà finalisé, slug déjà pris. |
422 | Schéma Zod refusé ou règle métier violée. |
429 | Rate limit dépassé (cf. header Retry-After). |
500 | Erreur Inkr ou upstream (retry recommandé). |
Détail complet des error.code dans Erreurs et retries.
Spec OpenAPI 3.1
curl https://api.getinkr.eu/openapi.yaml -o inkr-openapi.yamlCompatible OpenAPI Generator, Speakeasy, Fern et Stainless pour générer un SDK dans 25+ langages.
SDKs et outils communautaires
Aucun SDK officiel maintenu par Inkr en MVP. Inkr publie la spec OpenAPI 3.1 stable et recommande de générer votre client via :
OpenAPI Generator
Générateur multi-langage open source (Java, Python, TypeScript, Go, etc.).
Speakeasy
SDK générés type-safe avec retry, idempotency, pagination intégrés.
Fern
Génération SDK + doc + Postman depuis un schema unique.
Stainless
SDKs idiomatiques générés par Stripe / Anthropic / Cloudflare.
Versioning
L'API est en version v1. Les changements breaking déclenchent une nouvelle version (v2, v3). Les changements rétrocompatibles (nouveaux endpoints, nouveaux champs optionnels) restent sur v1.
Toute deprecation est annoncée 6 mois à l'avance via le header HTTP Sunset sur les endpoints concernés + email aux développeurs ayant utilisé une clé sk_live dans les 30 derniers jours.
Écrivez une intégration tolérante : ignorez les champs inconnus dans les réponses, traitez error.type et error.code comme des énumérations ouvertes, ne construisez jamais un ID vous-même et ne décodez pas les curseurs de pagination.