Référence API#

Base : https://dokkraft.blocsland.com/api/v1 — authentification Authorization: Bearer dfk_… sur tous les endpoints. Les réponses sont JSON (Content-Type: application/json), sauf les PDF en flux.

Les identifiants utilisés dans les URLs sont les public_id (template, dossier), pas les identifiants internes.

Idempotence des créations#

Les quatre POST de création (documents unitaires et lots) acceptent un en-tête Idempotency-Key — une valeur unique par intention, par exemple un UUID généré chez vous. Si un timeout réseau fait rejouer le POST avec la même clé et le même payload, vous recevez la réponse du premier appel (Idempotent-Replayed: true) au lieu d'un doublon numéroté — la mémoire vit 24 h. Avec download=true, le replay re-sert le PDF du document créé par le premier appel.

Réponse	Signification
Réponse du 1er appel + Idempotent-Replayed: true	Intentions identiques — aucun doublon créé
422 idempotency_key_reused	Même clé avec un payload différent — une clé porte une seule intention, générez-en une nouvelle
409 idempotency_in_progress	Un appel avec cette clé est encore en cours — réessayez dans un instant

POST /templates/{public_id}/pdf#

Génère un PDF sans rien enregistrer : le corps du template est rendu avec les variables passées.

Paramètre	Type	Description
data	object	Valeurs des variables ({"client.nom": "ACME"})
references	object	Fiches liées par identifiant ({"client": "42"}) — résolues comme en mode document
tableData	array	Lignes des tableaux
download	boolean	true → pièce jointe, sinon flux inline

Réponse : PDF (application/pdf).

POST /templates/{public_id}/documents#

Crée un document numéroté et archivé (racine « Non classés », ou dossier folder), avec son PDF.

Paramètre	Type	Description
name	string	Nom du document (défaut Document API)
date	string	Date d'émission (Y-m-d)
folder	string	public_id du dossier d'archivage
data, references, tableData	object / array	Variables, registres, lignes de tableaux
download	boolean	Renvoie le PDF au lieu du JSON
async	boolean	true → le PDF part sur la file d'attente : la réponse 201 arrive dès la numérotation (pdfStatus: "queued"), sondez GET /documents/{id} puis récupérez le PDF — ou déclarez un webhook pour être prévenu. Sans async, le rendu est synchrone (~2 s en médian, la requête attend le PDF)

Réponse 201 : fiche du document (contrat intégrateur, id = public_id — enchaînable avec GET /documents/{id}/pdf).

{
  "id": "01HXXXX-public-id",
  "name": "Facture ACME",
  "numero": "FAC-2026-0042",
  "status": "emis",
  "templateId": "tmpl_01HYYYY",
  "folderId": null,
  "date": "2026-09-22",
  "amount": 1250.0,
  "pdfStatus": "ready",
  "pdfUrl": "/api/v1/documents/01HXXXX-public-id/pdf",
  "emittedAt": "2026-09-22T10:15:00+00:00"
}

Idempotence : en-tête Idempotency-Key accepté — voir la section dédiée en tête de page.

Erreurs : 422 async combiné à download (incompatibles — l'un répond sans le PDF, l'autre attend le rendu synchrone), 422 champs obligatoires manquants (format {message, errors} — voir Erreurs), 503 pdf_busy quand le pool de rendu synchrone est saturé (en-tête Retry-After: 5 — relancez ou passez en async=true, qui n'occupe pas de créneau).

Champs obligatoires du template : les variables et suivis marqués required dans le schéma doivent être résolus non vides, sinon 422 — mais une cascade dossier/espace, un défaut du schéma, une formule ou la date dédiée satisfont l'exigence : data n'est nécessaire que pour ce qui n'est pas pré-rempli (clés d'erreur détaillées dans Erreurs). Cette règle vaut pour les POST unitaires et pour chaque item de lot.

POST /folders/{public_id}/documents#

