Documentation de l'API DocAI

DocAI fournit une API REST pour extraire des données structurées de documents téléversés ou de pièces jointes d’e-mails normalisées. Les tâches persistantes, l’approbation humaine, les webhooks signés et les exports comptables prennent en charge les automatisations dans Make, n8n, Zapier ou des intégrations personnalisées.

Vous développez plutôt avec un agent de codage qu'avec du code applicatif ? DocAI MCP connecte Codex, Claude Code, Gemini CLI et d'autres agents compatibles MCP à cette même API.

Authentification

Créez et gérez vos clés API sur la page Paramètres développeur. Envoyez la clé comme jeton bearer ; les scopes et le quota mensuel de pages de la clé sont appliqués à chaque requête.

Authorization: Bearer sk_docai_<your_key>

Les clés API commencent par sk_docai_. Gardez-les secrètes. Elles ne sont affichées qu'une seule fois lors de leur création.

Utilisez la portée extract pour soumettre et suivre les tâches. Ajoutez la portée history pour récupérer les résultats enregistrés et les exports comptables. Ce sont les seules portées de clé API prises en charge.

Limites de débit

L'utilisation des analyses est régie par le quota de pages et de stockage de votre forfait. Il n'existe pas de plafond distinct par requête ou par jour.

Les clés API décomptent en outre les pages OCR du quota mensuel de pages de la clé.

Les requêtes à court de pages ou de stockage renvoient HTTP 402 ; une clé API ayant dépassé son quota mensuel de pages renvoie HTTP 429 avec un indice Retry-After.

Format des erreurs

{
  "detail": "File too large. Maximum upload size is 15 MB.",
  "request_id": "abc123"
}

Extraction de document synchrone

POST/api/v1/analyze

Téléversez un document et obtenez les résultats d'extraction de manière synchrone. Idéal pour les petits documents (< 2 pages).

Requête

Données de formulaire multipart :

Champ	Type		Description
`file`	file	obligatoire	PDF, PNG, JPG, HEIC, AVIF, TIFF, BMP ou WEBP (15 Mo max)
`filename`	string	facultatif	Remplacer le nom de fichier affiché

Exemple

curl -X POST https://docai.synairo.com/api/v1/analyze \
  -H "Authorization: Bearer sk_docai_..." \
  -F "file=@purchase_order.pdf"

Réponse

{
  "request_id": "3fa8...",
  "filename": "purchase_order.pdf",
  "document_type": "purchase_order",
  "document_type_confidence": 0.94,
  "summary": "Purchase order from Acme Corp to Widget Co.",
  "language": "en",
  "extracted_fields": [
    {
      "field": "po_number",
      "value": "PO-2026-0042",
      "confidence": 0.97,
      "page": 1,
      "evidence": "PO-2026-0042"
    }
  ],
  "warnings": [],
  "ocr": { "pages": 1, "tokens": 312, "language": "eng+pol" },
  "llm": { "status": "success", "provider": "openai", "model": "gpt-4o-mini" }
}

Extraction en flux (SSE)

POST/api/v1/analyze/stream

Identique à l'extraction synchrone, mais diffuse des Server-Sent Events indiquant la progression du traitement. Idéal pour les interfaces en temps réel.

Créer une tâche asynchrone

POST/api/v1/jobs

Téléversez un document et obtenez un identifiant de tâche. Le traitement s'effectue en arrière-plan.

curl -X POST https://docai.synairo.com/api/v1/jobs \
  -H "Authorization: Bearer sk_docai_..." \
  -F "file=@invoice.pdf"

{ "job_id": "abc123", "status": "queued", "request_id": "xyz..." }

Ingérer des pièces jointes par e-mail

POST/api/v1/ingest/email

Passerelle d'e-mails entrants indépendante du fournisseur. Postmark, Mailgun, SendGrid, Amazon SES, Make, n8n ou un autre adaptateur doit analyser la charge utile du fournisseur et envoyer les pièces jointes acceptées sous forme de données de formulaire multipart. DocAI n'héberge pas de boîte aux lettres et n'effectue pas d'analyse MIME propre au fournisseur.

