API Kountabl

Authentification

Generez une cle API dans Parametres > Administration > API. Chaque cle commence par le prefixe mk_live_ et est liee a votre entreprise.

Envoyez la cle 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 limitee a 100 requetes par minute par cle API. Les headers suivants sont inclus dans chaque reponse :

Endpoints

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

Factures (Invoices)

Exemple de reponse

{
"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)

Depenses (Expenses)

Webhooks

Les webhooks vous permettent de recevoir des notifications en temps reel lorsqu'un evenement 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'evenements

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"
}

Verification de signature

Chaque requete webhook inclut un header X-Mokawil-Signature contenant un HMAC-SHA256 du body signe avec votre secret. Verifiez-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 });
});

Retentatives (Retry)

Si votre endpoint ne repond pas avec un status 2xx, Kountabl reessaiera avec un backoff exponentiel :

Erreurs

Les erreurs utilisent une enveloppe standard :

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

Codes d'erreur