L’API EZDocuAI pour les développeurs

Avec l’API EZDocuAI (v1), vous connectez votre propre système (CRM, ERP, site de commande) à EZDocuAI. Votre système téléverse le document, crée la commande de traduction ou de mise en page, apprend quand elle est terminée et télécharge le résultat, sans passer par le panneau. Ce sont les mêmes commandes et le même solde de crédits que sur le web.

Qui peut créer des clés

Cela ne dépend pas du plan, mais de la permission Clés API. Le propriétaire l’a toujours et les gestionnaires l’ont par défaut. Le Réviseur et le Membre l’ont désactivée ; le propriétaire peut l’activer personne par personne dans Équipe.

Avec un accès en lecture seule, vous ne pouvez ni voir, ni créer, ni révoquer de clés. Chaque clé agit avec l’accès de la personne qui l’a créée et ne fait jamais plus que cette personne. Si cette personne est désactivée dans l’équipe, sa clé apparaît comme Suspendue.

Créer une clé

1. Allez dans Paramètres › Clés API.
2. Cliquez sur Créer une clé.
3. Donnez-lui un Nom pour la reconnaître, par exemple Intégration ERP.
4. Choisissez l’Environnement : Staging pour tester ou Production pour travailler pour de vrai.
5. Cochez les Services : Traduction, Layout ou les deux. Sans service, la clé ne fait que consulter.
6. Dans Accès par domaine, cochez lecture ou écriture. Vous ne pouvez accorder que les accès que vous avez ; Commandes et Webhooks exigent la permission « Voir et attribuer tous les documents ».
7. Si vous le souhaitez, fixez une Limite quotidienne de pages (vide = sans limite ; 5000 maximum).
8. Cliquez sur Créer la clé, copiez-la avec Copier et cliquez sur Je l’ai enregistrée. La clé complète n’est affichée qu’à ce moment-là.

Vous pouvez avoir jusqu’à 20 clés actives. Révoquer désactive une clé immédiatement, de façon irréversible. Traitez-la comme un mot de passe.

Staging et Production : vers où pointe chaque clé

Les deux se créent ici, sur www.ezdocu.ai, depuis Paramètres › Clés API. Vous n’avez pas besoin d’un autre compte.

Chaque clé ne fonctionne qu’avec son URL. Commencez par Staging ; quand tout fonctionne, changez l’URL et la clé : les routes sont les mêmes.

Où trouver la documentation

Dans le menu latéral, Documentation de l’API. Vous y trouverez le Démarrage rapide, les guides Traduire un document, Layout sans traduction et Révision humaine, Webhooks et vérification de signature et la référence de chaque route avec des exemples.

• Dans Environnements, vous choisissez Staging ou Production : l’URL de base, les exemples et les téléchargements (Télécharger Postman et Télécharger OpenAPI) changent en conséquence.
• Tester dans Swagger appelle le serveur du site sur lequel vous êtes : sur www, c’est la Production, et créer une commande consomme des crédits. Pour la clé Staging, utilisez Postman ou votre code.

Le flux de base

Chaque requête porte l’en-tête Authorization: Bearer <votre clé>. Toute requête POST, PATCH, PUT et DELETE porte en plus Idempotency-Key : si vous répétez la requête avec la même valeur, deux commandes ne sont jamais créées et rien n’est facturé deux fois.

1. Téléversez le fichier avec POST /uploads (qui vous donne une URL de téléversement), envoyez-le à cette URL et confirmez-le avec POST /uploads/{id}/complete. S’il se trouve déjà à une URL https:// publique, envoyez-la dans file_url en créant la commande.
2. Créez la commande avec POST /orders. Dans mode, indiquez translate (traduire) ou layout (mettre en page dans la même langue). Pour traduire, indiquez target_language, par exemple en-US. La langue du document est détectée automatiquement.
3. Attendez le résultat : avec le webhook order.completed (recommandé) ou en consultant GET /orders/{id} toutes les 15 à 30 secondes.
4. Téléchargez : quand la commande est completed, le détail contient un lien par fichier, valable 1 heure.

Quels fichiers vous recevez

PDF, DOCX et HTML (un HTML par page et un avec toutes les pages), dans la combinaison que vous demandez, plus le certificat et l’original. Le contenu du document n’est jamais inclus dans le JSON de la réponse : seulement les liens et les données de la commande. Pour une traduction, le certificat et la signature numérique du PDF sont inclus par défaut ; vous pouvez les retirer dans la requête.

Webhooks

Ils se créent par l’API (POST /webhooks), pas dans Paramètres. EZDocuAI envoie un POST signé à votre URL https:// à chaque événement :

Le secret de signature (whsec_…) n’est affiché qu’une seule fois. Votre serveur doit répondre 2xx en moins de 10 secondes ; sinon, EZDocuAI réessaie pendant un peu plus d’un jour et demi.

Révision humaine

Avec review_required: true, la commande s’arrête en in_review et attend votre équipe, sans limite de temps. La personne qui la révise l’ouvre dans Commandes, clique sur Continuer la commande, la révise et clique sur Terminer la commande. C’est alors que order.completed arrive. La personne qui finalise choisit le format, le certificat et le Sceau Vérifié par un humain : une commande sans révision ne porte jamais ce sceau. L’approbation se fait sur le web, pas par l’API.

Crédits et limites

• Même solde que sur le web : 1 crédit par page, débité à la création de la commande.
• Sans solde suffisant, POST /orders répond 402 INSUFFICIENT_CREDITS et rien n’est créé ni facturé.
• Si une commande facturée échoue ou si vous l’annulez, les crédits ne sont pas rendus automatiquement : écrivez au support avec le numéro de la commande.
• Demander du DOCX, du HTML, le certificat ou une révision ne coûte rien de plus.
• 100 requêtes par minute par clé (par défaut). Fichiers jusqu’à 50 Mo et 2000 pages, en PDF, JPG, PNG, TIFF, WebP, HEIC, DOCX ou ODT.

Erreurs fréquentes

Tableau de bord d’utilisation

Dans le menu latéral, API ouvre Usage de l’API : requêtes, commandes, pages, erreurs, webhooks et limites de votre compte, par période, par clé et par membre. Les personnes ayant la permission Clés API y ont accès.

Questions fréquentes

Faut-il un plan spécial pour utiliser l’API ? Non. Il faut la permission Clés API, que possèdent le propriétaire et les gestionnaires.

Mon développeur reçoit une erreur 401 ou 403 avec la clé Staging : que se passe-t-il ? C’est presque toujours l’URL : la clé Staging (ezk_test_) ne fonctionne qu’avec https://staging.ezdocu.ai/api/v1, et la clé Production (ezk_live_), qu’avec https://www.ezdocu.ai/api/v1. Si la clé Staging vient d’être créée, attendez une minute avant de l’utiliser.

Les tests avec la clé Staging consomment-ils des crédits ? Non : les commandes sont simulées. Seule la clé Production est facturée.

Puis-je recevoir la traduction sous forme de texte en JSON ? Non. L’API livre des fichiers : PDF, DOCX ou HTML.