Champ	Type		Description
`message_id`	string	obligatoire	Identifiant de message stable provenant du fournisseur
`source_namespace`	string	obligatoire	Portée fournisseur/compte stable, telle que postmark:server-123
`files`	file[]	obligatoire	Répétez pour chaque pièce jointe prise en charge
`organization_id`	string	facultatif	Espace de travail cible ; l'appelant doit disposer de l'autorisation d'importer

curl -X POST https://docai.synairo.com/api/v1/ingest/email \
  -H "Authorization: Bearer sk_docai_..." \
  -F "message_id=provider-message-42" \
  -F "source_namespace=postmark:server-123" \
  -F "organization_id=org_..." \
  -F "files=@invoice.pdf;type=application/pdf" \
  -F "files=@receipt.jpg;type=image/jpeg"

{
  "message_id": "provider-message-42",
  "source_namespace": "postmark:server-123",
  "accepted_count": 1,
  "duplicate_count": 1,
  "jobs": [
    {"job_id": "job-new", "status": "queued", "filename": "invoice.pdf", "duplicate": false},
    {"job_id": "job-old", "status": "completed", "filename": "receipt.jpg", "duplicate": true}
  ]
}

L'idempotence comprend le propriétaire authentifié, l'espace de noms fournisseur/compte, la destination, l'identifiant du message, le nom de fichier normalisé, le contenu du fichier et l'occurrence parmi les pièces jointes identiques. Les nouvelles tentatives réordonnées du fournisseur renvoient les identifiants de tâche d'origine. Une ingestion échouée peut remettre en file la même tâche avec de nouveaux octets pour un maximum de trois tentatives au total ; les tâches actives et terminées ne sont jamais traitées deux fois.

Obtenir le statut de la tâche

GET/api/v1/jobs/{job_id}

curl https://docai.synairo.com/api/v1/jobs/abc123 \
  -H "Authorization: Bearer sk_docai_..."

{
  "id": "abc123",
  "status": "completed",
  "progress_pct": 100,
  "document_type": "invoice",
  "pages_processed": 2
}

Statuts possibles : queued, processing, review_required, completed, failed, cancelled.

Obtenir le résultat de la tâche

GET/api/v1/jobs/{job_id}/result

Renvoie le résultat complet de l’extraction lorsque la tâche a le statut completed ou review_required. Le périmètre history est requis pour les clés API.

curl https://docai.synairo.com/api/v1/jobs/abc123/result \
  -H "Authorization: Bearer sk_docai_..."

Exporter en JSON

POST/api/v1/export/json

Envoyez le résultat d'extraction dans le corps JSON et obtenez un fichier d'export propre.

curl -X POST https://docai.synairo.com/api/v1/export/json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_docai_..." \
  -d '{"request_id":"...","extracted_fields":[...]}' \
  -o export.json

Exporter en CSV

POST/api/v1/export/csv

curl -X POST https://docai.synairo.com/api/v1/export/csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_docai_..." \
  -d '{"request_id":"...","extracted_fields":[...]}' \
  -o fields.csv

Exporter en XLSX

POST/api/v1/export/xlsx

Renvoie un classeur Excel avec des feuilles Résumé, Champs, Lignes d'articles, Avertissements et Métadonnées.

Lister l'historique

GET/api/v1/history

curl https://docai.synairo.com/api/v1/history \
  -H "Authorization: Bearer sk_docai_..."

Flux de révision et d’approbation

POST/api/v1/history/{record_id}/workflow

Appliquez une transition de flux contrôlée à un enregistrement sauvegardé. Cette route nécessite une session Clerk interactive : les clés API ne peuvent pas approuver de documents. Les membres d'un espace de travail peuvent réviser ; ses administrateurs peuvent approuver, demander des modifications ou rejeter. Le propriétaire d'un enregistrement personnel assume les deux rôles.

{
  "action": "approve",
  "comment": "Ready to post"
}

