API v1 — Stabile

Sviluppa su Kolva

API RESTful per integrare i tuoi strumenti con Kolva. Gestisci clienti, opportunità, visite e contatti tramite API. Webhook in tempo reale per ogni evento.

AutenticazioneEndpointLimiti delle richiesteWebhookEsempi
Specifica OpenAPI 3.1

Autenticazione

Autenticazione con chiave API

Genera le chiavi API da Impostazioni → Sviluppatore nel pannello di amministrazione Kolva. Ogni chiave dispone di autorizzazioni con ambito definito e può essere revocata in qualsiasi momento.

Autenticazione tramite header

Metodo consigliato

# Opzione 1: header X-Kolva-Key
X-Kolva-Key: kolva_sk_abc123...

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

Ambiti disponibili

Autorizzazioni granulari

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

Endpoint

Risorse RESTful

Tutti gli endpoint seguono le convenzioni REST. Le risposte utilizzano JSON. Paginazione con ?page= e ?limit= (massimo 100).

Clienti

/api/v1/clients

Gestisci il database clienti: elenca, crea, aggiorna e disattiva.

GETPOSTPUTDELETE
Ambiti: read:clients, write:clients

Contatti

/api/v1/contacts

Operazioni CRUD sui contatti nei record cliente (array di contatti JSONB).

GETPOSTPUTDELETE
Ambiti: read:clients, write:clients

Opportunità

/api/v1/deals

Ordini e opportunità: crea, aggiorna lo stato e monitora i ricavi.

GETPOSTPUTDELETE
Ambiti: read:deals, write:deals

Visite

/api/v1/visits

Visite sul campo: pianifica, monitora check-in/check-out e gestisci i calendari.

GETPOSTPUTDELETE
Ambiti: read:visits, write:visits

Limiti delle richieste

Limiti di utilizzo equo

100

richieste / minuto

429

stato in caso di superamento

Retry-After

header incluso

Webhook

Notifiche degli eventi in tempo reale

Iscriviti agli eventi da Impostazioni → Sviluppatore → Webhook. Kolva invia richieste POST al tuo URL con verifica della firma HMAC-SHA256.

deal_created

Attivato quando viene creata una nuova opportunità o un nuovo ordine

deal_updated

Attivato quando cambiano lo stato o l'importo di un'opportunità

client_created

Attivato quando viene aggiunto un nuovo cliente

client_updated

Attivato quando vengono modificati i dati di un cliente

visit_completed

Attivato quando un commerciale sul campo effettua il check-out

invoice_created

Attivato quando viene generata una fattura

order_created

Attivato quando viene effettuato un ordine

contact_updated

Attivato quando viene modificato un contatto cliente

Verifica della firma

Ogni POST del webhook include un X-Kolva-Signature header. Verificalo con HMAC-SHA256 utilizzando il segreto del webhook.

// Verifica 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)
);

Criterio di ripetizione: 3 tentativi con backoff esponenziale (1 min, 5 min, 30 min). Dopo 10 errori consecutivi, il webhook viene disabilitato automaticamente.

Esempi

Avvio rapido

cURL — Elenca i clienti
curl -X GET "https://kolva.ai/api/v1/clients?page=1&limit=10" \
  -H "X-Kolva-Key: kolva_sk_your_key_here"
cURL — Crea un'opportunità
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 — Elenca le visite
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 — Crea una visita
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.

Pronto a integrare?

Crea la tua chiave API nelle impostazioni di Kolva oppure consulta la specifica OpenAPI per il riferimento completo.

Inizia gratuitamenteSpecifica OpenAPI