RESTful-API zur Integration Ihrer Tools mit Kolva. Verwalten Sie Kunden, Deals, Besuche und Kontakte programmatisch. Echtzeit-Webhooks für jedes Ereignis.
OpenAPI-3.1-SpezifikationAuthentifizierung
Erstellen Sie API-Schlüssel unter Einstellungen → Entwickler in Ihrem Kolva-Adminbereich. Jeder Schlüssel verfügt über eingegrenzte Berechtigungen und kann jederzeit widerrufen werden.
Empfohlene Methode
Granulare Berechtigungen
read:clientswrite:clientsread:dealswrite:dealsread:visitswrite:visitsread:finance* (all)Endpunkte
Alle Endpunkte folgen den REST-Konventionen. Antworten verwenden JSON. Paginierung mit ?page= und ?limit= (max. 100).
/api/v1/clientsVerwalten Sie Ihre Kundendatenbank — auflisten, anlegen, aktualisieren, deaktivieren.
/api/v1/contactsCRUD von Kontakten innerhalb von Kundendatensätzen (JSONB-Kontakt-Array).
/api/v1/dealsAufträge und Deals — anlegen, Status aktualisieren, Umsatz verfolgen.
/api/v1/visitsAußendienstbesuche — planen, Check-in/Check-out verfolgen, Termine verwalten.
Ratenbegrenzungen
100
Anfragen / Minute
429
Status bei Überschreitung
Retry-After
Header enthalten
Webhooks
Abonnieren Sie Ereignisse unter Einstellungen → Entwickler → Webhooks. Kolva sendet POST-Anfragen an Ihre URL mit HMAC-SHA256-Signaturprüfung.
deal_createdWird ausgelöst, wenn ein neuer Deal/Auftrag erstellt wird
deal_updatedWird ausgelöst, wenn sich Status oder Betrag eines Deals ändert
client_createdWird ausgelöst, wenn ein neuer Kunde hinzugefügt wird
client_updatedWird ausgelöst, wenn Kundendaten geändert werden
visit_completedWird ausgelöst, wenn ein Außendienstmitarbeiter auscheckt
invoice_createdWird ausgelöst, wenn eine Rechnung erzeugt wird
order_createdWird ausgelöst, wenn ein Auftrag aufgegeben wird
contact_updatedWird ausgelöst, wenn ein Kundenkontakt geändert wird
Jeder Webhook-POST enthält einen X-Kolva-Signature -Header. Prüfen Sie ihn mit HMAC-SHA256 anhand Ihres Webhook-Secrets.
Wiederholungsrichtlinie: 3 Versuche mit exponentiellem Backoff (1 Min., 5 Min., 30 Min.). Nach 10 aufeinanderfolgenden Fehlern wird der Webhook automatisch deaktiviert.
Beispiele
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.Erstellen Sie Ihren API-Schlüssel in den Kolva-Einstellungen oder sehen Sie sich die OpenAPI-Spezifikation für die vollständige Referenz an.