Référence API

Génère un PDF à partir d'un template DokJet identifié par template_id. Retourne le PDF en flux binaire (sync) ou un task_id (async).

Corps de la requête

Paramètre	Type	Requis	Description
template_id	string	requis	Identifiant du template (ex. `invoices/invoice`). Voir `GET /v1/templates`.
data	object	requis	Variables du template. Les clés inconnues sont ignorées.
options	object	optionnel	Options de rendu. Voir l'objet `options` ci-dessous.
goDokMode	boolean	optionnel	Active l'optimisation IA (+1 Dok). Avec `file` joint : +2 Doks. Défaut : `false`.
async_mode	boolean	optionnel	`false` (défaut) : retourne le PDF. `true` : retourne un `task_id` (HTTP 202).
return_type	string	optionnel	`binary` (défaut) \| `url`. Mode sync uniquement.
webhook_url	string (uri)	optionnel	URL appelée en POST JSON à la fin du job. Mode async uniquement.
metadata	object	optionnel	Objet libre restitué dans `/v1/status` et le webhook.

Objet options

Paramètre	Type	Description
paper	string	A4 \| A3 \| A5 \| Letter \| Legal. Défaut: A4
orientation	string	portrait \| landscape. Défaut: portrait
scale	float	Facteur de zoom. Défaut : 1.0
margin_top / bottom / left / right	float	Marges en pouces.
header_html	string	HTML affiché en en-tête de chaque page (styles inline requis). Gratuit.
footer_html	string	HTML affiché en pied de chaque page. Gratuit.
omit_backgrounds	boolean	Désactive les arrière-plans CSS. Gratuit.
pdf_format	string	PDF/A-1a \| PDF/A-1b \| PDF/A-2b \| PDF/A-3b. Gratuit.
password	string	Chiffrement AES. Gratuit sur plans payants. Interdit en Free (HTTP 403).
compress	boolean	Compression qpdf. +1 Dok.
factur_x	boolean	Force PDF/A-3b et prépare Factur-X. +1 Dok.
embed_files	string[]	URLs de fichiers à embarquer en pièces jointes invisibles. +1 Dok (total).
attachments	string[]	URLs de PDF à fusionner. +1 Dok par fichier.

Exemples de code

curl -X POST https://dokjet.ptitlabo.xyz/v1/generate \
  -H "X-API-Key: dk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "invoices/invoice",
    "data": { "client": "Acme Corp", "total": "€1 240" },
    "options": { "paper": "A4", "compress": true },
    "return_type": "url"
  }'

const res = await fetch('https://dokjet.ptitlabo.xyz/v1/generate', {
  method: 'POST',
  headers: { 'X-API-Key': 'dk_live_••••••••••••',
             'Content-Type': 'application/json' },
  body: JSON.stringify({
    template_id: 'invoices/invoice',
    data: { client: 'Acme Corp', total: '€1 240' },
    options: { paper: 'A4', compress: true },
    return_type: 'url',
  }),
});
const data = await res.json();

$ch = curl_init('https://dokjet.ptitlabo.xyz/v1/generate');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => ['X-API-Key: dk_live_••••••••••••',
                             'Content-Type: application/json'],
  CURLOPT_POSTFIELDS     => json_encode([
    'template_id' => 'invoices/invoice',
    'data'        => ['client' => 'Acme Corp', 'total' => '€1 240'],
    'options'     => ['paper' => 'A4', 'compress' => true],
    'return_type' => 'url',
  ]),
]);
$data = json_decode(curl_exec($ch), true);

import requests

data = requests.post(
    'https://dokjet.ptitlabo.xyz/v1/generate',
    headers={'X-API-Key': 'dk_live_••••••••••••'},
    json={
        'template_id': 'invoices/invoice',
        'data':        {'client': 'Acme Corp', 'total': '€1 240'},
        'options':     {'paper': 'A4', 'compress': True},
        'return_type': 'url',
    }
).json()

Réponse

200 application/pdf — PDF binary

200 application/json — {url, credits_left, response_time_ms}

202 — async: {task_id, status, check_status_url}

400 — missing template_id

401 — invalid API key

402 — insufficient Doks

404 — template not found

Convertit du HTML brut directement en PDF, sans template DokJet. Idéal pour les layouts maîtrisés côté frontend.

goDokMode est true par défaut sur /v1/transform. Passez goDokMode: false pour convertir à 1 Dok.

Corps de la requête

Paramètre	Type	Requis	Description
html	string	requis	Document HTML complet et autonome (`<html>`, `<head>`, `<body>`).
css	string	optionnel	CSS supplémentaire injecté dans le `<head>`.
options	object	optionnel	Mêmes options que `/v1/generate`.
goDokMode	boolean	optionnel	true par défaut sur cet endpoint. Passez `false` pour 1 Dok au lieu de 2.
async_mode	boolean	optionnel	Défaut : `false` (sync).
return_type	string	optionnel	`binary` \| `url`. Mode sync.
webhook_url	string	optionnel	Mode async uniquement.
metadata	object	optionnel	Objet libre restitué dans le webhook.

