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

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.

Attention

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

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
callback	string	URL du webhook qui recevra les résultats

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

{
    "status": "started",
    "extract_id": "550e8400-e29b-41d4-a716-446655440000"
}

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 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": "550e8400-e29b-41d4-a716-446655440000",
    "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": "550e8400-e29b-41d4-a716-446655440000",
    "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).

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
• Formats supportés: PDF, PNG, JPG, JPEG, DOCX, XLSX
• Temps moyen d’extraction: 5 à 10 secondes pour des documents standards (sans trop d’imagerie)
• Le mode asynchrone est fortement recommandé pour les fichiers > 20 Mo

Support et assistance

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