API v1 — Estable

Construye sobre Kolva

API RESTful para integrar tus herramientas con Kolva. Gestiona clientes, negocios, visitas y contactos mediante programación. Webhooks en tiempo real para cada evento.

AutenticaciónEndpointsLímites de usoWebhooksEjemplos
Especificación OpenAPI 3.1

Autenticación

Autenticación por clave API

Genera claves API desde Ajustes → Desarrollador en tu panel de administración de Kolva. Cada clave tiene permisos acotados y se puede revocar en cualquier momento.

Autenticación por cabecera

Método recomendado

# Opción 1: cabecera X-Kolva-Key
X-Kolva-Key: kolva_sk_abc123...

# Opción 2: token Bearer
Authorization: Bearer kolva_sk_abc123...

Scopes disponibles

Permisos granulares

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

Endpoints

Recursos RESTful

Todos los endpoints siguen las convenciones REST. Las respuestas usan JSON. Paginación con ?page= y ?limit= (máx. 100).

Clientes

/api/v1/clients

Gestiona tu base de clientes: listar, crear, actualizar, desactivar.

GETPOSTPUTDELETE
Scopes: read:clients, write:clients

Contactos

/api/v1/contacts

CRUD de contactos dentro de las fichas de cliente (array de contactos JSONB).

GETPOSTPUTDELETE
Scopes: read:clients, write:clients

Negocios

/api/v1/deals

Pedidos y negocios: crear, actualizar estado, seguir los ingresos.

GETPOSTPUTDELETE
Scopes: read:deals, write:deals

Visitas

/api/v1/visits

Visitas de campo: planificar, registrar entradas y salidas, gestionar horarios.

GETPOSTPUTDELETE
Scopes: read:visits, write:visits

Límites de uso

Límites de uso justo

100

solicitudes / minuto

429

estado al superar el límite

Retry-After

cabecera incluida

Webhooks

Notificaciones de eventos en tiempo real

Suscríbete a los eventos desde Ajustes → Desarrollador → Webhooks. Kolva envía solicitudes POST a tu URL con verificación de firma HMAC-SHA256.

deal_created

Se activa cuando se crea un nuevo negocio/pedido

deal_updated

Se activa cuando cambia el estado o el importe de un negocio

client_created

Se activa cuando se añade un nuevo cliente

client_updated

Se activa cuando se modifican los datos de un cliente

visit_completed

Se activa cuando un comercial de campo registra su salida

invoice_created

Se activa cuando se genera una factura

order_created

Se activa cuando se realiza un pedido

contact_updated

Se activa cuando se modifica un contacto de cliente

Verificación de la firma

Cada POST de webhook incluye una cabecera X-Kolva-Signature . Verifícala con HMAC-SHA256 usando tu secreto de webhook.

// Verificación en 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)
);

Política de reintentos: 3 intentos con retroceso exponencial (1 min, 5 min, 30 min). Tras 10 fallos consecutivos, el webhook se desactiva automáticamente.

Ejemplos

Inicio rápido

cURL — Listar clientes
curl -X GET "https://kolva.ai/api/v1/clients?page=1&limit=10" \
  -H "X-Kolva-Key: kolva_sk_your_key_here"
cURL — Crear un negocio
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 — Listar visitas
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 — Crear 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.

¿Listo para integrar?

Crea tu clave API en los ajustes de Kolva, o consulta la especificación OpenAPI para la referencia completa.

Empieza gratisEspecificación OpenAPI