API Kountabl

Authentification

Générez une clé API dans Paramètres > Administration > API. Chaque clé commence par le préfixe mk_live_ et est liée à votre entreprise.

Envoyez la clé dans le header Authorization :

Authorization: Bearer mk_live_your_api_key_here

Exemple cURL

curl -H"Authorization: Bearer mk_live_your_key" \
 https://kountabl.com/api/v1/invoices

Exemple JavaScript

const res = await fetch('https://kountabl.com/api/v1/invoices', {
 headers: {
 'Authorization': 'Bearer mk_live_your_key',
 'Content-Type': 'application/json',
 },
});

const { data, meta } = await res.json();
console.log(data); // Array of invoices
console.log(meta); // { page, per_page, total, total_pages }

Rate Limiting

L'API est limitée à 100 requêtes par minute par clé API. Les headers suivants sont inclus dans chaque réponse :

Endpoints

Tous les endpoints suivent le format /api/v1/{entity}. Les réponses utilisent une enveloppe standard avec data et meta.

Factures (Invoices)

Exemple de réponse

{
"data": [
 {
"id":"a1b2c3d4-...",
"invoice_number":"2026-0001",
"status":"final",
"issue_date":"2026-03-01",
"due_date":"2026-04-01",
"buyer_name":"ACME SARL",
"total_ht":"5000.00",
"created_at":"2026-03-01T10:00:00Z"
 }
 ],
"meta": {
"page": 1,
"per_page": 20,
"total": 42,
"total_pages": 3
 }
}

Clients

Devis (Quotes)

Recettes (Revenue)

Dépenses (Expenses)

Webhooks

Les webhooks vous permettent de recevoir des notifications en temps reel lorsqu'un événement se produit dans votre compte Kountabl.

Enregistrement

Enregistrez un endpoint webhook via l'API :

curl -X POST https://kountabl.com/api/v1/webhooks \
 -H"Authorization: Bearer mk_live_your_key" \
 -H"Content-Type: application/json" \
 -d '{
"url":"https://your-server.com/webhooks/kountabl",
"events": ["invoice.created","invoice.paid"]
 }'

Gestion des webhooks

Types d'événements

Format du payload

{
"event":"invoice.created",
"timestamp":"2026-03-23T10:00:00.000Z",
"data": {
"id":"a1b2c3d4-...",
"invoice_number":"2026-0001",
"status":"final",
"total_ht":"5000.00",
"issue_date":"2026-03-01"
 },
"idempotency_key":"f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Vérification de signature

Chaque requête webhook inclut un header X-Mokawil-Signature contenant un HMAC-SHA256 du body signé avec votre secret. Vérifiez-le avant de traiter le payload :

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
 const expected = createHmac('sha256', secret)
 .update(body)
 .digest('hex');

 const sig = Buffer.from(signature, 'hex');
 const exp = Buffer.from(expected, 'hex');

 return sig.length === exp.length && timingSafeEqual(sig, exp);
}

// In your webhook handler:
app.post('/webhooks/kountabl', (req, res) => {
 const signature = req.headers['x-mokawil-signature'];
 const isValid = verifyWebhookSignature(
 JSON.stringify(req.body),
 signature,
 process.env.KOUNTABL_WEBHOOK_SECRET
 );

 if (!isValid) {
 return res.status(401).json({ error: 'Invalid signature' });
 }

 // Process the webhook event
 const { event, data } = req.body;
 console.log('Received event:', event, data);

 res.status(200).json({ received: true });
});

Tentatives de renvoi (Retry)

Si votre endpoint ne répond pas avec un status 2xx, Kountabl réessaiera avec un backoff exponentiel :

Erreurs

Les erreurs utilisent une enveloppe standard :

{
"error": {
"code":"unauthorized",
"message":"Invalid or missing API key"
 }
}

Codes d'erreur