curl -X POST https://dokjet.ptitlabo.xyz/v1/transform \
  -H "X-API-Key: dk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body><h1>Hello World</h1></body></html>",
    "goDokMode": false,
    "return_type": "url"
  }'

const res = await fetch('https://dokjet.ptitlabo.xyz/v1/transform', {
  method: 'POST',
  headers: { 'X-API-Key': 'dk_live_••••••••••••',
             'Content-Type': 'application/json' },
  body: JSON.stringify({
    html: '<html><body><h1>Hello World</h1></body></html>',
    goDokMode: false,
    return_type: 'url',
  }),
});

$data = json_decode(
  file_get_contents('https://dokjet.ptitlabo.xyz/v1/transform', false,
    stream_context_create(['http' => [
      'method'  => 'POST',
      'header'  => "X-API-Key: dk_live_••••••••••••\r\nContent-Type: application/json\r\n",
      'content' => json_encode([
        'html'        => '<html><body><h1>Hello</h1></body></html>',
        'goDokMode'   => false,
        'return_type' => 'url',
      ]),
    ]])
  ), true
);

import requests

data = requests.post(
    'https://dokjet.ptitlabo.xyz/v1/transform',
    headers={'X-API-Key': 'dk_live_••••••••••••'},
    json={
        'html':        '<html><body><h1>Hello World</h1></body></html>',
        'goDokMode':   False,
        'return_type': 'url',
    }
).json()

Génère un PDF depuis un endpoint Studio pré-configuré identifié par son slug. La configuration de l'endpoint (template, options) s'applique automatiquement. Les valeurs data surchargent les défauts.

Paramètres de chemin

Paramètre	Type	Description
slug	string	Slug de l'endpoint Studio. Voir `GET /v1/endpoints`.

Corps de la requête

Paramètre	Type	Requis	Description
data	object	optionnel	Variables à injecter. Surchargent les valeurs par défaut de l'endpoint.
options	object	optionnel	Surcharge les options de rendu de l'endpoint.
goDokMode	boolean	optionnel	Surcharge le paramètre goDokMode de l'endpoint. +1 Dok.
async_mode	boolean	optionnel	Défaut : false.
webhook_url / return_type / metadata	—	optionnel	Identiques à /v1/generate.

curl -X POST https://dokjet.ptitlabo.xyz/v1/studio/mes-factures \
  -H "X-API-Key: dk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "client": "Acme Corp", "total": "€1 240" } }'

const res = await fetch('https://dokjet.ptitlabo.xyz/v1/studio/mes-factures', {
  method: 'POST',
  headers: { 'X-API-Key': 'dk_live_••••••••••••',
             'Content-Type': 'application/json' },
  body: JSON.stringify({ data: { client: 'Acme Corp', total: '€1 240' }}),
});

$ch = curl_init('https://dokjet.ptitlabo.xyz/v1/studio/mes-factures');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => ['X-API-Key: dk_live_••••••••••••',
                             'Content-Type: application/json'],
  CURLOPT_POSTFIELDS     => json_encode([
    'data' => ['client' => 'Acme Corp', 'total' => '€1 240'],
  ]),
]);

import requests

data = requests.post(
    'https://dokjet.ptitlabo.xyz/v1/studio/mes-factures',
    headers={'X-API-Key': 'dk_live_••••••••••••'},
    json={'data': {'client': 'Acme Corp', 'total': '€1 240'}}
).json()

Soumet plusieurs jobs PDF en une seule requête. Traitement exclusivement asynchrone.

Le mode batch est exclusivement asynchrone — async_mode doit être true.

Les limites d'entrées par batch dépendent de votre plan : Free = 3, Pro/Max = 10 entrées.

Corps de la requête

Paramètre	Type	Requis	Description
endpoint	string	requis	`generate` \| `transform` \| `{slug}`. Type d'endpoint appliqué à toutes les entries.
entries	array	requis	Tableau de payloads. Chaque entry suit le schéma de l'endpoint correspondant. Max 3 (Free) / 10 (Pro+).
async_mode	boolean	optionnel	Doit être `true` ou omis. Passer `false` → HTTP 400.
webhook_url	string	optionnel	Webhook par défaut pour toutes les entries (surchargeable par entry).

Payload webhook (par job)

POST {webhook_url}

{
  "task_id":      "job_a1b2c3d4e5f6g7h8",
  "status":       "completed",
  "download_url": "https://dokjet.ptitlabo.xyz/upload/.../doc.pdf",
  "metadata":     {}
}

curl -X POST https://dokjet.ptitlabo.xyz/v1/batch \
  -H "X-API-Key: dk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "generate",
    "webhook_url": "https://your-app.com/webhooks/dokjet",
    "entries": [
      { "template_id": "invoices/invoice", "data": { "client": "Acme" } },
      { "template_id": "invoices/invoice", "data": { "client": "Beta Corp" } }
    ]
  }'

