API v1 — stabilne

Twórz na Kolvie

API REST do integracji Twoich narzędzi z Kolvą. Zarządzaj klientami, dealami, wizytami i kontaktami programowo. Webhooki w czasie rzeczywistym dla każdego zdarzenia.

UwierzytelnianieEndpointyLimity zapytańWebhookiPrzykłady
Specyfikacja OpenAPI 3.1

Uwierzytelnianie

Uwierzytelnianie kluczem API

Generuj klucze API w Ustawienia → Deweloper w panelu administracyjnym Kolva. Każdy klucz ma ograniczone uprawnienia i może zostać unieważniony w dowolnym momencie.

Uwierzytelnianie nagłówkiem

Metoda zalecana

# Opcja 1: nagłówek X-Kolva-Key
X-Kolva-Key: kolva_sk_abc123...

# Opcja 2: token Bearer
Authorization: Bearer kolva_sk_abc123...

Dostępne zakresy

Uprawnienia granularne

read:clients
write:clients
read:deals
write:deals
read:visits
write:visits
read:finance
* (all)

Endpointy

Zasoby REST

Wszystkie endpointy stosują konwencje REST. Odpowiedzi są w formacie JSON. Paginacja przez ?page= i ?limit= (maks. 100).

Klienci

/api/v1/clients

Zarządzaj bazą klientów — lista, tworzenie, aktualizacja, dezaktywacja.

GETPOSTPUTDELETE
Zakresy: read:clients, write:clients

Kontakty

/api/v1/contacts

CRUD kontaktów w kartach klienta (tablica kontaktów JSONB).

GETPOSTPUTDELETE
Zakresy: read:clients, write:clients

Deale

/api/v1/deals

Zamówienia i deale — tworzenie, zmiana statusu, śledzenie przychodu.

GETPOSTPUTDELETE
Zakresy: read:deals, write:deals

Wizyty

/api/v1/visits

Wizyty w terenie — planowanie, śledzenie check-in/check-out, zarządzanie harmonogramami.

GETPOSTPUTDELETE
Zakresy: read:visits, write:visits

Limity zapytań

Limity uczciwego użycia

100

zapytań / minutę

429

status po przekroczeniu

Retry-After

dołączony nagłówek

Webhooki

Powiadomienia o zdarzeniach w czasie rzeczywistym

Subskrybuj zdarzenia w Ustawienia → Deweloper → Webhooki. Kolva wysyła żądania POST na Twój adres URL z weryfikacją podpisu HMAC-SHA256.

deal_created

Wyzwalany przy utworzeniu nowego deala lub zamówienia

deal_updated

Wyzwalany przy zmianie statusu lub kwoty deala

client_created

Wyzwalany przy dodaniu nowego klienta

client_updated

Wyzwalany przy zmianie danych klienta

visit_completed

Wyzwalany, gdy handlowiec terenowy rejestruje check-out

invoice_created

Wyzwalany przy wygenerowaniu faktury

order_created

Wyzwalany przy złożeniu zamówienia

contact_updated

Wyzwalany przy zmianie kontaktu klienta

Weryfikacja podpisu

Każdy POST webhooka zawiera nagłówek X-Kolva-Signature . Zweryfikuj go algorytmem HMAC-SHA256 przy użyciu sekretu webhooka.

// Weryfikacja w Node.js
const crypto = require('crypto');
const signature = req.headers['x-kolva-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature), Buffer.from(expected)
);

Zasady ponawiania: 3 próby z wykładniczym odstępem (1 min, 5 min, 30 min). Po 10 kolejnych niepowodzeniach webhook zostaje automatycznie wyłączony.

Przykłady

Szybki start

cURL — lista klientów
curl -X GET "https://kolva.ai/api/v1/clients?page=1&limit=10" \
  -H "X-Kolva-Key: kolva_sk_your_key_here"
cURL — utworzenie deala
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"}'
JavaScript — lista wizyt
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`);
JavaScript — utworzenie wizyty
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.

Gotowi do integracji?

Utwórz klucz API w ustawieniach Kolva albo zajrzyj do specyfikacji OpenAPI po pełną dokumentację.

Zacznij bezpłatnieSpecyfikacja OpenAPI