Kalendia Developers
Documentación oficial

Construye automatizaciones seguras con Kalendia

Conecta citas, clientes, servicios, inventario, pedidos, pagos y formularios con n8n, Make, Zapier o tu propio sistema.

¿Buscas configurar pagos o integraciones?Las credenciales de pasarelas, Automatizaciones y otras integraciones se administran directamente dentro de Kalendia. La API no expone esos secretos.
Inicio rápido

Tu primera consulta en cinco minutos

  1. Activa AutomatizacionesEn el catálogo de complementos de tu negocio.
  2. Crea una conexiónElige un nombre reconocible y solamente los permisos necesarios.
  3. Copia la credencialKalendia la muestra una sola vez. Guárdala en el gestor de credenciales de la herramienta que usarás.
  4. Usa el dominio de tu negocioSustituye TU-NEGOCIO por el subdominio exacto de tu Kalendia.
GEThttps://TU-NEGOCIO.app.kalendia.co/wp-json/kalendia/v1/automations/connection
curl --request GET \
  'https://TU-NEGOCIO.app.kalendia.co/wp-json/kalendia/v1/automations/connection' \
  --header 'Authorization: Bearer TU_CREDENCIAL'

Una conexión correcta devuelve el negocio asociado, los permisos vigentes, el límite de solicitudes y la fecha de vencimiento de la credencial.

Conceptos

Cómo está organizada la plataforma

Una credencial pertenece a un negocio

Las conexiones no pertenecen a una persona individual. Están vinculadas al negocio que las creó, por lo que varios administradores pueden trabajar con la misma cuenta sin mezclar información con otros negocios.

Identificadores opacos

Kalendia utiliza IDs públicos que no revelan los IDs internos de la base de datos. Debes guardarlos y enviarlos completos.

cli_… clienteapt_… citasvc_… serviciostf_… equipores_… recursoprd_… productoord_… pedidopay_… pagofrm_… formulariosub_… respuesta

Versiones y fechas

Cada respuesta incluye api_version. Las fechas intercambiadas por la API usan ISO 8601; conserva la zona horaria cuando corresponda y utiliza UTC para sincronizaciones incrementales.

Seguridad

Autenticación

Todas las rutas de Automatizaciones exigen el encabezado Authorization. Una credencial solo funciona en el subdominio del negocio que la emitió.

Authorization: Bearer TU_CREDENCIAL
Accept: application/json
Nunca publiques una credencialNo la incluyas en la URL, capturas, código del navegador, repositorios ni campos de consulta. Si sospechas exposición, rótala desde Automatizaciones.
RespuestaSignificado
401Falta la credencial o no es válida.
403La conexión no tiene el permiso requerido, está suspendida o pertenece a otro negocio.
429Se excedió el límite temporal de solicitudes.
Seguridad

Permisos por conexión

Aplica el principio de menor privilegio: una conexión de lectura no necesita permisos de escritura.

Negociobusiness.read
Clientescustomers.readcustomers.writecustomers.notes.readcustomers.notes.write
Citasappointments.readappointments.createappointments.update
Comercioproducts.readinventory.readorders.readpayments.read
Formulariosforms.schemas.readforms.submissions.readforms.submissions.write
Disponibilidadservices.readstaff.readresources.readavailability.read
Seguridad operacional

Idempotencia en escrituras

Las solicitudes POST y PATCH requieren Idempotency-Key de al menos ocho caracteres. Reutiliza la misma clave solamente al reintentar exactamente la misma operación.

Content-Type: application/json
Idempotency-Key: pedido-{{$execution.id}}-{{$itemIndex}}

Si una clave ya fue usada con otro cuerpo, Kalendia responde 409 idempotency_conflict en lugar de ejecutar una operación ambigua.

Uso responsable

Límites, paginación y sincronización

  • page: página solicitada, comenzando en 1.
  • per_page: entre 1 y 100; valor predeterminado 25.
  • updated_since: fecha ISO 8601 para sincronizaciones incrementales en recursos compatibles.
  • El límite por minuto aparece en GET /connection.

Ante un 429, espera antes de reintentar y utiliza retroceso exponencial con variación aleatoria.

API REST

Referencia de endpoints

Base URL para todas las operaciones:

https://TU-NEGOCIO.app.kalendia.co/wp-json/kalendia/v1/automations
Recetas

Clientes, propiedades y notas

Buscar por correo exacto

GET/customers?email=cliente@ejemplo.com

Crear o actualizar un cliente

POST /customers
{
  "name": "María Pérez",
  "email": "maria@ejemplo.com",
  "phone": "+573001234567",
  "timezone": "America/Bogota",
  "properties": { "numero_pasaporte": "AB123456" }
}

Agregar una nota interna

POST /customers/cli_ID_DEL_CLIENTE/notes
{
  "text": "Seguimiento realizado desde n8n.",
  "is_pinned": false
}
El campo se llama textLas notas no son propiedades personalizadas y no usan un property_id. Consulta GET /customers/properties únicamente para los campos personalizados del cliente.
Recetas

Citas y disponibilidad

Consultar una cita del webhook

