Bases de l'API

URL de base

Chaque endpoint de cette documentation est relatif à :

https://app.doclift.io/api/v1

Envoyez vos requêtes directement depuis votre serveur, jamais depuis le navigateur d'un utilisateur. Votre clé d'API serait sinon exposée à quiconque inspecte la page.

Authentification

Chaque requête porte un en-tête X-Api-Key. La clé identifie une application externe, qui appartient à une organisation. Chaque lecture et écriture de cette API est restreinte à cette organisation, pas à un utilisateur ou à une clé en particulier.

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

Une clé appartenant à une application externe désactivée répond exactement comme une clé inconnue : 403 Forbidden. Voir Codes de réponse pour les corps exacts.

Verbes HTTP

Envoyez des corps JSON ; chaque réponse est en JSON.

Environnements

Chaque application externe (clé d'API) est créée dans l'un des deux environnements. Les deux partagent les mêmes modèles et les mêmes données : un environnement est une propriété de la clé, pas de la ressource sur laquelle elle agit.

La création d'une clé de production requiert que votre organisation soit autorisée pour le mode production ; cette vérification n'a lieu qu'à la création de la clé, donc une clé de production déjà émise continue de fonctionner même si l'autorisation est révoquée par la suite. Il n'existe pas de restriction équivalente sur les clés sandbox.

Format de date

Tous les horodatages (created_at, updated_at, generated_at, timestamp et champs similaires) sont rendus au format ISO-8601, par exemple 2024-01-15T10:30:00+01:00. Le champ timestamp envoyé dans chaque payload de webhook est calculé au moment de la réponse plutôt que lu depuis une colonne stockée, mais utilise le même format ISO-8601 que tout autre champ de date de cette API.

Langue des réponses

Les messages d'erreur sont rendus en français par défaut. Pour les recevoir en anglais, envoyez l'en-tête Accept-Language :

curl https://app.doclift.io/api/v1/document_requests \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Accept-Language: en" \
  --header "Content-Type: application/json" \
  --data '{ "document_request": { "type": "synchrone" } }'

fr et en sont les deux seules langues servies. Un en-tête portant autre chose, ou absent, laisse le français. Un en-tête pondéré est lu dans son ordre de préférence.

Seuls les messages changent : les codes de statut, les clés JSON et les valeurs machine comme code ou generation_status sont identiques dans les deux langues, et ce sont elles qu'il faut tester dans votre code.

Codes de réponse

Erreurs

Il n'existe pas d'enveloppe d'erreur unique partagée par toute l'API. La forme dépend de ce qui a échoué :

Pagination

Deux endpoints de liste sont paginés : GET /api/v1/templates et GET /api/v1/document_requests. La taille de page est fixée à 30 et ne peut pas être modifiée ; ajoutez ?page= pour parcourir les résultats. Une page au-delà de la dernière répond toujours 200 avec un tableau vide, jamais un 404.

Chaque réponse paginée porte ces en-têtes :

GET /api/v1/templates/:template_id/variables n'est pas paginé. Il renvoie toujours toutes les variables du modèle dans un seul tableau.

Informations utilisateur

Renvoie le profil de l'utilisateur auquel votre clé correspond (le créateur de l'application externe, ou le propriétaire de l'organisation si ce créateur a été désactivé), ainsi que les limites de compte de votre organisation et les informations publiques propres à la clé appelante. Aucun paramètre.

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

{
  "id": 100001,
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "created_at": "2021-02-15T10:30:00+01:00",
  "updated_at": "2021-06-20T14:00:00+01:00",
  "document_max_length_allowed": 800000,
  "webhooks_replays_count": 3,
  "allowed_to_use_production_mode": false,
  "current_external_application": {
    "name": "My App",
    "environment": "sandbox",
    "active": true,
    "webhook_url": "https://myapp.com/webhooks/doclift",
    "revealable_secret_key": "•••...abc12345"
  }
}

document_max_length_allowed, webhooks_replays_count et allowed_to_use_production_mode sont les réglages de votre organisation, pas des réglages personnels. Chaque clé de la même organisation renvoie les mêmes valeurs. current_external_application n'inclut jamais le secret_key brut, seulement le revealable_secret_key masqué.

Codes de statut : 200 en cas de succès, 403 selon les règles d'authentification ci-dessus. Il n'y a pas d'autre mode d'échec pour cet endpoint.