API RESTful pour intégrer vos outils à Kolva. Gérez clients, affaires, visites et contacts par programmation. Webhooks en temps réel pour chaque événement.
Spécification OpenAPI 3.1Authentification
Générez vos clés API depuis Paramètres → Développeur dans votre panneau d’administration Kolva. Chaque clé dispose de permissions cantonnées et peut être révoquée à tout moment.
Méthode recommandée
Permissions granulaires
read:clientswrite:clientsread:dealswrite:dealsread:visitswrite:visitsread:finance* (all)Endpoints
Tous les endpoints suivent les conventions REST. Les réponses sont au format JSON. Pagination avec ?page= et ?limit= (max. 100).
/api/v1/clientsGérez votre base de clients — lister, créer, mettre à jour, désactiver.
/api/v1/contactsCRUD des contacts au sein des fiches client (tableau de contacts JSONB).
/api/v1/dealsCommandes et affaires — créer, mettre à jour le statut, suivre le chiffre d’affaires.
/api/v1/visitsVisites terrain — planifier, suivre les pointages d’arrivée et de départ, gérer les plannings.
Limites de débit
100
requêtes / minute
429
statut en cas de dépassement
Retry-After
en-tête inclus
Webhooks
Abonnez-vous aux événements depuis Paramètres → Développeur → Webhooks. Kolva envoie des requêtes POST à votre URL avec vérification de signature HMAC-SHA256.
deal_createdDéclenché lorsqu’une nouvelle affaire/commande est créée
deal_updatedDéclenché lorsque le statut ou le montant d’une affaire change
client_createdDéclenché lorsqu’un nouveau client est ajouté
client_updatedDéclenché lorsque les détails d’un client sont modifiés
visit_completedDéclenché lorsqu’un commercial terrain pointe son départ
invoice_createdDéclenché lorsqu’une facture est générée
order_createdDéclenché lorsqu’une commande est passée
contact_updatedDéclenché lorsqu’un contact client est modifié
Chaque POST de webhook inclut un en-tête X-Kolva-Signature . Vérifiez-le avec HMAC-SHA256 à l’aide de votre secret de webhook.
Politique de réessai : 3 tentatives avec backoff exponentiel (1 min, 5 min, 30 min). Après 10 échecs consécutifs, le webhook est désactivé automatiquement.
Exemples
curl -X GET "https://kolva.ai/api/v1/clients?page=1&limit=10" \ -H "X-Kolva-Key: kolva_sk_your_key_here"
curl -X POST "https://kolva.ai/api/v1/deals" \
-H "X-Kolva-Key: kolva_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"client_id": "uuid", "total_ht": 1500, "currency": "EUR"}'const response = await fetch("https://kolva.ai/api/v1/visits?status=completed", {
headers: { "X-Kolva-Key": process.env.KOLVA_API_KEY },
});
const { data, total } = await response.json();
console.log(`Found ${total} completed visits`);const visit = await fetch("https://kolva.ai/api/v1/visits", {
method: "POST",
headers: {
"X-Kolva-Key": process.env.KOLVA_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
client_id: "client-uuid",
commercial_id: "rep-uuid",
planned_date: "2026-03-15",
type: "routine",
}),
});
const { data } = await visit.json();
// Retry the same operation with the same UUID. A replay returns HTTP 200;
// the initial creation returns HTTP 201.Créez votre clé API dans les paramètres Kolva, ou consultez la spécification OpenAPI pour la référence complète.