const res = await fetch('https://dokjet.ptitlabo.xyz/v1/batch', {
  method: 'POST',
  headers: { 'X-API-Key': 'dk_live_••••••••••••',
             'Content-Type': 'application/json' },
  body: JSON.stringify({
    endpoint:    'generate',
    webhook_url: 'https://your-app.com/webhooks/dokjet',
    entries: [
      { template_id: 'invoices/invoice', data: { client: 'Acme' }},
      { template_id: 'invoices/invoice', data: { client: 'Beta Corp' }},
    ],
  }),
});
const { batch_id, tasks } = await res.json();

// Using Guzzle
$response = $client->post('https://dokjet.ptitlabo.xyz/v1/batch', [
  'headers' => ['X-API-Key' => 'dk_live_••••••••••••'],
  'json'    => [
    'endpoint'    => 'generate',
    'webhook_url' => 'https://your-app.com/webhooks/dokjet',
    'entries'     => [
      ['template_id' => 'invoices/invoice', 'data' => ['client' => 'Acme']],
      ['template_id' => 'invoices/invoice', 'data' => ['client' => 'Beta Corp']],
    ],
  ],
]);

import requests

result = requests.post(
    'https://dokjet.ptitlabo.xyz/v1/batch',
    headers={'X-API-Key': 'dk_live_••••••••••••'},
    json={
        'endpoint':    'generate',
        'webhook_url': 'https://your-app.com/webhooks/dokjet',
        'entries': [
            {'template_id': 'invoices/invoice', 'data': {'client': 'Acme'}},
            {'template_id': 'invoices/invoice', 'data': {'client': 'Beta Corp'}},
        ],
    }
).json()

Réponse

202 — {batch_id, count, tasks[]}

400 — async_mode: false

402 — insufficient Doks

422 — plan limit exceeded

Retourne l'état d'un job créé en mode async. Lifecycle : pending → processing → completed | failed.

Interrogez toutes les 2–5 secondes. Privilégiez les webhooks en production.

Paramètres de chemin

Paramètre	Type	Description
task_id	string	`task_id` retourné par un endpoint de génération en mode async.

curl https://dokjet.ptitlabo.xyz/v1/status/job_a1b2c3d4e5f6g7h8 \
  -H "X-API-Key: dk_live_••••••••••••"
→  200 OK
{
  "task_id":      "job_a1b2c3d4e5f6g7h8",
  "status":       "completed",
  "download_url": "https://dokjet.ptitlabo.xyz/upload/.../doc.pdf"
}

const poll = async (taskId) => {
  let status;
  do {
    await new Promise(r => setTimeout(r, 3000));
    const res = await fetch(`https://dokjet.ptitlabo.xyz/v1/status/${taskId}`, {
      headers: { 'X-API-Key': 'dk_live_••••••••••••' },
    });
    ({ status } = await res.json());
  } while (status === 'pending' || status === 'processing');
  return status;
};

$status = 'pending';
while (in_array($status, ['pending', 'processing'])) {
  sleep(3);
  $r = json_decode(file_get_contents(
    'https://dokjet.ptitlabo.xyz/v1/status/' . $taskId,
    false,
    stream_context_create(['http' => [
      'header' => "X-API-Key: dk_live_••••••••••••\r\n"
    ]])), true);
  $status = $r['status'];
}

import time, requests

def poll(task_id):
    while True:
        time.sleep(3)
        r = requests.get(
            f'https://dokjet.ptitlabo.xyz/v1/status/{task_id}',
            headers={'X-API-Key': 'dk_live_••••••••••••'}
        ).json()
        if r['status'] not in ('pending', 'processing'):
            return r

Retourne le catalogue complet des templates DokJet utilisables dans POST /v1/generate via leur template_id.

curl https://dokjet.ptitlabo.xyz/v1/templates \
  -H "X-API-Key: dk_live_••••••••••••"
→  [{ "id": "invoices/invoice", "label": "Invoice", "category": "invoices", "orientation": "portrait" }, ...]

const templates = await fetch('https://dokjet.ptitlabo.xyz/v1/templates', {
  headers: { 'X-API-Key': 'dk_live_••••••••••••' },
}).then(r => r.json());

$templates = json_decode(file_get_contents(
  'https://dokjet.ptitlabo.xyz/v1/templates', false,
  stream_context_create(['http' => [
    'header' => "X-API-Key: dk_live_••••••••••••\r\n"
  ]])
), true);

templates = requests.get(
    'https://dokjet.ptitlabo.xyz/v1/templates',
    headers={'X-API-Key': 'dk_live_••••••••••••'}
).json()

Retourne tous les endpoints Studio de votre workspace. Utilisez leur slug avec POST /v1/studio/{slug}.

GET /v1/endpoints

→  200 OK
[{
  "name":      "Mes factures",
  "slug":      "mes-factures",
  "type":      "template",
  "express":   false,
  "variables": ["client", "total", "invoice_number"]
}]

Retourne le solde de Doks de votre compte et le nom du plan actif.

GET /v1/credits

curl https://dokjet.ptitlabo.xyz/v1/credits \
  -H "X-API-Key: dk_live_••••••••••••"
→  200 OK
{
  "credits_left": 42,
  "plan":         "Free"
}