Zimun: Appointment Scheduling & Booking Software: Guía de API

La API de Zimun: Appointment Scheduling & Booking Software está diseñada para equipos que quieren que la reserva se sienta integrada en sus propias herramientas. Úsala para mostrar disponibilidad en vivo, colocar holds temporales y confirmar citas sin conflictos.

Para quién es esta API

Si gestionas una app de clientes, un portal de personal o una herramienta interna, la API te permite mantener la lógica de programación sincronizada con Zimun: Appointment Scheduling & Booking Software y conservar la experiencia.

Piénsalo como un motor de programación que puedes integrar en cualquier lugar: tu web, tu app móvil o una herramienta interna para tu equipo.

Protocolo y formato

• HTTPS + respuestas JSON (UTF‑8).
• Autenticación OAuth2 Client Credentials (RFC 6749 §4.4).
• POST/PATCH idempotentes con Idempotency‑Key para reintentos seguros.
• Paginación mediante page_size/page_token con { items, next_page_token }.
• Marcas de tiempo ISO‑8601 con desfases de zona horaria.

Cómo funciona la autenticación

1. Crea un cliente API en Ajustes → API Clients para obtener tu client_id y client_secret.
2. Solicita un token en /oauth/token usando el grant de credenciales de cliente.
3. Llama a la API con Authorization: Bearer <token>.

Los tokens son de corta duración y están limitados a tu organización.

Scopes de un vistazo

• org:read - metadatos de la organización
• availability:read - slots y mapa de festivos
• appointments:read - listar/ver citas
• appointments:write - holds, confirmar, reprogramar, cancelar, webhooks

URL base

https://api.zimun.online/api/v1

Flujo de reserva común

1. Mostrar disponibilidad para un servicio o miembro del equipo.
2. Crea un hold de 10 minutos cuando un usuario elige un slot.
3. Confirma la cita con los datos del cliente - o libera el hold si cancelan.

Este flujo refleja lo que hace la página pública de reservas, así que obtienes el mismo comportamiento sin conflictos.

Ejemplo rápido (cURL)

Usa este ejemplo para obtener disponibilidad para los próximos 7 días. Sustituye service_id y tu token de acceso.

curl -X GET \
  "https://api.zimun.online/api/v1/availability?service_id=s_123&days_ahead=7" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Para ejemplos de extremo a extremo en Python, Node.js, Go y Rust, consulta la página de Referencia de la API.

Casos de uso típicos

• Reserva integrada - Usa la API para impulsar una interfaz de programación personalizada dentro de tu app.
• Sincronización CRM / POS - Envía citas confirmadas a tus herramientas internas o a tu pila de analítica.
• Panel de operaciones - Consulta servicios, personal y recursos para una vista de calendario en tiempo real.

Historias de usuario

• Una app de clínica muestra terapeutas disponibles por servicio, coloca un hold mientras el paciente completa un formulario y luego confirma la cita.
• Un estudio sincroniza las citas en su panel de BI con una extracción nocturna.
• Un marketplace SaaS integra un modal de reservas que usa la disponibilidad y las reglas de conflicto de Zimun: Appointment Scheduling & Booking Software.