KalendarIAopenapi.json

API de KalendarIA

REST + JSON, webhooks firmados y servidor MCP. Incluida en todos los planes.

Empezar en 3 pasos

  1. En el panel, API y webhooks → crea una clave (kal_live_…).
  2. Consulta las horas libres de un servicio.
  3. Crea la reserva con uno de los start devueltos.
curl https://kalendaria.kisasotest.com/api/v1/services -H "Authorization: Bearer kal_live_XXXX"

curl "https://kalendaria.kisasotest.com/api/v1/availability?service_id=svc_…&from=2026-11-02&to=2026-11-08" \
  -H "Authorization: Bearer kal_live_XXXX"

curl -X POST https://kalendaria.kisasotest.com/api/v1/bookings \
  -H "Authorization: Bearer kal_live_XXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c…" \
  -d '{"service_id":"svc_…","start":"2026-11-03T13:00:00.000Z",
       "customer":{"name":"Ana Pérez","email":"ana@ejemplo.com","phone":"+56912345678"}}'

Convenciones

Endpoints

Cuenta

GET/accountDatos del negocio

Catálogo

GET/servicesListar servicios
POST/servicesCrear servicio
GET/services/{id}Ver servicio
PATCH/services/{id}Actualizar servicio
GET/staffListar profesionales (con horario semanal)
GET/resourcesListar recursos (boxes, sillones, salas, equipos)

Disponibilidad

GET/availabilityHoras libres de un servicio

Reservas

POST/holdsRetener una hora (10 minutos)
GET/bookingsListar reservas
POST/bookingsCrear reserva
GET/bookings/{id}Ver reserva
POST/bookings/{id}/cancelCancelar
POST/bookings/{id}/rescheduleCambiar hora
POST/bookings/{id}/confirmAprobar (pending_approval → confirmed)
POST/bookings/{id}/completeMarcar como atendida
POST/bookings/{id}/no_showMarcar como no asistió

Clientes

GET/customersListar o buscar clientes
POST/customersCrear o actualizar cliente (por email/teléfono)
GET/customers/{id}Ver cliente
PATCH/customers/{id}Actualizar cliente
DELETE/customers/{id}Suprimir datos personales (RGPD / Ley 21.719)

Webhooks

GET/webhook_endpointsListar webhooks
POST/webhook_endpointsSuscribir un webhook (REST hook)
DELETE/webhook_endpoints/{id}Eliminar webhook
GET/webhook_endpoints/{id}/deliveriesÚltimas entregas de un webhook
GET/eventsRegistro de eventos (reconciliación)
GET/events/{id}Ver evento

Esquemas completos en openapi.json (impórtalo en Postman, Insomnia o un generador de SDK).

Flujo con retención (checkout, WhatsApp)

Retén la hora 10 minutos mientras el cliente termina y confírmala después: nadie más puede tomarla mientras tanto.

POST /api/v1/holds     {"service_id":"svc_…","start":"2026-11-03T13:00:00.000Z"}
→ {"id":"bkg_…","object":"hold","status":"held","hold_expires_at":"…"}

POST /api/v1/bookings  {"hold_id":"bkg_…","customer":{"name":"Ana","phone":"+34612345678"}}
→ {"id":"bkg_…","status":"confirmed","manage_url":"…"}

Webhooks

Formato Standard Webhooks: cabeceras webhook-id, webhook-timestamp y webhook-signature (v1,<base64>). Firma HMAC-SHA256 de id.timestamp.cuerpo con el secreto (whsec_…, se decodifica en base64). Reintentos durante ~42 h; responde 2xx en menos de 10 s.

// Node.js
import crypto from "node:crypto";
function verify(secret, headers, rawBody) {
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const msg = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
  const sig = crypto.createHmac("sha256", key).update(msg).digest("base64");
  const fresh = Math.abs(Date.now() / 1000 - Number(headers["webhook-timestamp"])) < 300;
  return fresh && headers["webhook-signature"].split(" ").includes(`v1,${sig}`);
}

Eventos:

booking.heldbooking.createdbooking.confirmedbooking.pending_approvalbooking.pending_paymentbooking.rescheduledbooking.canceledbooking.completedbooking.no_showbooking.expiredpayment.succeededpayment.failedcustomer.createdcustomer.updatedwaitlist.joinedwaitlist.notified

Si se pierde alguno, GET /api/v1/events devuelve el registro completo para reconciliar.

Servidor MCP (agentes de IA)

Streamable HTTP en https://kalendaria.kisasotest.com/api/mcp, autenticado con una clave de API. Herramientas: datos del negocio, servicios, horas libres, crear, mover, cancelar y aprobar reservas, marcar asistencia, buscar clientes y resumen del día.

claude mcp add --transport http kalendaria https://kalendaria.kisasotest.com/api/mcp \
  --header "Authorization: Bearer kal_live_XXXX"

Widget

<div data-kalendaria="tu-negocio"></div>
<script src="https://kalendaria.kisasotest.com/embed.js" async></script>

<!-- o un botón flotante -->
<script src="https://kalendaria.kisasotest.com/embed.js" data-kalendaria-button="tu-negocio" data-label="Reservar" async></script>

Pasa los UTM, fbclid, gclid y las cookies _fbp/_fbc/_ga a la reserva y, al reservar, lanza dataLayer.push({event: "booking_created"}) y el evento Schedule del píxel de Meta con eventID = id de la reserva.