Premiers pas

Bienvenue sur l'API Koncile

Ce guide vous accompagne dans le processus complet de configuration, de la génération d'une clé API à l'extraction de données de votre premier document.

Étape 1 : Générer votre clé API

Les clés API sont générées depuis l'application web Koncile.

1. Connectez-vous à votre compte Koncile sur app.koncile.ai

   • Si vous n'avez pas de compte Koncile, créez-en un

2. Naviguez vers Paramètres > API

3. Cliquez sur Générer une clé API

4. Copiez et stockez votre clé API en lieu sûr

La clé API n'est affichée qu'une seule fois. Stockez-la en lieu sûr (par exemple, dans des variables d'environnement ou un gestionnaire de secrets). Si vous la perdez, vous devrez en générer une nouvelle.

Seuls les administrateurs de l'entreprise peuvent générer des clés API. Si vous ne voyez pas les paramètres API, contactez l'administrateur de votre entreprise.

---

Étape 2 : Vérifier votre clé API

Avant de continuer, vérifiez que votre clé API fonctionne :

curl -X POST "https://api.koncile.ai/v1/check_api_key" \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponse attendue :

{"success": true}

Si vous recevez une erreur, vérifiez que :

• Votre clé API est correcte et complète

• L'en-tête Authorization utilise le format Bearer YOUR_API_KEY

• Votre clé API n'a pas été révoquée

---

Étape 3 : Créer votre configuration d'extraction

Créez une configuration d'extraction complète avec un Folder, un Template, des Fields et des Instructions.

Pour des clarifications sur les concepts d'extraction, consultez "Comprendre la structure de Koncile".

3.1 Créer un Folder

Les Folders aident à organiser les Templates par type de document ou objectif métier.

curl -X POST "https://api.koncile.ai/v1/create_folder" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Factures fournisseurs",
    "desc": "Factures reçues des fournisseurs"
  }'

Réponse :

{
    "id": 1,
    "name": "Factures fournisseurs",
    "desc": "Factures reçues des fournisseurs",
    "templates": []
}

Conservez la valeur id — vous en aurez besoin pour créer des Templates.

3.2 Créer un Template

Les Templates définissent quelles données extraire des documents. Chaque Template appartient à un Folder.

curl -X POST "https://api.koncile.ai/v1/create_template" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Facture standard",
    "desc": "Template pour les factures fournisseurs standard",
    "type": "invoice",
    "folder_id": 1
  }'

3.3 Créer des Fields

Les Fields définissent quels points de données extraire. Créez à la fois des General fields et des Line fields.

General Fields (extraits une fois par document) :

# Créer le field Numéro de facture
curl -X POST "https://api.koncile.ai/v1/create_field" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Numéro de facture",
    "type": "General fields",
    "format": "text",
    "template_id": 1,
    "desc": "L identifiant unique de cette facture"
  }'

# Créer le field Date de facture
curl -X POST "https://api.koncile.ai/v1/create_field" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Date de facture",
    "type": "General fields",
    "format": "date",
    "template_id": 1,
    "desc": "La date d émission de la facture"
  }'

Line Fields (extraits pour chaque ligne) :

line_fields = [
    {
        "name": "Description produit",
        "type": "Line fields",
        "format": "text",
        "template_id": template_id,
        "desc": "Description du produit ou service"
    },
    {
        "name": "Quantité",
        "type": "Line fields",
        "format": "number",
        "template_id": template_id,
        "desc": "Nombre d unités"
    },
    {
        "name": "Prix unitaire",
        "type": "Line fields",
        "format": "number",
        "template_id": template_id,
        "desc": "Prix par unité"
    },
    {
        "name": "Total ligne",
        "type": "Line fields",
        "format": "number",
        "template_id": template_id,
        "desc": "Montant total pour cette ligne (quantité × prix unitaire)"
    }
]

for field in line_fields:
    response = requests.post(...)

Le champ desc est important — il aide l'IA à comprendre exactement quoi extraire, surtout pour les fields ambigus.

3.4 Créer des Instructions (Optionnel)

Les Instructions fournissent du contexte pour aider l'outil à extraire les données plus précisément. Utilisez-les pour :

• Exclure des informations spécifiques (certaines pages du document, lignes de total en fin de tableau)

• Donner du contexte supplémentaire à l'IA

instructions = [
    {
        "content": "",
        "type": "General fields",
        "template_id": template_id
    },
    {
        "content": "Pour les montants en devise, extraire la valeur numérique sans les symboles de devise.",
        "type": "General fields",
        "template_id": template_id
    }
]

for instruction in instructions:
    response = requests.post(...)

---

Étape 4 : Télécharger un document

Maintenant que votre configuration d'extraction est complète, vous pouvez télécharger des documents.

curl -X POST "https://api.koncile.ai/v1/upload_file/?folder_id=1&template_id=1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

response = requests.post(
    "https://api.koncile.ai/v1/upload_file/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"files": open("facture.pdf", "rb")},
    params={
        "folder_id": folder_id,
        "template_id": template_id
    }
)
result = response.json()
task_id = result["task_ids"][0]
print(f"Téléchargement réussi ! Task ID : {task_id}")

Réponse :

{
    "task_ids": ["EOBdOSUX4Uv57YWsLYc4JQ"]
}

Le slash final dans /upload_file/ est obligatoire.

