Comment générer un document avec l’API PDFMonkey ?

Envoyez une requête POST à /api/v1/documents avec l’ID du modèle et les données dynamiques. Définissez le statut sur "pending" pour lancer la génération immédiatement. Interrogez ensuite le statut du document ou utilisez les webhooks.

Quelle différence entre Document et DocumentCard dans PDFMonkey ?

Un Document est l’objet complet incluant payload, generation_logs et checksum. Un DocumentCard est une version allégée sans ces champs mais avec document_template_identifier en plus.

PDFMonkey prend-il en charge la génération synchrone ?

Oui. Envoyez un POST à /api/v1/documents/sync pour créer un document et attendre le résultat en une seule requête. L’endpoint a un timeout de 6 minutes et renvoie un DocumentCard.

Combien de temps une URL de téléchargement PDFMonkey est-elle valide ?

Les URL de téléchargement sont des liens S3 signés temporaires valides 1 heure. Après expiration, récupérez le document à nouveau pour obtenir une URL fraîche.

API Documents : créer, lister et gérer les documents générés

Référence complète de l’API pour créer, récupérer, mettre à jour et supprimer des documents dans PDFMonkey.

Démarrage rapide

La génération est asynchrone : vous créez un document, puis vous vérifiez son statut jusqu’à ce qu’il soit prêt.

# 1. Créer un document et le mettre en file d’attente pour génération
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR_TEMPLATE_ID",
      "status": "pending",
      "payload": { "name": "Jane Doe" }
    }
  }'
# Retourne un document avec "status": "pending" et "download_url": null

# 2. Vérifier le statut du document jusqu’à ce qu’il atteigne "success"
curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID
# Lorsque le statut est "success", lire la download_url dans la réponse

Passer "status": "pending" met le document en file d’attente pour une génération immédiate. Le fichier n’est pas encore prêt à ce stade — vous devez interroger le document ou configurer un webhook pour savoir quand il est terminé. Lorsque le statut atteint success, le champ download_url contient un lien signé vers le fichier généré.

Lisez la suite pour tous les détails, y compris l’endpoint synchrone qui attend le résultat en une seule requête.

Authentification

Toutes les requêtes nécessitent un token Bearer dans l’en-tête Authorization :

Authorization: Bearer YOUR_SECRET_KEY

Consultez Authentification pour savoir comment trouver votre clé API et gérer vos tokens d’accès.

Créer un document

POST /api/v1/documents

Crée un nouveau document. Passez status à "pending" pour lancer la génération immédiatement, ou omettez-le (valeur par défaut : "draft") pour générer plus tard.

Paramètres

Tous les paramètres sont imbriqués sous une clé document.

Nom	Type	Requis	Description
`document_template_id`	String (UUID)	Oui	ID du modèle à utiliser pour la génération.
`payload`	Object ou String	Non	Les données dynamiques utilisées pour construire le document. Doit être un objet JSON (pas un tableau). Peut être transmis en tant qu’objet JSON ou chaîne JSON.
`meta`	Object ou String	Non	Métadonnées à attacher au document. Supporte des clés spéciales comme `_filename`. Doit être un objet JSON. 200 Ko maximum.
`status`	String	Non	`"draft"` (par défaut) ou `"pending"`. Passez à `"pending"` pour déclencher la génération à la création.

Passez "status": "pending" dans votre requête de création pour générer le document en une seule étape. Sans cela, le document est créé en brouillon et vous devrez le mettre à jour ultérieurement pour déclencher la génération.

Requête

curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "status": "pending",
      "payload": {
        "clientName": "Peter Parker",
        "orderDate": "2050-03-14",
        "products": [
          { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
          { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
        ]
      },
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      }
    }
  }'

