RESTful API om uw tools met Kolva te integreren. Beheer klanten, deals, bezoeken en contacten programmatisch. Realtime webhooks voor elke gebeurtenis.
OpenAPI 3.1-specificatieAuthenticatie
Genereer uw API-sleutels via Instellingen → Ontwikkelaar in uw Kolva-beheerpaneel. Elke sleutel heeft afgebakende machtigingen en kan op elk moment worden ingetrokken.
Aanbevolen methode
Fijnmazige machtigingen
read:clientswrite:clientsread:dealswrite:dealsread:visitswrite:visitsread:finance* (all)Endpoints
Alle endpoints volgen de REST-conventies. De antwoorden zijn in JSON. Paginering met ?page= en ?limit= (max. 100).
/api/v1/clientsBeheer uw klantenbestand — weergeven, aanmaken, bijwerken, deactiveren.
/api/v1/contactsCRUD-bewerkingen op contacten binnen klantdossiers (JSONB-array met contacten).
/api/v1/dealsOrders en deals — aanmaken, status bijwerken, omzet volgen.
/api/v1/visitsVeldbezoeken — plannen, check-in/check-out volgen, planningen beheren.
Rate limits
100
verzoeken / minuut
429
status bij overschrijding
Retry-After
header meegestuurd
Webhooks
Abonneer u op gebeurtenissen via Instellingen → Ontwikkelaar → Webhooks. Kolva stuurt POST-verzoeken naar uw URL, met handtekeningverificatie via HMAC-SHA256.
deal_createdWordt geactiveerd wanneer een nieuwe deal/order wordt aangemaakt
deal_updatedWordt geactiveerd wanneer de status of het bedrag van een deal verandert
client_createdWordt geactiveerd wanneer een nieuwe klant wordt toegevoegd
client_updatedWordt geactiveerd wanneer klantgegevens worden gewijzigd
visit_completedWordt geactiveerd wanneer een veldvertegenwoordiger uitcheckt
invoice_createdWordt geactiveerd wanneer een factuur wordt aangemaakt
order_createdWordt geactiveerd wanneer een order wordt geplaatst
contact_updatedWordt geactiveerd wanneer een klantcontact wordt gewijzigd
Elke webhook-POST bevat een header X-Kolva-Signature . Verifieer hem met HMAC-SHA256 en uw webhook-secret.
Herhaalbeleid: 3 pogingen met exponentiële backoff (1 min, 5 min, 30 min). Na 10 opeenvolgende mislukkingen wordt de webhook automatisch uitgeschakeld.
Voorbeelden
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.Maak uw API-sleutel aan in de Kolva-instellingen of raadpleeg de OpenAPI-specificatie voor de volledige referentie.