Extracteur

Ce document décrit comment utiliser l’API DIMARC pour interagir avec les endpoints d’extraction. L’API offre deux approches pour extraire des données structurées de documents.

Prérequis

• Un compte DIMARC actif.
• Être administrateur de votre organisation.
• Votre token d’authentification x-api-key (voir Récupération de votre Token d’Authentification)

Deux approches d’extraction

L’API Extracteur propose deux méthodes d’utilisation selon vos besoins:

1. Extracteur Global

L’extracteur global permet de définir le schéma d’extraction directement dans la requête API, sans nécessiter de configuration préalable d’un agent.

Endpoints:

POST /v2/extractor
POST /v2/extractor/async

Cas d’usage: Idéal pour des extractions ponctuelles, des tests, ou lorsque vous souhaitez définir dynamiquement le schéma d’extraction sans passer par l’interface Dimarc.

2. Extracteur avec Agent

L’extracteur avec agent utilise des modèles d’extraction préconfigurés dans l’interface Dimarc. Cette approche est recommandée pour des extractions répétitives avec le même schéma.

Endpoints:

POST /v2/extractor/:agentReference
POST /v2/extractor/async/:agentReference

Cas d’usage: Recommandé pour des cas d’usage en production où vous avez des modèles d’extraction standardisés et réutilisables.

Récupérer la référence d’un agent

Pour utiliser l’extracteur avec agent, vous devez d’abord récupérer la référence de votre agent:

1. Cliquez en haut à droite sur l’icône de votre profil puis accédez à la section Organisation > API ou en cliquant ici
2. Dans la section Références de vos agents, vous pouvez récupérer la référence de l’agent Extracteur que vous souhaitez utiliser.

Configurer les modèles d’extraction

Les modèles d’extraction sont configurés dans l’interface Dimarc. Pour ajouter un nouveau modèle, rendez-vous sur votre tableau de bord: https://app.dimarc.ai

Rendez-vous dans la configuration de votre agent Extracteur et ajoutez un nouveau modèle en définissant les champs à extraire.

Modes de traitement

Chaque approche (Global et Agent) offre deux modes de traitement:

1. Synchrone: La requête est traitée immédiatement et la réponse est retournée dans la même connexion HTTP.
2. Asynchrone: Le traitement est mis en file d’attente et les résultats sont envoyés à un webhook défini une fois l’extraction terminée.

Extraction synchrone

L’extraction synchrone est idéale pour des traitements rapides ou lorsque votre application attend directement le résultat.

Approche 1: Extracteur Global (Synchrone)

Cette méthode permet de définir le schéma d’extraction directement dans la requête.

Requête

curl --location 'https://api.dimarc.ai/v2/extractor' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "filename": "facture.pdf",
    "file": "<base64_encoded_file>",
    "params": [
        {
            "name": "invoice_number",
            "format": "text",
            "description": "Numéro de facture"
        },
        {
            "name": "total_amount",
            "format": "number",
            "description": "Montant total TTC"
        },
        {
            "name": "products",
            "format": "list",
            "description": "Liste des produits",
            "items": [
                {
                    "name": "product_name",
                    "format": "text",
                    "description": "Nom du produit"
                },
                {
                    "name": "quantity",
                    "format": "number",
                    "description": "Quantité"
                }
            ]
        }
    ]
}'

Paramètres

Paramètre	Type	Description
filename	string	Nom du fichier original (avec extension)
file	string	Contenu du fichier encodé en base64
params	array	Tableau définissant le schéma d’extraction (voir Structure des paramètres)

Approche 2: Extracteur avec Agent (Synchrone)

Cette méthode utilise un agent préconfiguré avec un schéma d’extraction défini dans l’interface Dimarc.

Requête

curl --location 'https://api.dimarc.ai/v2/extractor/<agent_reference>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "filename": "facture.pdf",
    "file": "<base64_encoded_file>"
}'

Paramètres

Paramètre	Type	Description
filename	string	Nom du fichier original (avec extension)
file	string	Contenu du fichier encodé en base64
thread_id	string	(Optionnel) Rattache l’extraction à un thread existant — celui rendu dans metadata.thread_id d’un appel précédent. Le thread doit appartenir à cet agent, sinon 404 thread_not_found

Format de réponse synchrone (commune aux deux approches)