document = Pdfmonkey::Document.generate(
  document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  payload: {
    clientName: 'Peter Parker',
    orderDate: '2050-03-14',
    products: [
      { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
      { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 }
    ]
  },
  meta: {
    _filename: '2050-03-14 Peter Parker.pdf',
    clientRef: 'spidey-616'
  }
)

document.status # => 'pending'

const response = await fetch('https://api.pdfmonkey.io/api/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    document: {
      document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
      status: 'pending',
      payload: {
        clientName: 'Peter Parker',
        orderDate: '2050-03-14',
        products: [
          { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
          { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 },
        ],
      },
      meta: {
        _filename: '2050-03-14 Peter Parker.pdf',
        clientRef: 'spidey-616',
      },
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/documents',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'document_template_id': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status': 'pending',
            'payload': {
                'clientName': 'Peter Parker',
                'orderDate': '2050-03-14',
                'products': [
                    {'name': 'Spider silk', 'quantity': 12, 'unitPrice': 123.50},
                    {'name': 'Spandex fabric', 'quantity': 2, 'unitPrice': 28.90},
                ],
            },
            'meta': {
                '_filename': '2050-03-14 Peter Parker.pdf',
                'clientRef': 'spidey-616',
            },
        },
    },
)

print(response.json())

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document' => [
            'document_template_id' => '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status' => 'pending',
            'payload' => [
                'clientName' => 'Peter Parker',
                'orderDate' => '2050-03-14',
                'products' => [
                    ['name' => 'Spider silk', 'quantity' => 12, 'unitPrice' => 123.50],
                    ['name' => 'Spandex fabric', 'quantity' => 2, 'unitPrice' => 28.90],
                ],
            ],
            'meta' => [
                '_filename' => '2050-03-14 Peter Parker.pdf',
                'clientRef' => 'spidey-616',
            ],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Réponse

{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "checksum": "c230530f6f0aa32900af0924cf228e5c",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "download_url": null,
    "failure_cause": null,
    "filename": null,
    "generation_logs": [],
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "payload": {
      "clientName": "Peter Parker",
      "orderDate": "2050-03-14",
      "products": [
        { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
        { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
      ]
    },
    "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
    "public_share_link": null,
    "status": "pending",
    "updated_at": "2050-03-13T12:34:56.181+02:00"
  }
}

Erreurs de validation

Si des champs requis sont manquants ou invalides, l’API retourne une erreur 422 Unprocessable Entity :

{
  "errors": {
    "document_template_id": ["can’t be blank"]
  }
}

Génération synchrone

POST /api/v1/documents/sync

Un raccourci qui crée un document et attend la fin de la génération côté serveur, pour obtenir le résultat en une seule requête. La réponse est un DocumentCard (pas un Document). Pour un guide pas-à-pas, consultez Générer des documents avec l’API.

Cet endpoint accepte les mêmes paramètres que Créer un document. Vous devez passer "status": "pending" pour que la génération démarre.

Quand utiliser sync vs async

	Async	Sync
Réponse	Retourne immédiatement	Attend la fin de la génération
Obtenir le résultat	Polling ou webhooks	Inclus dans la réponse
Objet retourné	Document	DocumentCard
Adapté au volume	Oui	Non — une requête ouverte par document
Timeout	Aucun	6 minutes
Idéal pour	Pipelines de production, génération par lots	Faible volume ou cas d’usage interactifs

L’endpoint sync attend jusqu’à 6 minutes la fin de la génération. Pour les pipelines de production ou la génération par lots, préférez la génération asynchrone avec les webhooks.

Requête

curl https://api.pdfmonkey.io/api/v1/documents/sync \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "status": "pending",
      "payload": {
        "clientName": "Peter Parker",
        "orderDate": "2050-03-14",
        "products": [
          { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
          { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
        ]
      },
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      }
    }
  }'

document = Pdfmonkey::Document.generate!(
  document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  payload: {
    clientName: 'Peter Parker',
    orderDate: '2050-03-14',
    products: [
      { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
      { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 }
    ]
  },
  meta: {
    _filename: '2050-03-14 Peter Parker.pdf',
    clientRef: 'spidey-616'
  }
)

document.status       # => 'success'
document.download_url # => 'https://…'

const response = await fetch('https://api.pdfmonkey.io/api/v1/documents/sync', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    document: {
      document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
      status: 'pending',
      payload: {
        clientName: 'Peter Parker',
        orderDate: '2050-03-14',
        products: [
          { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
          { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 },
        ],
      },
      meta: {
        _filename: '2050-03-14 Peter Parker.pdf',
        clientRef: 'spidey-616',
      },
    },
  }),
});

