API Demandes de document

L'objet demande de document

• id : identifiant unique
• tag : chaîne libre que vous envoyez, renvoyée telle quelle
• type : asynchrone (orthographié tel quel, pas le terme anglais « asynchronous ») ; la valeur à envoyer à la création
• sandbox_mode : défini une fois pour toutes à la création, d'après l'environnement de la clé appelante
• status : in_progress, success, ou error (le résultat global de la requête)
• documents_generations : présent sur l'endpoint de liste et sur l'endpoint de détail ; absent de la réponse de création, puisque rien n'a encore été rendu au moment où elle répond ; chaque entrée a id, tag, generated_at, created_at, generation_status (created, in_progress, success, ou error), et file (filename, url, size)

template_id accepte un modèle custom, fillable_form, ou workflow, du moment qu'il est publié. La forme du payload est identique pour les trois. Les modèles workflow portent un contrat supplémentaire par-dessus tout ce qui suit. Voir Modèles workflow.

Génération asynchrone

type: "asynchrone" accepte une ou plusieurs entrées dans document_generations et répond immédiatement avec id, tag, type, sandbox_mode, et status: "in_progress" : aucune clé documents_generations du tout, puisque rien n'a encore été rendu. Les documents terminés arrivent plus tard sous forme de webhook. Voir Webhooks. La génération nécessite une URL de webhook configurée sur l'application externe appelante ; sans elle, la requête est refusée avant même que quoi que ce soit soit créé :

{
  "error": "Please add a webhook URL to this external application to use asynchronous generation. You can add one from your Doclift.io account."
}

Créer une demande de document

curl https://app.doclift.io/api/v1/document_requests \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "document_request": {
      "type": "asynchrone",
      "document_generations": [
        {
          "template_id": 100013,
          "tag": "Invoice#42",
          "variables": {
            "client_name": "John Doe"
          }
        }
      ],
      "tag": "Batch#1"
    }
  }'

{
  "id": 100004,
  "tag": "Batch#1",
  "type": "asynchrone",
  "sandbox_mode": false,
  "status": "in_progress"
}

Il n'y a pas de clé d'idempotence : envoyer deux fois le même corps crée deux demandes de document indépendantes, chacune avec son propre statut.

Erreurs de validation

Chacun des cas suivants est vérifié dans l'ordre ; le premier échec court-circuite le reste et répond avant qu'aucun document ne soit généré.

Une clé d'API absente, invalide, ou désactivée répond 403 dans tous les cas, comme partout ailleurs dans l'API. Voir Codes de réponse.

Erreurs de validation des variables

Sur un modèle fillable_form uniquement, chaque valeur fournie est vérifiée par rapport aux allowed_values auto-détectées de sa variable (voir Formulaires PDF). Une valeur hors de la liste autorisée répond 422 en nommant chaque champ fautif :

{
  "error": "Les valeurs fournies pour certaines variables ne sont pas valides (status: 'bad_value' (valeurs autorisées : approved, rejected)).",
  "invalid_variables": [
    { "field": "status", "value": "bad_value", "allowed_values": ["approved", "rejected"] }
  ]
}

Les modèles custom et workflow ne sont pas vérifiés par rapport à allowed_values au moment de la génération par cette étape.

Si la génération échoue pour toute autre raison une fois le payload par ailleurs valide, vous l'observez via generation_status/generation_error de GET /api/v1/document_requests/:id, ou via generation_status: "error" du payload du webhook.

Modèles workflow

Les modèles workflow sont générés via ce même endpoint. Il n'y a pas de route de génération workflow séparée. Les workflows sont en bêta privée, disponibles sur demande en écrivant à [email protected] ; voir Workflows pour la vue d'ensemble.

En plus de tout ce qui précède, le payload variables d'un workflow porte un contrat de variable requise qu'aucune autre catégorie n'impose :

{
  "template_id": 100050,
  "variables": {
    "investor_type": "natural",
    "country": "FR",
    "investments": [{ "product": "SCPI", "amount": "10 000 €" }]
  },
  "tag": ""
}

Une clé présente avec une chaîne vide ou null compte comme répondue. Seule l'absence de la clé déclenche la vérification de variable manquante. Tous les échecs applicables sur le lot entier sont rapportés ensemble dans un seul 422 {"error": "..."}, nommant chaque modèle et variable concernés à la fois (utile lorsqu'un lot mélange plusieurs générations de workflow). allowed_values n'est pas vérifié pour les variables de workflow au moment de la génération.

Lister les demandes de document

curl https://app.doclift.io/api/v1/document_requests \
  --header "X-Api-Key: <your-api-key>"

[
  {
    "id": 100004,
    "tag": "Batch#1",
    "type": "asynchrone",
    "external_application": {
      "id": 100000,
      "name": "Production key",
      "environment": "sandbox",
      "active": true
    },
    "documents_generations": [
      {
        "id": 100230,
        "tag": "Invoice#42",
        "generated_at": "2024-01-15T10:35:02+01:00",
        "created_at": "2024-01-15T10:35:00+01:00",
        "generation_status": "success",
        "file": {
          "filename": "Invoice-1615737313.pdf",
          "url": "https://doclift.s3.eu-west-1.amazonaws.com/d207f8fe.pdf?[...]",
          "size": 40290
        }
      }
    ]
  }
]

Liste les demandes de document de votre organisation, les plus récentes en premier. Cela découle de l'association au niveau de l'organisation, donc les demandes créées via d'autres applications externes de la même organisation apparaissent aussi, pas seulement celles de la clé appelante. Paginé à 30 par page ; voir Pagination.

Consulter une demande de document

curl https://app.doclift.io/api/v1/document_requests/100004 \
  --header "X-Api-Key: <your-api-key>"

{
  "id": 100004,
  "tag": "Batch#1",
  "type": "asynchrone",
  "external_application": {
    "id": 100000,
    "name": "Production key",
    "environment": "sandbox",
    "active": true
  },
  "documents_generations": [
    {
      "id": 100230,
      "tag": "Invoice#42",
      "generated_at": "2024-01-15T10:35:02+01:00",
      "created_at": "2024-01-15T10:35:00+01:00",
      "generation_status": "success",
      "generation_duration": 1721,
      "generation_error": null,
      "sent_payload": { "client_name": "John Doe" },
      "file": {
        "filename": "Invoice-1615737313.pdf",
        "url": "https://doclift.s3.eu-west-1.amazonaws.com/d207f8fe.pdf?[...]",
        "size": 40290
      },
      "template": {
        "id": 100013,
        "title": "Invoice",
        "description": "A template for invoices"
      }
    }
  ]
}

C'est la vue la plus riche : sent_payload (exactement ce que vous avez envoyé), generation_duration, generation_error, et le template source ne sont présents qu'ici, jamais dans la liste ni dans la réponse de création. Les URLs de fichier sont valables 20 heures dans cette vue, contre 2 heures partout ailleurs.

Limites

Il n'y a aucune limitation de débit sur cette API. Voir Environnements.