{
    "status": "success",
    "data": [
      {
        "invoice_number": "INV-2024-001",
        "total_amount": 1250.50,
        "products": [
            {
                "product_name": "Produit A",
                "quantity": 2
            },
            {
                "product_name": "Produit B",
                "quantity": 1
            }
        ]
      },
    ],
    "metadata": {
        "filename": "facture.pdf",
        "duration": 3.45,
        "tokens_consumed": 1,
        "thread_id": "01J..."
    }
}

En cas d’erreur

{
    "status": "error",
    "code": "extraction_failed",
    "error": "Extraction stream failed",
    "detail": { }
}

code est un identifiant machine stable — error reste un message humain qui peut évoluer sans préavis. detail est optionnel et absent la plupart du temps. Voir le tableau des codes d’erreur pour l’ensemble des codes possibles.

Un document que le moteur a traité sans rien pouvoir en extraire répond 422 no_data_extracted. Ce n’est pas une panne : le soumettre à nouveau à l’identique produira le même résultat.

Attention

Ne pilotez jamais votre logique sur le texte de error — utilisez code.

Codes d’erreur

Status	Code	Cas
401	unauthorized	En-tête x-api-key manquant ou invalide
403	forbidden	Accès API désactivé pour votre organisation
404	agent_not_found	Agent introuvable, mauvais type, privé, ou hors de votre organisation (extracteur avec agent)
404	thread_not_found	thread_id fourni introuvable pour cet agent
413	file_too_large	Fichier de plus de 36 Mo ; detail porte limit et size en octets
422	invalid_request	Corps de requête invalide : base64, params, ou champ inconnu (thread_id n’existe que sur l’extracteur avec agent)
422	infected_file	Fichier rejeté par l’antivirus
422	no_data_extracted	Document traité, aucune donnée exploitable à en tirer
429	rate_limit_exceeded	Plus de 100 requêtes par minute ; Retry-After porte les secondes avant la prochaine fenêtre
429	spending_limit_reached	Plafond de dépense de l’organisation atteint
429	concurrent_limit_exceeded	Plus de 4 traitements simultanés pour l’organisation, synchrones et asynchrones confondus ; Retry-After porte les secondes avant de réessayer
429	queue_saturated	Le moteur de traitement est saturé ; Retry-After porte les secondes avant de réessayer
500	internal_error	Erreur interne inattendue
502	extraction_failed	L’agent n’a pas pu traiter l’extraction
503	agent_unavailable	File de traitement indisponible
503	antivirus_unavailable	Service antivirus indisponible
504	agent_timeout	Délai de traitement dépassé (120 s)

En asynchrone, seuls les refus antérieurs à la mise en file sortent en HTTP — 401, 403, 404 agent_not_found, 413, 422 invalid_request et les quatre 429. Tout ce qui survient pendant le traitement part dans le callback et l’événement extraction.completed, avec le même code et detail.http_status.

Extraction asynchrone

L’extraction asynchrone est recommandée pour:

• Les documents volumineux
• Les extractions complexes nécessitant plus de temps
• Les systèmes qui ne peuvent pas attendre une réponse immédiate

Approche 1: Extracteur Global (Asynchrone)

Cette méthode permet de définir le schéma d’extraction directement dans la requête.

Requête

curl --location 'https://api.dimarc.ai/v2/extractor/async' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "filename": "facture.pdf",
    "file": "<base64_encoded_file>",
    "callback": "https://votre-endpoint-de-callback.com/webhook",
    "params": [
        {
            "name": "invoice_number",
            "format": "text",
            "description": "Numéro de facture"
        },
        {
            "name": "total_amount",
            "format": "number",
            "description": "Montant total TTC"
        }
    ]
}'

Paramètres

Paramètre	Type	Description
filename	string	Nom du fichier original (avec extension)
file	string	Contenu du fichier encodé en base64
callback	string	URL du webhook qui recevra les résultats
params	array	Tableau définissant le schéma d’extraction (voir Structure des paramètres)

Approche 2: Extracteur avec Agent (Asynchrone)

Cette méthode utilise un agent préconfiguré avec un schéma d’extraction défini dans l’interface Dimarc.

Requête

curl --location 'https://api.dimarc.ai/v2/extractor/async/<agent_reference>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "filename": "facture.pdf",
    "file": "<base64_encoded_file>",
    "callback": "https://votre-endpoint-de-callback.com/webhook"
}'

Paramètres

