Renders API

L'API Renders vous permet de générer des PDF remplis à partir de vos templates. Envoyez des données JSON et recevez une URL de téléchargement.

Endpoints

Méthode	Endpoint	Description
`POST`	`/renders`	Créer un render
`GET`	`/renders`	Lister les renders
`GET`	`/renders/:id`	Récupérer un render
`GET`	`/renders/usage`	Statistiques d'utilisation
`DELETE`	`/renders/:id`	Supprimer un render

Créer un render

POST /renders

Génère un PDF rempli à partir d'un template et de données JSON.

Request Body

Paramètre	Type	Requis	Description
`templateId`	String	Oui	ID du template à remplir
`data`	Object	Oui	Données à insérer dans le PDF
`options`	Object	Non	Options de rendu

Options de rendu

Option	Type	Défaut	Description
`flatten`	Boolean	true	Aplatir le PDF (rendre les champs non éditables)
`locale`	String	"fr-FR"	Locale pour le formatage des dates
`timezone`	String	"Europe/Paris"	Timezone pour les dates
`watermark`	Boolean \| "auto"	"auto"	Ajouter un filigrane ("auto" = selon le plan)
`strict`	Boolean	false	Échouer si un champ est inconnu

Exemple

curl -X POST https://api.docflow.io/v1/renders \
  -H "Authorization: Bearer df_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_abc123",
    "data": {
      "employee_name": "Jean Dupont",
      "start_date": "2024-02-01",
      "contract_type": "CDI",
      "salary": 45000,
      "accept_terms": true
    },
    "options": {
      "flatten": true,
      "locale": "fr-FR"
    }
  }'

Response (201 Created)

{
  "data": {
    "renderId": "rnd_xyz789",
    "status": "completed",
    "downloadUrl": "https://storage.docflow.io/renders/rnd_xyz789.pdf?token=...",
    "expiresIn": 900,
    "fileSize": 256000,
    "durationMs": 342,
    "warnings": []
  }
}

Champs de réponse

Champ	Type	Description
`renderId`	String	ID unique du render
`status`	String	"completed" ou "failed"
`downloadUrl`	String	URL présignée pour télécharger le PDF
`expiresIn`	Integer	Durée de validité de l'URL en secondes
`fileSize`	Integer	Taille du fichier en bytes
`durationMs`	Integer	Temps de génération en millisecondes
`warnings`	String[]	Avertissements (champs ignorés, etc.)

Lister les renders

GET /renders

Query Parameters

Paramètre	Type	Description
`page`	Integer	Numéro de page (défaut: 1)
`limit`	Integer	Résultats par page (défaut: 20, max: 100)
`templateId`	String	Filtrer par template
`status`	String	Filtrer par statut

Response

{
  "data": [
    {
      "id": "rnd_xyz789",
      "templateId": "tpl_abc123",
      "templateName": "Contrat de travail",
      "status": "completed",
      "fileSize": 256000,
      "durationMs": 342,
      "expiresAt": "2024-01-22T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "downloadUrl": "https://..."
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42
  }
}

Statistiques d'utilisation

GET /renders/usage

Récupère les statistiques d'utilisation du mois en cours.

Response

{
  "data": {
    "plan": "pro",
    "month": "2024-01",
    "renders": {
      "used": 1250,
      "limit": 5000
    },
    "templates": {
      "used": 12,
      "limit": 50
    },
    "apiKeys": {
      "used": 3,
      "limit": 10
    },
    "features": {
      "webhooksEnabled": true,
      "watermark": false,
      "retentionDays": 30
    }
  }
}

Télécharger un PDF

L'URL de téléchargement (downloadUrl) est une URL présignée valide pendant 15 minutes (900 secondes). Utilisez cette URL directement pour télécharger le PDF :

curl -o document.pdf "https://storage.docflow.io/renders/rnd_xyz789.pdf?token=..."

Pour obtenir une nouvelle URL après expiration, récupérez le render avec GET /renders/:id.

Erreurs courantes

RENDER_LIMIT_REACHED

Vous avez atteint la limite de renders de votre plan pour ce mois.

{
  "error": {
    "code": "RENDER_LIMIT_REACHED",
    "message": "Monthly render limit reached (50/50)"
  }
}

TEMPLATE_NOT_FOUND

Le template spécifié n'existe pas ou a été supprimé.

{
  "error": {
    "code": "TEMPLATE_NOT_FOUND",
    "message": "Template 'tpl_abc123' not found"
  }
}

VALIDATION_ERROR

Les données fournies sont invalides (mauvais type, champ manquant en mode strict, etc.).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid data for field 'salary': expected number, got string",
    "details": {
      "field": "salary",
      "expected": "number",
      "received": "string"
    }
  }
}

RENDER_FAILED

Une erreur s'est produite lors de la génération du PDF.

{
  "error": {
    "code": "RENDER_FAILED",
    "message": "Failed to render PDF: corrupted template file"
  }
}