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
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	Timeout de la réponse agent

Classification asynchrone

L’asynchrone est recommandé pour les lots volumineux ou les fichiers de nombreuses 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": "550e8400-e29b-41d4-a716-446655440000"
}

Résultat (callback et webhook)

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

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

Limites et considérations

• Formats supportés: PDF, PNG, JPG, JPEG, DOCX, XLSX
• Le mode asynchrone est recommandé pour les fichiers volumineux ou les lots de nombreuses pages, pour éviter les timeouts

Support et assistance

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