Identique à l'endpoint précédent, mais le dossier est le point d'entrée : son template (lié localement ou hérité d'un ancêtre), sa cascade de registres et ses variables s'appliquent automatiquement.

Paramètre	Type	Description
name, date	string	Comme ci-dessus
data, references, tableData	object / array	Surcharges de la cascade
download	boolean	Renvoie le PDF au lieu du JSON
async	boolean	Comme ci-dessus

Erreurs : 404 dossier inconnu (ou hors de l'espace de la clé), 422 aucun template lié ou async combiné à download, 422 champs obligatoires manquants et 503 pdf_busy — mêmes contrats que l'endpoint précédent (la cascade du dossier peut à elle seule satisfaire les champs required).

POST /templates/{public_id}/documents/batch#

Génération en lot (asynchrone). Crée plusieurs documents d'un coup et répond 202 immédiatement : les documents sont émis hors requête, leur PDF rendu par la file d'attente. L'avancement se suit par GET /batches/{batch_id} — c'est la voie à privilégier dès qu'il s'agit de créer plus de quelques documents.

Paramètre	Type	Description
items	array (1–50)	Un objet par document : name, date, folder, data, references, tableData — les mêmes champs que l'endpoint unitaire
folder	string	public_id du dossier d'archivage par défaut (chaque item peut le surcharger)

Réponse 202 : la ressource batch.

{
  "id": "4e7c9a52-…",
  "status": "pending",
  "total": 2,
  "counts": { "queued": 2, "emitted": 0, "failed": 0 },
  "items": [
    { "position": 0, "status": "queued", "document": null }
  ]
}

Limites : 50 items par lot, 2 lots actifs (pending/processing) par espace de travail, 10 lots/minute. Le quota mensuel documents est décompté par document réellement émis — le refus rapide 429 quota_exceeded indique remaining et required quand il reste moins de documents que d'items demandés.

Erreurs : 422 validation (items mal formés, dossier inconnu), 429 batch_limit_reached (trop de lots actifs) ou quota_exceeded (pré-vol du quota documents).

POST /folders/{public_id}/documents/batch#

Identique au précédent, mais le dossier est le point d'entrée : son template (lié localement ou hérité d'un ancêtre) et sa cascade s'appliquent à tous les items.

GET /batches/{batch_id}#

État d'un lot (polling de l'intégrateur). Chaque appel compte dans le quota api_calls — un sondage toutes les 2-3 s est largement suffisant. Un lot actif sans mise à jour depuis 15 min (job perdu côté serveur) est automatiquement repris : continuez simplement de sonder. Le webhook batch.completed vous évite ce sondage — voir Webhooks.

Réponse 200 : la ressource batch complète. status vaut pending → processing → completed (tout est émis), partial (au moins un échec) ou failed. Chaque item porte son document (numéro, pdfStatus, pdfUrl) dès qu'il est émis ; l'échec d'un item ne bloque jamais les autres — son error explique pourquoi.

GET /documents/{public_id}#

Fiche d'un document créé par l'API — le même format que la réponse du POST unitaire (id, numero, pdfStatus, pdfUrl, …). 404 si le document est étranger à l'espace de la clé.

GET /documents/{public_id}/pdf#

Le PDF du document, en flux (?download=true pour une pièce jointe). Complément du mode batch : le fichier n'existe qu'après le rendu en file.

Réponse	Signification
200	Le PDF (flux application/pdf)
202 + Retry-After: 5	Rendu en cours — sondez à nouveau (ou recevez un webhook dès qu'il est prêt)
409 pdf_draft / pdf_failed / pdf_missing	Brouillon (pas de PDF), rendu échoué ou fichier indisponible
410 pdf_expired	PDF purgé par la rétention du plan (régénération possible depuis l'application)

POST /embed/sessions#

Crée une session de studio en iframe : échange la clé API contre une URL signée à charger dans votre produit.

Paramètre	Type	Description
template_id	string	public_id du template à éditer
allowed_domains	array	Origines autorisées (1 à 10) — https://app.exemple.com
ttl_minutes	integer	Durée de vie (5 à 1440, défaut 120)
permissions	object	variables (frozen|editable), ai, save, export_pdf

Réponse 201 : { "url", "token", "expires_at", "permissions" }.

DELETE /embed/sessions/{token}#

Révoque une session d'embed : l'iframe cesse de fonctionner immédiatement (clé fugée, fin de contrat…). Répond 200 {"revoked": true} même pour un jeton inconnu ou déjà révoqué — même réponse dans tous les cas, pas d'énumération possible.

GET /templates/{public_id}/schema#

Sans authentification. Schéma de variables du template (champs de génération, registres référencés) — pratique pour construire un formulaire dynamique côté intégrateur.