GET/appointments?id=apt_ID_DE_LA_CITA

La respuesta incluye cliente, servicio, miembro del equipo, modalidad y, cuando existe, virtual_provider y virtual_meeting_url.

Consultar horarios

GET/availability?service_id=svc_…&date=2026-11-24

Crear una cita

POST /appointments
{
  "service_id": "svc_…",
  "staff_id": "stf_…",
  "date": "2026-11-24",
  "time": "10:30",
  "timezone": "America/Bogota",
  "customer": {
    "name": "María Pérez",
    "email": "maria@ejemplo.com",
    "phone": "+573001234567"
  }
}
Recetas

Productos, inventario, pedidos y pagos

Los IDs recibidos en eventos pueden consultarse directamente:

GET /products?id=prd_…
GET /inventory?product_id=prd_…
GET /orders?id=ord_…
GET /payments?id=pay_…

Para sincronizaciones periódicas utiliza updated_since en pedidos y pagos. Los filtros inválidos no se ignoran: devuelven una colección vacía para impedir que una consulta mal formada exponga datos generales.

Recetas

Formularios y respuestas

Consulta primero el esquema. Cada campo contiene un ID estable que debe usarse como clave dentro de values.

GET /forms/schemas?id=frm_…

POST /forms/submissions
{
  "form_id": "frm_…",
  "appointment_id": "apt_…",
  "customer_id": "cli_…",
  "service_id": "svc_…",
  "values": {
    "field_numero_pasaporte": "AB123456"
  }
}

También puedes consultar por id, form_id, appointment_id o updated_since.

Eventos

Webhooks

Los webhooks notifican cambios sin necesidad de consultar constantemente la API. Configura una URL HTTPS pública desde Automatizaciones y selecciona únicamente los eventos necesarios.

{
  "event_id": "evt_…",
  "event_type": "appointment.created",
  "event_version": 1,
  "occurred_at": "2026-11-21T02:00:00+00:00",
  "business_id": "site_136",
  "resource_id": "apt_…",
  "correlation_id": null,
  "data": { "appointment_id": "apt_…", "status": "confirmed" }
}
  • Responde con un código 2xx rápidamente.
  • Guarda event_id para evitar procesar duplicados.
  • No asumas que los eventos siempre llegarán en orden.
  • Consulta el recurso por su ID si necesitas su estado completo y más reciente.
Webhooks

Catálogo de eventos

Webhooks

Validar la firma

Verifica la firma antes de interpretar el cuerpo. Usa el cuerpo crudo recibido, no un JSON reconstruido.

mensaje = timestamp + "." + delivery_id + "." + event_type + "." + raw_body
esperada = "v1=" + HMAC_SHA256(webhook_secret, mensaje)

Compara mediante una función de tiempo constante. Rechaza timestamps demasiado antiguos para reducir ataques de repetición.

Plataformas

Configuración recomendada en n8n

  1. Método: GET, POST o PATCH.
  2. Authentication: Generic Credential Type → Header Auth.
  3. Nombre: Authorization.
  4. Valor: Bearer TU_CREDENCIAL.
  5. Para escrituras activa Send Headers y agrega Idempotency-Key.
No antepongas = a una URL fijaUtiliza la URL base fija y agrega id desde “Send Query Parameters”. Si n8n muestra =https://…, la URL es inválida.
Diagnóstico

Códigos de error

HTTPCódigo habitualAcción
400invalid_jsonRevisa que el cuerpo sea JSON válido.
401missing_bearer_tokenAgrega o corrige Authorization.
403insufficient_scope / tenant_mismatchRevisa el permiso y el subdominio.
404not_foundComprueba el ID y su prefijo.
409idempotency_conflictUsa una clave nueva para un cuerpo diferente.
422validation_errorCorrige campos, relaciones o encabezados.
429rate_limit_exceededEspera y reintenta gradualmente.
500internal_errorConserva request_id y contacta soporte.

Todas las respuestas incluyen un request_id. Compártelo con soporte; nunca envíes tu Bearer Token.

Antes de publicar

Lista de verificación para producción

  • Una conexión diferente por sistema o flujo importante.
  • Solamente los permisos imprescindibles.
  • Credenciales almacenadas como secretos, nunca en código.
  • Idempotencia en todas las escrituras.
  • Validación de firma en webhooks.
  • Deduplicación mediante event_id.
  • Timeouts, reintentos y retroceso exponencial.
  • Registro de request_id sin guardar datos sensibles.
  • Pruebas con IDs inexistentes y credenciales revocadas.
  • Monitoreo de fallos y revisión periódica de permisos.
Versiones

Changelog

Filtros de consulta uniformes

Se añadieron búsquedas directas por ID para citas, pedidos, pagos, productos, servicios, recursos, equipo y formularios. Los filtros inválidos ya no devuelven colecciones generales.

Autenticación obligatoria y aislamiento

Todas las rutas de Automatizaciones requieren Bearer Token y cada credencial queda ligada al negocio que la emitió.

API inicial

Primera versión pública de Automatizaciones, webhooks firmados y permisos por conexión.