Classification

Ce document décrit comment utiliser l’API DIMARC pour classer un document en plages de pages selon des catégories métier. L’API ne découpe pas le fichier et n’émet aucun binaire : le livrable est un JSON qui indique où commence et où finit chaque catégorie.

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)

Endpoints

POST /v2/classification
POST /v2/classification/async

Cas d’usage: Trier un lot de pages scannées mêlant plusieurs types de documents (ex: factures, bons de livraison, contrats) sans les découper manuellement au préalable.

Note

Contrairement à l’Extracteur, la Classification est globale uniquement : les catégories sont fournies dans la requête, il n’existe pas de variante “agent préconfiguré”.

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 la classification terminée.

Classification synchrone

Requête

curl --location 'https://api.dimarc.ai/v2/classification' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "filename": "lot-documents.pdf",
    "file": "<base64_encoded_file>",
    "classes": [
        {
            "name": "facture",
            "description": "Facture émise par un fournisseur"
        },
        {
            "name": "bon_livraison",
            "description": "Bon de livraison accompagnant une commande"
        }
    ]
}'

Paramètres

Paramètre	Type	Description
filename	string	Nom du fichier original (avec extension)
file	string	Contenu du fichier encodé en base64
classes	array	Catégories à détecter (voir Structure des classes) — peut être vide uniquement si options.guess vaut true
options	object	Options facultatives (voir Options)

Structure des classes

Chaque élément du tableau classes est un objet avec les propriétés suivantes:

Propriété	Type	Description
name	string	Nom de la catégorie
description	string	Description de la catégorie (aide l’IA à distinguer les documents)

Options

Propriété	Type	Description
guess	boolean	Devine les catégories au lieu de s’appuyer sur classes — seul cas où classes peut être vide. Les catégories proposées sont renvoyées dans discovered_classes
per_page	boolean	Classe page par page plutôt que par plage de document (reflété dans data.mode de la réponse)
system	string	Instruction système additionnelle transmise au modèle de classification

Attention

Si classes est vide et options.guess n’est pas true, l’API renvoie 422 invalid_request.

Format de réponse synchrone

{
    "status": "success",
    "data": {
        "source_name": "lot-documents.pdf",
        "mode": "document",
        "segments": [
            {
                "start": 1,
                "end": 3,
                "label": "facture",
                "title": "Facture n°2024-001",
                "confidence": 0.92
            },
            {
                "start": 4,
                "end": 5,
                "label": "bon_livraison",
                "title": "Bon de livraison",
                "confidence": 0.87
            }
        ],
        "discovered_classes": [],
        "pages_count": 5
    },
    "metadata": {
        "filename": "lot-documents.pdf",
        "duration": 4.12,
        "tokens_consumed": 1,
        "thread_id": "01J..."
    }
}

Note

start/end sont 1-indexés et inclusifs : ce sont les numéros de page tels que vus dans le document. confidence est la confiance minimale des pages du segment — un segment ne vaut pas mieux que sa page la plus douteuse. discovered_classes n’est rempli qu’en mode options.guess — vide sinon.

En cas d’erreur

{
    "status": "error",
    "code": "classification_failed",
    "error": "Classification 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.

Codes d’erreur

Status	Code	Cas
422	invalid_request	Corps de requête invalide, ou classes vide sans options.guess
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
413	file_too_large	Fichier de plus de 36 Mo ; detail porte limit et size en octets
422	infected_file	Fichier rejeté par l’antivirus
503	antivirus_unavailable	Service antivirus indisponible
503	agent_unavailable	File de traitement indisponible
502	classification_failed	L’agent n’a pas pu traiter la classification
504	agent_timeout	Délai de traitement dépassé (120 s en synchrone, 5 min en asynchrone)

Classification asynchrone

L’asynchrone porte le délai de traitement à 5 min (120 s en synchrone) : c’est le mode à utiliser dès quelques dizaines de pages.

Requête

curl --location 'https://api.dimarc.ai/v2/classification/async' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "filename": "lot-documents.pdf",
    "file": "<base64_encoded_file>",
    "classes": [
        {
            "name": "facture",
            "description": "Facture émise par un fournisseur"
        }
    ],
    "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
classes	array	Catégories à détecter — mêmes règles qu’en synchrone
options	object	Options facultatives (voir Options)
callback	string	URL du webhook qui recevra le résultat

Réponse immédiate

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

Relire un résultat

Le classification_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.

Résultat (callback et webhook)

Lorsque la classification est terminée, le résultat est envoyé à l’URL de callback.

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 classification.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",
    "classification_id": "01K74Z3Q8RVN5XW2B6JHMTGD9C",
    "data": {
        "source_name": "lot-documents.pdf",
        "mode": "document",
        "segments": [
            {
                "start": 1,
                "end": 3,
                "label": "facture",
                "title": "Facture n°2024-001",
                "confidence": 0.92
            }
        ],
        "discovered_classes": [],
        "pages_count": 3
    },
    "metadata": {
        "filename": "lot-documents.pdf",
        "duration": 4.12,
        "tokens_consumed": 1,
        "thread_id": "01J..."
    }
}

En cas d’erreur

{
    "status": "error",
    "classification_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).

Limites et considérations

• Format supporté : PDF uniquement
• Taille maximale du fichier : 36 Mo (413 file_too_large au-delà, avant tout traitement, en synchrone comme en asynchrone)
• Délai de traitement : 120 s en synchrone, 5 min 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
• Documents volumineux : au-delà de 5 min de traitement (plusieurs centaines de pages), découpez le PDF en lots de 30 à 50 pages, un appel asynchrone par lot, puis réassemblez les segments en décalant start et end de l’offset du lot
• Classes : pas de limite de nombre ; gardez des descriptions courtes, elles sont injectées dans chaque appel modèle. options.system est limité à 4000 caractères
• 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 Classification, contactez notre équipe de support à l’adresse contact@dimarc.fr