Authentification

Chaque appel porte la clé API du cabinet dans l’en-tête Authorization, sous la forme Bearer <clé API>. Les clés se créent depuis Administration > Connecteurs & logiciels.

Une clé Kontia commence par kontia_, suivi de 64 caractères hexadécimaux. Elle n’est affichée qu’une fois, à sa création : seule son empreinte est conservée.

L’en-tête X-API-Key reste accepté, sans le préfixe Bearer.

bash

# Jeton Bearer (recommandé)
curl -H "Authorization: Bearer kontia_votre_cle" \
  https://kontia.fr/api/v1/dossiers

# En-tête X-API-Key (équivalent)
curl -H "X-API-Key: kontia_votre_cle" \
  https://kontia.fr/api/v1/dossiers

Une clé API ne se partage pas. Ne la placez ni dans du code exécuté par un navigateur, ni dans un dépôt public. Les appels se font depuis votre serveur.

Limites de débit

Type de limite	Limite	Fenêtre
Par clé API	30 requêtes	1 minute glissante
Par adresse IP (toutes routes)	100 requêtes	1 minute glissante

Le quota mensuel de requêtes IA dépend du plan du cabinet :

Plan	Requêtes IA par mois
Essentiel	500
Professionnel	2 500
Premium	10 000
Entreprise	999 999

Au-delà de la limite, l’API répond 429. La route GET /api/v1/usage donne la consommation du mois en cours et le quota du plan.

Exemples de code

javascript

const API_KEY = 'kontia_votre_cle';
const BASE = 'https://kontia.fr/api/v1';
const auth = { Authorization: 'Bearer ' + API_KEY };

// Lister les dossiers
const res = await fetch(BASE + '/dossiers?page=1&limit=10', { headers: auth });
const { data, meta } = await res.json();
console.log(meta.total + ' dossiers');

// Creer un dossier
const create = await fetch(BASE + '/dossiers', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'SARL Dupont', siren: '123456789' }),
});
const { data: nouveauDossier } = await create.json();

// Interroger l'assistant
const chat = await fetch(BASE + '/chat', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Quel est le taux de TVA applicable aux prestations de services ?',
    model: 'sonnet',
  }),
});
const { data: reponse } = await chat.json();
console.log(reponse.response);

Webhooks

Un webhook prévient votre système dès qu’un événement se produit dans Kontia. Enregistrez une URL en HTTPS et choisissez les événements à recevoir.

Événements disponibles

Événement	Description
`dossier.created`	Un dossier vient d’être créé
`invoice.created`	Une facture vient d’être créée
`document.uploaded`	Un document vient d’être déposé
`chat.completed`	Une réponse de l’assistant vient d’être produite

Vérification de la signature

Each webhook delivery includes an X-Kontia-Signature header contenant la signature HMAC-SHA256 du corps de la requête, calculée avec le secret remis à la création. Vérifiez-la avant de traiter l’événement.

javascript

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Dossiers

Chat IA

Documents

Facturation

Utilisateurs

Usage

Webhooks

Format des réponses

Toutes les réponses sont en JSON. Une réponse réussie porte un champ data. Les routes de liste ajoutent un objet meta de pagination. Chaque réponse porte un en-tête X-Request-Id qui identifie l’appel dans les journaux.

Succès (2xx)

json

{
  "data": { ... },
  "meta": { "total": 42, "page": 1, "limit": 20 }
}

Erreur (4xx/5xx)

json

{
  "error": "Ce qui n’a pas fonctionné, et quoi faire"
}