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:

Cliquez en haut à droite sur l’icône de votre profil puis accédez à la section Organisation > API ou en cliquant ici
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:

Synchrone: La requête est traitée immédiatement et la réponse est retournée dans la même connexion HTTP.
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
    }
}

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.

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
    }
}

En cas d’erreur

{
    "extract_id": "550e8400-e29b-41d4-a716-446655440000",
    "error": "Extraction failed: Unable to process the document",
    "detail": "HTTP status: 500"
}

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`, 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

{
    "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": "text",
            "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"
                }
            ]
        }
    ]
}

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

Extracteur

Prérequis

Deux approches d’extraction

1. Extracteur Global

2. Extracteur avec Agent

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

Configurer les modèles d’extraction

Modes de traitement

Extraction synchrone

Approche 1: Extracteur Global (Synchrone)

Requête

Paramètres

Approche 2: Extracteur avec Agent (Synchrone)

Requête

Paramètres

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

Extraction asynchrone

Approche 1: Extracteur Global (Asynchrone)

Requête

Paramètres

Approche 2: Extracteur avec Agent (Asynchrone)

Requête

Paramètres

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

Format de la réponse au webhook

En cas de succès

En cas d’erreur

Structure des paramètres

Types de formats supportés

1. Types simples

2. Listes (format list)

Exemple complet de schéma

Comparaison des approches

Quelle approche choisir ?

Limites et considérations

Support et assistance

2. Listes (format `list`)