Paramètre	Type	Description
filename	string	Nom du fichier original (avec extension)
file	string	Contenu du fichier encodé en base64
thread_id	string	(Optionnel) Rattache l’extraction à un thread existant — celui rendu dans metadata.thread_id d’un appel précédent. Le thread doit appartenir à cet agent, sinon 404 thread_not_found
callback	string	URL du webhook qui recevra les résultats

Réponse immédiate (commune aux deux approches)

{
    "status": "started",
    "extract_id": "01K74Z3Q8RVN5XW2B6JHMTGD9C"
}

Relire un résultat

Le extract_id est l’identifiant du traitement. Tant que vous n’avez pas reçu le callback, ou si votre endpoint était indisponible, relisez le résultat avec cet identifiant :

curl --location 'https://api.dimarc.ai/v2/turns/01K74Z3Q8RVN5XW2B6JHMTGD9C' \
--header 'x-api-key: <your_api_key>'

Status	Corps
200	L’événement de fin, identique à celui du callback (status: "success" ou "error") ; pour un traitement synchrone réussi, le corps de sa réponse
422, 502, 504	Traitement synchrone en échec : le code et le corps d’erreur de sa réponse d’origine
202	{ "status": "running", "turn_id": "…" } — le traitement n’est pas terminé, ou son résultat est en cours de remise ; réessayez dans quelques secondes
404	turn_not_found — identifiant inconnu, expiré, ou appartenant à une autre organisation

Le résultat reste lisible au moins 7 jours.

Format de la réponse au webhook

Lorsque l’extraction est terminée, les résultats sont envoyés à l’URL de callback spécifiée.

Le callback est appelé en POST avec le même corps JSON que l’événement. Si votre organisation a configuré un webhook pour cet événement, la requête porte l’en-tête x-dimarc-signature: sha256=…, à vérifier avec le secret de ce webhook ; sans webhook configuré, elle n’est pas signée. Chaque essai attend 10 s au plus ; sur 429, 5xx ou erreur réseau, la livraison est retentée après 1 s, 10 s puis 60 s. Une même livraison pouvant arriver deux fois, dédoublonnez côté client.

Le même résultat est aussi disponible via l’événement extraction.completed si vous avez configuré un webhook d’organisation — utile pour centraliser la réception sans dépendre du callback par requête.

En cas de succès

{
    "status": "success",
    "extract_id": "01K74Z3Q8RVN5XW2B6JHMTGD9C",
    "data": [
        {
            "invoice_number": "INV-2024-001",
            "total_amount": 1250.50
        }
    ],
    "metadata": {
        "filename": "facture.pdf",
        "duration": 3.45,
        "tokens_consumed": 1,
        "thread_id": "01J..."
    }
}

En cas d’erreur

{
    "status": "error",
    "extract_id": "01K74Z3Q8RVN5XW2B6JHMTGD9C",
    "code": "agent_timeout",
    "error": "Agent response timed out",
    "detail": { "http_status": 504 }
}

detail est un objet — http_status est un nombre. code porte le vrai code machine de l’erreur (voir le tableau des codes d’erreur). Un http_status sous 500, comme 422 pour no_data_extracted, décrit le document soumis, pas une panne.

Attention

Si votre parsing extrait le status HTTP depuis une string detail (ancien format), il cassera — lisez detail.http_status directement.

Structure des paramètres

Lorsque vous utilisez l’extracteur global, vous devez définir le schéma d’extraction via le paramètre params. Chaque élément du tableau params est un objet avec les propriétés suivantes:

Propriété	Type	Description
name	string	Nom du champ à extraire
format	string	Type de données: text, number, boolean, date, ou list
description	string	Description claire du champ à extraire (aide l’IA à comprendre)
items	array	(Requis uniquement pour format: "list") Tableau des sous-champs à extraire pour chaque élément de la liste

Types de formats supportés

1. Types simples

Pour les valeurs scalaires, utilisez:

• text: Pour du texte, des chaînes de caractères
• number: Pour des valeurs numériques
• boolean: Pour des valeurs vraies/fausses
• date: Pour des dates, renvoyées au format YYYY-MM-DD (best-effort : la forme exacte dépend du modèle, elle n’est pas normalisée)

{
    "name": "invoice_number",
    "format": "text",
    "description": "Numéro de facture"
}

2. Listes (format list)

Pour les données complexes comme les tableaux, séries d’articles, etc., utilisez le format list et définissez les sous-éléments dans le tableau items:

