Crear y cambiar datos Próximamente
Las escrituras necesitan una clave con el permiso *:write correspondiente.
Qué devuelve una escritura. Si la clave tiene también el permiso de lectura correspondiente (
contacts:readobookings:read), recibes el recurso completo. Una clave solo de escritura recibe únicamente{ "id": "…" }: así no puede usarse para leer datos que no se le han autorizado (por ejemplo, al crear un contacto con un teléfono que ya existe, que se fusiona con el contacto existente).
Idempotency-Key (obligatoria en los POST)
Todos los POST exigen la cabecera Idempotency-Key: un identificador único
de la petición (8 a 128 caracteres entre letras, números y _ . : -; sirve un
UUID). Así, si tu servidor reintenta por un corte de red, no se hace dos
veces.
- Misma clave y misma petición: no se repite nada y recibes el mismo
resultado, con la cabecera
Idempotent-Replay: true. - Misma clave con una petición distinta: error
422. Usa una clave nueva para una petición nueva. - Si la primera petición todavía está en curso: error
409; espera unos segundos y repítela. - Si la operación falla, la clave queda libre para reintentar.
- Las claves caducan a las 24 horas.
Crear un contacto
curl -X POST https://TU-DIRECCION-BASE/v1/contacts \
-H "Authorization: Bearer nxk_live_…" \
-H "Idempotency-Key: 2f1c6a3e-8b6e-4c0c-9a0f-3f5b6d9a7a10" \
-H "Content-Type: application/json" \
-d '{"name": "Ana Pérez", "phone": "+34600111222"}'Necesita el nombre y al menos un teléfono o un email. Si el teléfono ya existe,
el contacto se fusiona con el existente en vez de duplicarse (igual que al
darlo de alta desde el panel). Responde 201.
PATCH /v1/contacts/{id} cambia el nombre, el teléfono o el email, y no
necesita Idempotency-Key.
Crear una reserva
curl -X POST https://TU-DIRECCION-BASE/v1/bookings \
-H "Authorization: Bearer nxk_live_…" \
-H "Idempotency-Key: 9d2b8c1a-5e7f-4a3b-8c2d-1e0f9a8b7c6d" \
-H "Content-Type: application/json" \
-d '{
"serviceId": "…",
"startsAt": "2026-11-02T10:00:00Z",
"customerName": "Ana Pérez",
"customerPhone": "+34600111222"
}'La reserva pasa por las mismas reglas que en el panel: comprueba que el
horario está libre, que el servicio y el profesional existen, y avisa al
cliente según la configuración de tu negocio. Si el horario ya no está
disponible recibes un 409 con el motivo. El teléfono va en formato
internacional (+34…).
Cancelar una reserva
POST /v1/bookings/{id}/cancel, con Idempotency-Key y, opcionalmente, un
cuerpo {"reason": "…"}. Cancela en nombre del negocio.
Límites
Las escrituras tienen un tope propio de 120 por minuto y clave, además del límite general. Ver Errores y límites.