API RESTful para integrar as suas ferramentas com a Kolva. Faça a gestão de clientes, negócios, visitas e contactos por programação. Webhooks em tempo real para cada evento.
Especificação OpenAPI 3.1Autenticação
Gere as suas chaves de API em Definições → Programador no seu painel de administração Kolva. Cada chave tem permissões delimitadas e pode ser revogada a qualquer momento.
Método recomendado
Permissões granulares
read:clientswrite:clientsread:dealswrite:dealsread:visitswrite:visitsread:finance* (all)Endpoints
Todos os endpoints seguem as convenções REST. As respostas são em JSON. Paginação com ?page= e ?limit= (máx. 100).
/api/v1/clientsFaça a gestão da sua base de clientes — listar, criar, atualizar, desativar.
/api/v1/contactsCRUD dos contactos dentro das fichas de cliente (matriz de contactos JSONB).
/api/v1/dealsEncomendas e negócios — criar, atualizar o estado, acompanhar a faturação.
/api/v1/visitsVisitas no terreno — planear, acompanhar o check-in/check-out, gerir os planeamentos.
Limites de taxa
100
pedidos / minuto
429
estado em caso de excesso
Retry-After
cabeçalho incluído
Webhooks
Subscreva os eventos em Definições → Programador → Webhooks. A Kolva envia pedidos POST para o seu URL, com verificação de assinatura HMAC-SHA256.
deal_createdAcionado quando é criado um novo negócio/encomenda
deal_updatedAcionado quando o estado ou o montante de um negócio muda
client_createdAcionado quando é adicionado um novo cliente
client_updatedAcionado quando os dados de um cliente são alterados
visit_completedAcionado quando um comercial de terreno faz check-out
invoice_createdAcionado quando é gerada uma fatura
order_createdAcionado quando é registada uma encomenda
contact_updatedAcionado quando um contacto de cliente é alterado
Cada POST de webhook inclui um cabeçalho X-Kolva-Signature . Verifique-o com HMAC-SHA256, usando o segredo do seu webhook.
Política de repetição: 3 tentativas com backoff exponencial (1 min, 5 min, 30 min). Ao fim de 10 falhas consecutivas, o webhook é desativado automaticamente.
Exemplos
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.Crie a sua chave de API nas definições da Kolva ou consulte a especificação OpenAPI para a referência completa.