const data = await response.json();
console.log(data.document_card.download_url);

import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/documents/sync',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'document_template_id': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status': 'pending',
            'payload': {
                'clientName': 'Peter Parker',
                'orderDate': '2050-03-14',
                'products': [
                    {'name': 'Spider silk', 'quantity': 12, 'unitPrice': 123.50},
                    {'name': 'Spandex fabric', 'quantity': 2, 'unitPrice': 28.90},
                ],
            },
            'meta': {
                '_filename': '2050-03-14 Peter Parker.pdf',
                'clientRef': 'spidey-616',
            },
        },
    },
    timeout=400,
)

data = response.json()
print(data['document_card']['download_url'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/sync');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_TIMEOUT => 400,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document' => [
            'document_template_id' => '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status' => 'pending',
            'payload' => [
                'clientName' => 'Peter Parker',
                'orderDate' => '2050-03-14',
                'products' => [
                    ['name' => 'Spider silk', 'quantity' => 12, 'unitPrice' => 123.50],
                    ['name' => 'Spandex fabric', 'quantity' => 2, 'unitPrice' => 28.90],
                ],
            ],
            'meta' => [
                '_filename' => '2050-03-14 Peter Parker.pdf',
                'clientRef' => 'spidey-616',
            ],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['document_card']['download_url'];

Réponse

L’endpoint sync retourne un DocumentCard, pas un Document. Le résultat est imbriqué sous document_card et n’inclut ni payload ni generation_logs.

{
  "document_card": {
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}

L’objet Document

L’objet Document est la représentation complète d’un document généré, incluant son payload et ses logs de génération.

{
  "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
  "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
  "checksum": "c230530f6f0aa32900af0924cf228e5c",
  "created_at": "2050-03-13T12:34:56.181+02:00",
  "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
  "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "failure_cause": null,
  "filename": "2050-03-14 Peter Parker.pdf",
  "generation_logs": [
    {
      "type": "info",
      "message": "Starting PDF generation.",
      "timestamp": "Thu, 13 Mar 2050 10:34:57 GMT"
    },
    {
      "type": "info",
      "message": "Generation took 1617ms to load and render.",
      "timestamp": "Thu, 13 Mar 2050 10:34:58 GMT"
    },
    {
      "type": "info",
      "message": "Content size is 96302.",
      "timestamp": "Thu, 13 Mar 2050 10:34:59 GMT"
    }
  ],
  "meta": {
    "_filename": "2050-03-14 Peter Parker.pdf",
    "clientRef": "spidey-616"
  },
  "output_type": "pdf",
  "payload": {
    "clientName": "Peter Parker",
    "orderDate": "2050-03-14",
    "products": [
      { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
      { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
    ]
  },
  "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
  "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/2050-03-14-peter-parker.pdf",
  "status": "success",
  "updated_at": "2050-03-13T12:34:59.412+02:00"
}

Attributs

Nom	Type	Description
`id`	String (UUID)	Identifiant unique du document.
`app_id`	String (UUID)	Identifiant unique du workspace du document.
`checksum`	String	Checksum interne utilisé pour le rendu de l’aperçu.
`created_at`	String (ISO 8601)	Date de création du document.
`document_template_id`	String (UUID)	ID du modèle utilisé pour générer ce document.
`download_url`	String (URL) ou `null`	URL signée temporaire pour télécharger le fichier généré. `null` tant que la génération n’a pas réussi. Valide pendant 1 heure (voir URLs de téléchargement).
`failure_cause`	String ou `null`	Raison de l’échec de la génération. `null` sauf si le statut est `failure`.
`filename`	String ou `null`	Nom du fichier généré. `null` tant que la génération n’a pas réussi. Configurable via la clé meta `_filename`.
`generation_logs`	Array	Logs collectés pendant la génération. Chaque entrée contient `type` (`"info"` ou `"error"`), `message` et `timestamp`. Tableau vide avant le début de la génération.
`meta`	Object ou `null`	Métadonnées arbitraires attachées au document. Supporte des clés spéciales comme `_filename`. Également accessible dans les intégrations no-code (Zapier, Make) où `payload` n’est pas disponible.
`output_type`	String	Format de sortie : `"pdf"` ou `"image"`. Hérité du modèle.
`payload`	Object ou `null`	Les données dynamiques utilisées pour générer le document.
`preview_url`	String (URL)	URL pour intégrer un aperçu visuel du document. Destinée à être utilisée dans une `<iframe>`, pas pour le téléchargement.
`public_share_link`	String (URL) ou `null`	Lien public permanent vers le fichier généré. Disponible uniquement lorsque la fonctionnalité Liens de partage est activée (offres Pro+).
`status`	String	Statut actuel du document : `draft`, `pending`, `generating`, `success` ou `failure`. Voir Statuts des documents et cycle de vie.
`updated_at`	String (ISO 8601)	Date de dernière mise à jour du document.

L’objet DocumentCard

Le DocumentCard est une version allégée du Document. Il contient les mêmes champs sauf payload, generation_logs et checksum. Il ajoute également document_template_identifier.

Utilisez les DocumentCards lorsque vous n’avez pas besoin du payload complet ; ils sont plus rapides et plus légers. Ce sont les objets retournés par les endpoints de liste, l’endpoint sync, les webhooks et les intégrations no-code.

Préférez DocumentCard à Document.

Stockez les données dont vous aurez besoin plus tard dans meta plutôt que (ou en plus de) payload. Ainsi, vous n’aurez jamais besoin de récupérer l’objet Document complet.

{
  "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
  "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
  "created_at": "2050-03-13T12:34:56.181+02:00",
  "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
  "document_template_identifier": "My Invoice Template",
  "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "failure_cause": null,
  "filename": "2050-03-14 Peter Parker.pdf",
  "meta": {
    "_filename": "2050-03-14 Peter Parker.pdf",
    "clientRef": "spidey-616"
  },
  "output_type": "pdf",
  "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
  "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/2050-03-14-peter-parker.pdf",
  "status": "success",
  "updated_at": "2050-03-13T12:34:59.412+02:00"
}

Attributs

Nom	Type	Description
`id`	String (UUID)	Identifiant unique du document.
`app_id`	String (UUID)	Identifiant unique du workspace du document.
`created_at`	String (ISO 8601)	Date de création du document.
`document_template_id`	String (UUID)	ID du modèle utilisé pour générer ce document.
`document_template_identifier`	String	Le nom du modèle tel qu’affiché dans le tableau de bord.
`download_url`	String (URL) ou `null`	URL signée temporaire pour télécharger le fichier généré. `null` tant que la génération n’a pas réussi. Valide pendant 1 heure.
`failure_cause`	String ou `null`	Raison de l’échec de la génération. `null` sauf si le statut est `failure`.
`filename`	String ou `null`	Nom du fichier généré. `null` tant que la génération n’a pas réussi.
`meta`	Object ou `null`	Métadonnées arbitraires attachées au document.
`output_type`	String	Format de sortie : `"pdf"` ou `"image"`. Hérité du modèle.
`preview_url`	String (URL)	URL pour intégrer un aperçu visuel. Pas pour le téléchargement.
`public_share_link`	String (URL) ou `null`	Lien public permanent. Nécessite l’activation des Liens de partage (offres Pro+).
`status`	String	Statut actuel : `draft`, `pending`, `generating`, `success` ou `failure`.
`updated_at`	String (ISO 8601)	Date de dernière mise à jour du document.

Comparaison : Document vs DocumentCard

Champ	Document	DocumentCard
`payload`	Inclus	Non inclus
`generation_logs`	Inclus	Non inclus
`checksum`	Inclus	Non inclus
`document_template_identifier`	Non inclus	Inclus

Récupérer un document

Récupérer un DocumentCard (recommandé)

GET /api/v1/document_cards/{id}

Retourne un DocumentCard pour le document donné. C’est la méthode recommandée pour vérifier le statut de génération et récupérer l’URL de téléchargement.

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c

card = Pdfmonkey::Document.fetch_card('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')

card.status       # => 'success'
card.download_url # => 'https://…'

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

const data = await response.json();
console.log(data.document_card);

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['document_card'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['document_card']);

Réponse : 200 OK avec un objet document_card.

Récupérer un Document complet

GET /api/v1/documents/{id}

Retourne le Document complet, incluant payload et generation_logs. Utilisez cet endpoint uniquement lorsque vous avez besoin de ces champs.

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c

document = Pdfmonkey::Document.fetch('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')

document.status   # => 'success'
document.payload  # => '{"clientName":"Peter Parker",…}'

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

const data = await response.json();
console.log(data.document);

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['document'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['document']);

Réponse : 200 OK avec un objet document.

Lister les documents

GET /api/v1/document_cards

Retourne une liste paginée de DocumentCards. Les résultats sont limités à 24 éléments par page.

Paramètres de requête

Nom	Type	Description
`page[number]`	Integer	Numéro de page (par défaut : `1`).
`q[document_template_id]`	String (UUID) ou Array	Filtrer par un ou plusieurs IDs de modèle. Accepte un UUID unique ou une liste séparée par des virgules.
`q[status]`	String	Filtrer par statut : `draft`, `pending`, `generating`, `success` ou `failure`. Voir Statuts des documents.
`q[workspace_id]`	String (UUID)	Filtrer par ID de workspace.
`q[updated_since]`	Timestamp	Retourner uniquement les documents mis à jour après ce moment. Accepte un timestamp Unix (ex. `1640995200` pour le 2022-01-01 00:00:00 UTC) ou une chaîne ISO 8601.
`q[search]`	String	Rechercher par ID de document ou nom de fichier. Si la valeur est un UUID, recherche par ID exact ; sinon effectue une correspondance partielle sur le nom de fichier.

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  'https://api.pdfmonkey.io/api/v1/document_cards?q[document_template_id]=2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&q[status]=success&page[number]=1'

cards = Pdfmonkey::Document.list_cards(
  page: 1,
  document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  status: 'success'
)

cards.each { |card| puts card.download_url }

cards.current_page # => 1
cards.total_pages  # => 1

const params = new URLSearchParams({
  'q[document_template_id]': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  'q[status]': 'success',
  'page[number]': '1',
});

const response = await fetch(
  `https://api.pdfmonkey.io/api/v1/document_cards?${params}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

const data = await response.json();
console.log(data.document_cards);
console.log(data.meta); // Informations de pagination

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/document_cards',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    params={
        'q[document_template_id]': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
        'q[status]': 'success',
        'page[number]': 1,
    },
)

data = response.json()
print(data['document_cards'])
print(data['meta'])  # Informations de pagination

<?php
$query = http_build_query([
    'q' => [
        'document_template_id' => '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
        'status' => 'success',
    ],
    'page' => ['number' => 1],
]);

$ch = curl_init("https://api.pdfmonkey.io/api/v1/document_cards?{$query}");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['document_cards']);
print_r($data['meta']); // Informations de pagination

Réponse

{
  "document_cards": [
    {
      "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
      "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
      "created_at": "2050-03-13T12:34:56.181+02:00",
      "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "document_template_identifier": "My Invoice Template",
      "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
      "failure_cause": null,
      "filename": "2050-03-14 Peter Parker.pdf",
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      },
      "output_type": "pdf",
      "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
      "public_share_link": null,
      "status": "success",
      "updated_at": "2050-03-13T12:34:59.412+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

L’objet meta contient les informations de pagination :

Champ	Type	Description
`current_page`	Integer	Le numéro de la page courante.
`next_page`	Integer ou `null`	Le numéro de la page suivante, ou `null` si c’est la dernière page.
`prev_page`	Integer ou `null`	Le numéro de la page précédente, ou `null` si c’est la première page.
`total_pages`	Integer	Le nombre total de pages disponibles.

Mettre à jour un document

PUT /api/v1/documents/{id}

Met à jour un document existant. Vous pouvez modifier son payload, ses métadonnées, ou déclencher la génération en passant status à "pending".

Paramètres

Tous les paramètres sont imbriqués sous une clé document.

Nom	Type	Requis	Description
`document_template_id`	String (UUID)	Non	Changer le modèle.
`payload`	Object ou String	Non	Remplacer les données dynamiques.
`meta`	Object ou String	Non	Remplacer les métadonnées.
`status`	String	Non	Passer à `"pending"` pour déclencher la génération.

curl https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "status": "pending",
      "payload": { "name": "Mary Jane Watson" }
    }
  }'

document = Pdfmonkey::Document.fetch('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')

document.update!(
  status: 'pending',
  payload: { name: 'Mary Jane Watson' }
)

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      document: {
        status: 'pending',
        payload: { name: 'Mary Jane Watson' },
      },
    }),
  }
);

const data = await response.json();
console.log(data.document);

import requests

response = requests.put(
    'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'status': 'pending',
            'payload': {'name': 'Mary Jane Watson'},
        },
    },
)

print(response.json())

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document' => [
            'status' => 'pending',
            'payload' => ['name' => 'Mary Jane Watson'],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Réponse : 200 OK avec l’objet document mis à jour.

Supprimer un document

DELETE /api/v1/documents/{id}

Supprime définitivement un document et son fichier généré.

curl https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Pdfmonkey::Document.delete('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')
# => true

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

console.log(response.status); // 204

import requests

response = requests.delete(
    'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

print(response.status_code)  # 204

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE); // 204
curl_close($ch);

Réponse : 204 No Content avec un corps vide.

URLs de téléchargement

Les URLs de téléchargement sont des liens S3 signés temporaires, valides pendant 1 heure. Pour obtenir une URL fraîche après expiration, récupérez simplement le document à nouveau ; il n’est pas nécessaire de le regénérer. Pour des liens permanents, activez les Liens de partage (offres Pro+).

Consultez URL de téléchargement pour les détails sur l’expiration, les bonnes pratiques et le dépannage.

Authentification — Trouvez votre clé API et authentifiez vos requêtes.
API Templates — Listez et récupérez vos modèles pour trouver le document_template_id dont vous avez besoin.
Générer des documents avec l’API — Guide pas-à-pas pour générer votre premier document.
Statuts des documents et cycle de vie — Comprenez le cycle draft / pending / generating / success / failure.
URL de téléchargement — Comportement des URLs de téléchargement, expiration et bonnes pratiques.
Webhooks — Recevez des notifications en temps réel lorsque la génération est terminée.
Nom de fichier personnalisé — Contrôlez le nom de fichier des documents générés via la clé meta _filename.
Liens de partage — URLs publiques permanentes pour les documents générés (offres Pro+).
Intégrer un aperçu — Intégrez un aperçu visuel de votre document dans une page web.

Questions fréquentes

Comment générer un document avec l’API PDFMonkey ?: Envoyez une requête POST à /api/v1/documents avec l’ID du modèle et les données dynamiques. Définissez le statut sur "pending" pour lancer la génération immédiatement. Interrogez ensuite le statut du document ou utilisez les webhooks.
Quelle différence entre Document et DocumentCard dans PDFMonkey ?: Un Document est l’objet complet incluant payload, generation_logs et checksum. Un DocumentCard est une version allégée sans ces champs mais avec document_template_identifier en plus.
PDFMonkey prend-il en charge la génération synchrone ?: Oui. Envoyez un POST à /api/v1/documents/sync pour créer un document et attendre le résultat en une seule requête. L’endpoint a un timeout de 6 minutes et renvoie un DocumentCard.
Combien de temps une URL de téléchargement PDFMonkey est-elle valide ?: Les URL de téléchargement sont des liens S3 signés temporaires valides 1 heure. Après expiration, récupérez le document à nouveau pour obtenir une URL fraîche.

API Documents : créer, lister et gérer les documents générés

Démarrage rapide

Authentification

Créer un document

Paramètres

Requête

Réponse

Erreurs de validation

Génération synchrone

Quand utiliser sync vs async

Requête

Réponse

L’objet Document

Attributs

L’objet DocumentCard

Attributs

Comparaison : Document vs DocumentCard

Récupérer un document

Récupérer un DocumentCard (recommandé)

Récupérer un Document complet

Lister les documents

Paramètres de requête

Réponse

Mettre à jour un document

Paramètres

Supprimer un document

URLs de téléchargement

Pages associées

Questions fréquentes