{
    "name": "products",
    "format": "list",
    "description": "Liste des produits dans la facture",
    "items": [
        {
            "name": "product_name",
            "format": "text",
            "description": "Nom du produit"
        },
        {
            "name": "quantity",
            "format": "number",
            "description": "Quantité commandée"
        },
        {
            "name": "unit_price",
            "format": "number",
            "description": "Prix unitaire HT"
        }
    ]
}

Exemple complet de schéma

{
    "params": [
        {
            "name": "invoice_number",
            "format": "text",
            "description": "Numéro de facture"
        },
        {
            "name": "invoice_date",
            "format": "date",
            "description": "Date d'émission de la facture"
        },
        {
            "name": "total_ht",
            "format": "number",
            "description": "Montant total HT"
        },
        {
            "name": "total_ttc",
            "format": "number",
            "description": "Montant total TTC"
        },
        {
            "name": "is_paid",
            "format": "boolean",
            "description": "La facture est-elle payée?"
        },
        {
            "name": "products",
            "format": "list",
            "description": "Liste des produits facturés",
            "items": [
                {
                    "name": "designation",
                    "format": "text",
                    "description": "Désignation du produit ou service"
                },
                {
                    "name": "quantity",
                    "format": "number",
                    "description": "Quantité"
                },
                {
                    "name": "unit_price",
                    "format": "number",
                    "description": "Prix unitaire HT"
                }
            ]
        }
    ]
}

Attention

Les fichiers volumineux (>20 Mo) ou les extractions très complexes devraient toujours utiliser le mode asynchrone pour éviter les timeouts.

Comparaison des approches

Critère	Extracteur Global	Extracteur avec Agent
Configuration	Schéma défini dans la requête API	Schéma préconfiguré dans l’interface Dimarc
Flexibilité	⭐⭐⭐ Très flexible, schéma différent à chaque requête	⭐ Schéma fixe, nécessite une modification via l’interface
Maintenance	⚠️ Schéma géré côté code client	✅ Schéma centralisé
Cas d’usage	Tests, extractions ponctuelles, intégrations dynamiques	Production, extractions répétitives, processus standardisés
Réutilisabilité	❌ Chaque client doit définir le schéma	✅ Schéma partagé entre différents systèmes
Complexité requête	Plus volumineuse (inclut le schéma)	Plus légère (seulement le fichier)

Quelle approche choisir ?

Choisissez l’Extracteur Global si:

• Vous faites des tests ou du prototypage
• Vous avez besoin de schémas d’extraction différents pour chaque document
• Vous voulez une intégration rapide sans configuration préalable
• Votre cas d’usage est ponctuel ou exploratoire

Choisissez l’Extracteur avec Agent si:

• Vous êtes en production avec des processus répétitifs
• Vous extrayez toujours les mêmes types de données
• Vous souhaitez centraliser la gestion des schémas d’extraction
• Plusieurs systèmes doivent utiliser le même schéma d’extraction
• Vous voulez un meilleur suivi et une meilleure traçabilité

Limites et considérations

• Taille maximale du fichier: 36 Mo. Au-delà, la requête est refusée en 413 file_too_large avant tout traitement, en synchrone comme en asynchrone ; detail porte limit et size en octets
• Formats supportés: PDF, PNG, JPG, JPEG, DOCX, XLSX
• Temps moyen d’extraction: 5 à 10 secondes pour des documents standards (sans trop d’imagerie)
• Délai de traitement : 120 s, en synchrone comme en asynchrone. Au-delà, 504 agent_timeout (ou un événement status: "error" en asynchrone) ; le document est alors à renvoyer. En asynchrone, un traitement interrompu par une panne est rejoué une fois tant que son délai court
• Le mode asynchrone est fortement recommandé pour les fichiers > 20 Mo
• Simultanéité : 4 traitements au plus par organisation, synchrones et asynchrones confondus — un appel asynchrone occupe sa place jusqu’à la fin réelle du traitement, pas jusqu’à la réponse HTTP, et la libère dès que le résultat est conservé, sans attendre les retries du callback. Au-delà, 429 concurrent_limit_exceeded avec Retry-After ; rien n’est mis en file, réessayez quand un traitement se termine. Si le moteur est saturé, 429 queue_saturated avec Retry-After : réessayez après ce délai
• Débit : 100 requêtes par minute par clé, Retry-After sur 429

Support et assistance

Pour toute question concernant l’API Extracteur, contactez notre équipe de support à l’adresse contact@dimarc.fr