Documentación

API REST v1

La API REST da a scripts e integraciones el mismo acceso por permisos que el conector. Solo acepta tokens de API; los tokens OAuth sirven únicamente en el endpoint MCP.

Lo básico

URL base: https://app.leitvik.com/api/v1
Cabecera: Authorization: Bearer qre_…. Peticiones y respuestas en JSON.
Límite: el del propio token por minuto (60 por defecto, de 1 a 600), compartido con el conector. Si se supera, la respuesta es 429 con Retry-After.
Las listas devuelven 50 elementos por defecto y 100 como máximo, con limit y offset; la respuesta incluye hasMore.
Las fechas van en la zona horaria del espacio.

Primera petición

curl

curl -s "https://app.leitvik.com/api/v1/context" \
  -H "authorization: Bearer $LEITVIK_TOKEN"

Escrituras idempotentes

Las escrituras de registros aceptan un requestId (UUID) en el cuerpo o una cabecera Idempotency-Key. Durante 24 horas, si repites la petición con la misma clave y el mismo contenido recibes el primer resultado sin que se escriba otra vez; la misma clave con otro contenido da 409. Las escrituras de tareas, oportunidades y capturas exigen su propio requestId.

Versiones

Las tareas y las oportunidades llevan una version. Envía la actual con cada cambio; si está desfasada recibes 409: vuelve a leer y decide otra vez.

Endpoints

Método	Ruta	Permiso
`GET`	`/api/v1/context`	Cualquier permiso
`GET`	`/api/v1/companies?q=&limit=&offset=`	`companies:read`
`GET`	`/api/v1/companies/{id}`	`companies:read`
`PUT`	`/api/v1/companies`	`companies:write`
`GET`	`/api/v1/companies/{id}/brief`	`companies:readleads:readtouches:readsignals:read`
`GET`	`/api/v1/contacts?companyId=`	`contacts:read`
`PUT`	`/api/v1/contacts`	`contacts:write`
`GET`	`/api/v1/leads?q=&status=`	`leads:read`
`PATCH`	`/api/v1/leads/{id}`	`leads:write`
`GET`	`/api/v1/touches?companyId=`	`touches:read`
`POST`	`/api/v1/touches`	`touches:write`
`GET`	`/api/v1/signals?companyId=`	`signals:read`
`POST`	`/api/v1/signals`	`signals:write`
`GET`	`/api/v1/dossiers?companyId=`	`dossiers:read`
`PUT`	`/api/v1/dossiers`	`dossiers:write`
`GET`	`/api/v1/today?limit=&offset=`	`leads:read`
`GET`	`/api/v1/tasks?status=&due=&owner=&companyId=`	`tasks:read`
`POST`	`/api/v1/tasks`	`tasks:write`
`PATCH`	`/api/v1/tasks/{id}`	`tasks:write`
`GET`	`/api/v1/opportunities?companyId=&stage=`	`opportunities:read`
`POST`	`/api/v1/opportunities`	`opportunities:write`
`PATCH`	`/api/v1/opportunities/{id}`	`opportunities:write`
`POST`	`/api/v1/captures`	`captures:write`
`POST`	`/api/v1/captures/{id}/apply`	`captures:write`
`POST`	`/api/v1/captures/{id}/undo`	`captures:write`

Errores

Los errores llegan como { "error": código }. Nunca incluyen trazas, SQL ni lo que enviaste.

Estado	Código	Qué significa
400	`validation`	Datos no válidos.
401	`unauthorized`	Falta el token, ha caducado, está revocado o no tiene el permiso.
403	`forbidden`	El token no puede hacerlo.
404	`not_found`	No existe en este espacio.
409	`conflict`	Versión desfasada, cambio de estado no permitido o clave repetida con otro contenido.
413	`too_large`	El cuerpo supera el límite.
429	`rate_limited`	Demasiadas peticiones; espera los segundos de `Retry-After`.