Auto-classification : Si vous omettez folder_id et template_id, Koncile classifiera automatiquement le document et sélectionnera le Template le plus approprié.

---

Étape 5 : Récupérer les résultats d'extraction

L'extraction se fait de manière asynchrone. Interrogez le statut de la tâche jusqu'à ce qu'elle soit terminée :

import time

def wait_for_extraction(task_id, api_key, timeout=300):
    url = "https://api.koncile.ai/v1/fetch_tasks_results"
    headers = {"Authorization": f"Bearer {api_key}"}
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(url, headers=headers, params={"task_id": task_id})
        result = response.json()

        print(f"Statut : {result['status']}")

        if result["status"] == "DONE":
            return result
        elif result["status"] == "FAILED":
            raise Exception(f"Extraction échouée : {result['status_message']}")

        time.sleep(2)

    raise TimeoutError("Délai d'extraction dépassé")

# Attendre les résultats
result = wait_for_extraction(task_id, "YOUR_API_KEY")

# Afficher les données extraites
print(f"\nDocument ID : {result['document_id']}")
print(f"Nom du document : {result['document_name']}")

print("\n--- General Fields ---")
for field_name, data in result["General_fields"].items():
    print(f"{field_name} : {data['value']} (confiance : {data['confidence_score']:.2f})")

print("\n--- Lignes ---")
line_fields = result["Line_fields"]
if line_fields:
    num_lines = len(list(line_fields.values())[0])
    for i in range(num_lines):
        print(f"\nLigne {i + 1} :")
        for field_name, values in line_fields.items():
            print(f"  {field_name} : {values[i]['value']}")

Exemple de réponse une fois terminée :

{
    "status": "DONE",
    "status_message": "Extraction completed successfully",
    "child_task_ids": null,
    "task_id": "EOBdOSUX4Uv57YWsLYc4JQ",
    "document_id": 12345,
    "document_name": "facture.pdf",
    "General_fields": {
        "Numéro de facture": {
            "value": "INV-2024-0042",
            "confidence_score": 0.98
        },
        "Date de facture": {
            "value": "2024-01-15",
            "confidence_score": 0.95
        }
    },
    "Line_fields": {
        "Description produit": [
            {"value": "Widget Pro X100", "confidence_score": 0.94}
        ],
        "Quantité": [
            {"value": "10", "confidence_score": 0.99}
        ]
    }
}

---

Script d'exemple complet

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.koncile.ai/v1"

def api_request(method, endpoint, **kwargs):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    if "json" in kwargs:
        headers["Content-Type"] = "application/json"

    response = requests.request(
        method,
        f"{BASE_URL}/{endpoint}",
        headers=headers,
        **kwargs
    )
    response.raise_for_status()
    return response.json()

# Étape 1 : Créer un folder
folder = api_request("POST", "create_folder", json={
    "name": "Factures fournisseurs",
    "desc": "Factures des fournisseurs"
})
folder_id = folder["id"]
print(f"Folder créé : {folder_id}")

# Étape 2 : Créer un template
template = api_request("POST", "create_template", json={
    "name": "Facture standard",
    "type": "invoice",
    "folder_id": folder_id
})
template_id = template["id"]
print(f"Template créé : {template_id}")

# Étape 3 : Créer des fields
fields = [
    {"name": "Numéro de facture", "type": "General fields", "format": "text"},
    {"name": "Date de facture", "type": "General fields", "format": "date"},
    {"name": "Montant total", "type": "General fields", "format": "number"},
    {"name": "Produit", "type": "Line fields", "format": "text"},
    {"name": "Quantité", "type": "Line fields", "format": "number"},
    {"name": "Prix", "type": "Line fields", "format": "number"},
]

for field in fields:
    result = api_request("POST", "create_field", json={**field, "template_id": template_id})
    print(f"Field créé : {field['name']}")

# Étape 4 : Créer une instruction
api_request("POST", "create_instruction", json={
    "content": "Extraire les dates au format AAAA-MM-JJ",
    "type": "General fields",
    "template_id": template_id
})
print("Instruction créée")

# Étape 5 : Télécharger un document
with open("facture.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/upload_file/",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"files": f},
        params={"folder_id": folder_id, "template_id": template_id}
    )
task_id = response.json()["task_ids"][0]
print(f"Document téléchargé, task ID : {task_id}")

# Étape 6 : Attendre les résultats
while True:
    result = api_request("GET", "fetch_tasks_results", params={"task_id": task_id})

    if result["status"] == "DONE":
        print("\nExtraction terminée !")
        print(f"Document ID : {result['document_id']}")
        for name, data in result["General_fields"].items():
            print(f"{name} : {data['value']}")
        break
    elif result["status"] == "FAILED":
        print(f"Échec : {result['status_message']}")
        break

    print(f"Statut : {result['status']}...")
    time.sleep(2)

---

Prochaines étapes

Maintenant que vous comprenez les bases, explorez ces sujets :

• File Uploading - Téléchargements par lot, metadata et contraintes de fichiers

• Task Retrieval - Format de réponse détaillé et stratégies de polling

• Gestion des documents - Lister, télécharger et supprimer des documents

• Folders, Templates, Fields & Instructions - Référence API complète

• API Status Codes - Gestion des erreurs et dépannage

• SDK Libraries - SDKs Python et Node.js pour une intégration plus facile