Actions : start_review, complete_review, reopen_review, submit_for_approval, approve, request_changes, reject et accept_partial_analysis. L'approbation valide ensemble l'événement d'audit du flux et l'événement de boîte d'envoi document.approved.

Supprimer tout l'historique

DELETE/api/v1/history

Supprime définitivement toutes les analyses enregistrées de votre compte.

Lister les clés API

GET/api/v1/keys

Créer une clé API

POST/api/v1/keys

curl -X POST https://docai.synairo.com/api/v1/keys \
  -H "Authorization: Bearer <clerk_session_token>" \
  -H "Content-Type: application/json" \
          -d '{"name": "My automation key", "scopes": "extract,history"}'

{
  "id": "...",
  "name": "My automation key",
  "key": "sk_docai_...",   // shown ONCE - save it now
  "prefix": "sk_docai_abc",
  "scopes": "extract,history",
  "created_at": "2026-06-10T12:00:00Z"
}

Révoquer une clé API

DELETE/api/v1/keys/{key_id}

Créer un webhook

POST/api/v1/webhooks

curl -X POST https://docai.synairo.com/api/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
          -d '{"name": "My webhook", "endpoint_url": "https://my.app/hook", "event_types": ["document.completed", "document.review_required", "document.approved", "document.failed"]}'

La réponse inclut un secret pour la vérification de la signature. Enregistrez-le maintenant, il ne sera plus affiché.

Types d’événements webhook

Événement	Lorsqu'il se déclenche
`document.completed`	L'extraction est terminée et le résultat a été enregistré
`document.review_required`	La validation ou le routage selon la confiance nécessite une révision humaine ; se déclenche également avec document.completed
`document.approved`	Un approbateur autorisé a validé la décision d'approbation ; utilisez cet événement pour les écritures comptables
`document.failed`	Le traitement a échoué ; les tâches ingérées par e-mail incluent des métadonnées sur la possibilité de nouvelle tentative et le nombre de tentatives

Utilisez document.approved, et non document.completed, comme point de contrôle pour enregistrer des données dans un système comptable. L'extraction peut être terminée alors que des champs nécessitent encore une correction.

Tester un webhook

POST/api/v1/webhooks/{webhook_id}/test

Vérifier la signature du webhook

Chaque livraison inclut ces en-têtes :

X-DocAI-Event. Type d'événement (par ex. document.completed)
X-DocAI-Timestamp. Horodatage UTC au format ISO 8601
X-DocAI-Signature. sha256=<hmac>

import hashlib, hmac

def verify(secret, body_str, timestamp, signature_header):
    msg = f"{timestamp}.{body_str}"
    digest = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", signature_header)

Événements durables échoués

DocAI réessaie automatiquement les livraisons sortantes. Si un événement durable de boîte d'envoi ne peut pas être développé après cinq tentatives, il devient un message non distribuable. Le propriétaire peut examiner les métadonnées sans exposer la charge utile stockée et relancer l'événement après avoir corrigé la cause.

GET/api/v1/webhook-outbox/failed

curl https://docai.synairo.com/api/v1/webhook-outbox/failed \
  -H "Authorization: Bearer sk_docai_..."

POST/api/v1/webhook-outbox/{event_id}/replay

curl -X POST https://docai.synairo.com/api/v1/webhook-outbox/EVENT_ID/replay \
  -H "Authorization: Bearer sk_docai_..."

Les mêmes contrôles sont disponibles dans Paramètres développeur → Événements nécessitant une attention. Les enregistrements de livraison et de boîte d'envoi terminaux sont conservés pendant 30 jours.

Utilisation avec Make / n8n / Zapier

Pour les importations directes, appelez /api/v1/jobs. Pour les e-mails entrants, laissez le fournisseur analyser les pièces jointes et appelez /api/v1/ingest/email avec un identifiant de message et un espace de noms source stables. Les deux routes créent les mêmes tâches persistantes et utilisent le même flux de révision.

Abonnez-vous aux événements de fin et de révision pour connaître l'état, puis utilisez document.approved pour déclencher des actions comptables aval contrôlées. Les webhooks signés éliminent la nécessité d'interroger le service.