L'API PaperOffice pour les développeurs: le guide complet

Où se trouve la spécification

La spécification des points de terminaison est générée en direct à partir du catalogue d'API. Utilisez ces fichiers au lieu de copier les listes de points de terminaison depuis des articles :

• Index compact pour les clients IA : https://api.paperoffice.ai/latest/docs/llms.txt
• Référence complète : https://api.paperoffice.ai/latest/docs/llms-full.txt
• OpenAPI 3.1 : https://api.paperoffice.ai/latest/docs/openapi.json
• Compétence agent : https://api.paperoffice.ai/latest/docs/skill.md
• Collection Postman : https://api.paperoffice.ai/latest/docs/postman

Les routes de documentation sont publiques et ne nécessitent aucun jeton. Importez l'URL Postman dans Postman, VS Code ou Bruno, et téléchargez-la à nouveau lorsque la version de la documentation change. L'adresse de base en production est https://api.paperoffice.ai/latest ; utilisez /dev uniquement pour le développement.

Un démarrage rapide avec un assistant de codage IA : donnez-lui l'adresse de llms-full.txt et décrivez la fonction dont vous avez besoin, par exemple une fonction qui envoie une image et retourne le texte reconnu.

Authentification et types de jetons

La plupart des points de terminaison du produit nécessitent un jeton porteur (bearer token) dans l'en-tête Authorization. Vous créez des jetons dans l'application PaperOffice sous Compte → API.

• Clé système (po_sk_): intégration serveur-à-serveur avec un accès complet à l'API. Ne jamais l'utiliser dans un navigateur.
• Jeton utilisateur (po_ut_) : la portée d'un seul utilisateur, par exemple pour MCP. Les droits suivent l'utilisateur et la licence.
• Jeton de groupe (po_gt_) : hérite des droits et de la liste blanche d'espaces de travail d'un groupe d'utilisateurs.
• Clé publiable (po_pk_): à utiliser dans un navigateur. Chaque requête nécessite une origine que le propriétaire de la clé a saisie, un budget global sur la durée de vie de la clé limite la consommation, et la suppression, l'administration du compte, la gestion des clés et les modifications de paiement restent bloqués. Elle n'est pas autorisée pour MCP.

Sans jeton, seuls les points de terminaison d'infrastructure tels que la spécification, le contrôle de santé et le test de connectivité sont accessibles. Une requête vers un produit sans jeton reçoit la réponse HTTP 403 et le code TIER_RESTRICTED, et non avec HTTP 401.

Tâches : attente, interrogation (polling) et résultats

Le traitement s'exécute sous forme de tâches. Les chemins des tâches utilisent le motif handler___command avec trois tirets bas, par exemple POST /job/add/paperoffice_aiocr___generate pour la reconnaissance de texte. La notation pointée est rejetée avec JOB_CONFIG_INVALID.

• Par défaut, la requête maintient la connexion pendant un certain temps. Si la tâche se termine dans les délais, vous obtenez le résultat directement. Sinon, vous obtenez HTTP 202 avec un ID de tâche et une adresse d'interrogation (poll), et la tâche continue de s'exécuter.
• HTTP 202 est un succès, pas une erreur. Interrogez GET /job/get/{job_id} toutes les 5 à 10 secondes jusqu'à ce que le statut soit terminé. Le résultat se trouve alors dans job_result.
• Avec client_wait=false, vous obtenez l'ID de tâche immédiatement et commencez l'interrogation dès le début.
• Toutes les réponses sont au format JSON. Les clients doivent lire le champ code stable, et non le texte du message localisé.

Vous voyez les tâches API en file d'attente, en cours et terminées dans l'application sous Compte → API → File des jobs. La liste complète des codes d'erreur se trouve dans la spécification; les cas typiques sont des paramètres manquants ou invalides (400), un jeton manquant ou invalide (401), un solde insuffisant de Credits (402), une action interdite (403) et trop de requêtes (429, respecter Retry-After).

SLA de démarrage : quand une tâche démarre

Le champ optionnel processing_lane contrôle quand une tâche démarre dans la file d'attente, et non quand elle se termine. client_wait contrôle si la connexion attend le résultat ; les deux champs sont indépendants.

Sans processing_lane, la valeur par défaut de l'espace de travail s'applique, sinon best effort. Chaque plan inclut best effort sans surcoût. Les voies de démarrage plus rapides sont optionnelles et coûtent plus cher. Les voies actuelles et leurs prix sont disponibles en direct via la liste des prix de l'API ; les détails se trouvent dans la documentation de l'API.

Webhooks

Les points de terminaison webhook reçoivent des événements de tâche et de compte, par exemple job.completed, job.failed, job.progress et des événements pour les documents, les espaces de travail et les tâches. Les avis de compte tels qu'un portefeuille vide ou une clé révoquée ne sont pas des événements webhook.

• Les payloads sont signés avec HMAC-SHA256 dans l'en-tête X-Paperoffice-Signature. Calculez la signature sur le corps brut de la requête avec votre secret webhook et rejetez la requête si elle ne correspond pas.
• Les webhooks sont enregistrés, listés, mis à jour, testés et supprimés via l'API.

Facturation et utilisation

Les appels API consomment Credits depuis le pool partagé de l'organisation, le même pool que celui de l'application. Certaines requêtes d'état et de santé ne sont pas facturées; les détails figurent dans la documentation de l'API. Les appels rejetés en raison d'une entrée invalide sont également facturés; les appels limités par le débit ne le sont pas.

Vous voyez les appels avec leurs Credits sous API & Développeur → Utilisation de l'API : le journal en direct affiche chaque requête, l'historique affiche l'utilisation par date, gestionnaire et action. Lorsque le solde de Credits est épuisé, les appels sont rejetés jusqu'à ce que le solde soit rechargé ou que le rechargement automatique prenne effet. Les limites de débit dépendent de votre plan; les limites actuelles et les en-têtes de réponse sont décrits dans la documentation de l'API. En savoir plus sur Credits: Facturation et Credits dans PaperOffice AI.

MCP : connecter les assistants IA

MCP connecte les assistants IA tels que Claude, ChatGPT, Grok et Cursor directement à PaperOffice. L'authentification est OAuth 2.1 ou un jeton utilisateur ou de groupe; les clés système et les clés publiables sont bloquées pour le MCP. L'hôte de production est https://mcp.paperoffice.ai, avec des profils tels que /claude, /chatgpt, /grok, /cursor et /dms. Configuration, autorisations et flux de données: Utilisation de PaperOffice avec Claude, ChatGPT, Grok et Cursor.

Questions fréquemment posées

• Où puis-je trouver tous les points de terminaison ? Dans llms.txt, llms-full.txt et le fichier OpenAPI. Ils sont générés en temps réel.
• Quel jeton mon serveur doit-il utiliser ? Une clé système, jamais dans un navigateur. Pour un navigateur, utilisez une clé publiable avec une origine et un budget.
• HTTP 202 est-il une erreur ? Non. Le travail est toujours en cours ; interrogez le résultat.
• Les voies de démarrage plus rapides coûtent-elles plus cher ? Oui. Best effort n'entraîne aucun supplément ; les prix actuels figurent dans la liste des prix de l'API.
• Les appels rejetés sont-ils facturés ? Les appels rejetés en raison d'une entrée invalide sont facturés ; les appels limités par le débit ne le sont pas.