API de citas (integración CRM)

Si gestionas tu propio CRM, ERP o pantalla de reservas, puedes controlar las citas de Conviro desde allí mediante una API REST sencilla. Las reservas por API usan el mismo motor que la reserva en el chat: la disponibilidad se recalcula en el servidor según tu horario y tu calendario conectado (Google, Outlook o un feed ICS), el cliente recibe el correo de confirmación con archivo de calendario y enlace de gestión, y tu equipo recibe las notificaciones habituales.

Requisitos previos

1. Citas configuradas para tu asistente: Dashboard -> Assistants -> [tu bot] -> Setup -> Scheduling.
2. Un calendario conectado: Google Calendar, Outlook / Microsoft 365, un feed ICS (Apple/iCloud, Fastmail, Nextcloud, ...) o el calendario interno integrado.
3. Una clave API con los scopes adecuados: Dashboard -> Settings -> API Keys; marca Appointments Read y/o Appointments Write.

Autenticación

Envía tu clave en la cabecera Authorization en cada petición:

Authorization: Bearer YOUR_API_KEY

URL base: https://api.conviro.io

1. Listar huecos libres

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments/slots?chatbotId=CHATBOT_ID&date=2026-07-15"

• date (opcional) — fecha local (YYYY-MM-DD) en la zona horaria del asistente; si se omite, el siguiente día disponible.
• serviceId (opcional) — uno de los servicios devueltos en la respuesta.

La respuesta contiene timeZone, tus services y slots como pares { start, end } en formato ISO UTC.

2. Reservar una cita

Requiere el scope appointments:write. Las reservas por API son de confianza — no se envía OTP por correo, porque tu sistema ya posee la identidad del cliente.

curl -X POST "https://api.conviro.io/v1/api/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "startIso": "2026-07-15T09:00:00.000Z",
    "contactEmail": "[email protected]",
    "contactName": "Jane Doe",
    "contactPhone": "+31 6 00000000"
  }'

Usa un startIso obtenido del endpoint de huecos. El servidor revalida el hueco antes de reservar — si ya se ocupó recibirás un 400 ("ya no disponible"): recarga los huecos y reintenta.

3. Listar citas

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments?status=confirmed&limit=50"

Filtros: status (p. ej. confirmed, cancelled), limit (máx. 200), offset. Requiere appointments:read.

4. Cancelar una cita

curl -X DELETE "https://api.conviro.io/v1/api/appointments/APPOINTMENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Requiere appointments:write. Cancelar también elimina el evento del calendario conectado y avisa a tu equipo.

Webhooks — mantén tu CRM sincronizado

Suscríbete en Dashboard -> Developers -> Webhooks a:

• appointment.booked — se dispara con cada reserva confirmada (chat, widget de reservas o API)
• appointment.cancelled — se dispara con cada cancelación

El payload incluye appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone y channel — todo lo necesario para reflejar la reserva en tu CRM.

Opciones de calendario de un vistazo

> Consejo: Las claves API tienen límite de peticiones por clave. Para grandes volúmenes, prefiere los webhooks antes que consultar el endpoint de listado.