Construye automatizaciones seguras con Kalendia
Conecta citas, clientes, servicios, inventario, pedidos, pagos y formularios con n8n, Make, Zapier o tu propio sistema.
Tu primera consulta en cinco minutos
- Activa AutomatizacionesEn el catálogo de complementos de tu negocio.
- Crea una conexiónElige un nombre reconocible y solamente los permisos necesarios.
- Copia la credencialKalendia la muestra una sola vez. Guárdala en el gestor de credenciales de la herramienta que usarás.
- Usa el dominio de tu negocioSustituye
TU-NEGOCIOpor el subdominio exacto de tu Kalendia.
https://TU-NEGOCIO.app.kalendia.co/wp-json/kalendia/v1/automations/connectioncurl --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.
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_… respuestaVersiones 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.
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
| Respuesta | Significado |
|---|---|
401 | Falta la credencial o no es válida. |
403 | La conexión no tiene el permiso requerido, está suspendida o pertenece a otro negocio. |
429 | Se excedió el límite temporal de solicitudes. |
Permisos por conexión
Aplica el principio de menor privilegio: una conexión de lectura no necesita permisos de escritura.
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.
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.
Referencia de endpoints
Base URL para todas las operaciones:
https://TU-NEGOCIO.app.kalendia.co/wp-json/kalendia/v1/automations
Clientes, propiedades y notas
Buscar por correo exacto
/customers?email=cliente@ejemplo.comCrear 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
}
textLas notas no son propiedades personalizadas y no usan un property_id. Consulta GET /customers/properties únicamente para los campos personalizados del cliente.Citas y disponibilidad
Consultar una cita del webhook
/appointments?id=apt_ID_DE_LA_CITALa respuesta incluye cliente, servicio, miembro del equipo, modalidad y, cuando existe, virtual_provider y virtual_meeting_url.
Consultar horarios
/availability?service_id=svc_…&date=2026-11-24Crear 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"
}
}
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.
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.
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
2xxrápidamente. - Guarda
event_idpara 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.
Catálogo de eventos
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.
Configuración recomendada en n8n
- Método:
GET,POSToPATCH. - Authentication: Generic Credential Type → Header Auth.
- Nombre:
Authorization. - Valor:
Bearer TU_CREDENCIAL. - Para escrituras activa Send Headers y agrega
Idempotency-Key.
= a una URL fijaUtiliza la URL base fija y agrega id desde “Send Query Parameters”. Si n8n muestra =https://…, la URL es inválida.Códigos de error
| HTTP | Código habitual | Acción |
|---|---|---|
| 400 | invalid_json | Revisa que el cuerpo sea JSON válido. |
| 401 | missing_bearer_token | Agrega o corrige Authorization. |
| 403 | insufficient_scope / tenant_mismatch | Revisa el permiso y el subdominio. |
| 404 | not_found | Comprueba el ID y su prefijo. |
| 409 | idempotency_conflict | Usa una clave nueva para un cuerpo diferente. |
| 422 | validation_error | Corrige campos, relaciones o encabezados. |
| 429 | rate_limit_exceeded | Espera y reintenta gradualmente. |
| 500 | internal_error | Conserva request_id y contacta soporte. |
Todas las respuestas incluyen un request_id. Compártelo con soporte; nunca envíes tu Bearer Token.
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_idsin guardar datos sensibles. - Pruebas con IDs inexistentes y credenciales revocadas.
- Monitoreo de fallos y revisión periódica de permisos.
Changelog
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.
Todas las rutas de Automatizaciones requieren Bearer Token y cada credencial queda ligada al negocio que la emitió.
Primera versión pública de Automatizaciones, webhooks firmados y permisos por conexión.