La API de reserva de citas abierta a todas sus herramientas
Tokens con permisos, webhooks firmados, aplicaciones OAuth, Zapier y Make. Sus reservas circulan allí donde usted trabaja.
Una API de reserva de citas resulta útil en cuanto sus reservas tienen que vivir fuera de la herramienta de reservas: un software de gestión, un portal de clientes, un almacén de datos, una herramienta de automatización. Sin ella, solo queda exportar a mano y volver a teclear.
Por qué una API de reserva de citas completa
Artibox Calendar ofrece una API REST pública en sus rutas /api/v1: tipos de cita, disponibilidad, reservas, encuestas, enlaces únicos, envíos de enlaces y webhooks. Sigue las mismas reglas que la aplicación: los mismos permisos, el mismo aislamiento entre organizaciones y la misma reserva con bloqueo. Lo que puede hacer un token es lo que puede hacer su miembro; nada más.
Para los equipos sin desarrolladores, los conectores de Zapier y Make conectan sus citas con sus herramientas sin escribir código. Y para HubSpot, Salesforce o Pipedrive, las integraciones con CRM ya están listas.
Cómo funciona
Cree un token personal
Elija sus permisos (leer las reservas, escribir los tipos…). El token empieza por rdv_pat_.
Llame a la API
Envíe el token en la cabecera x-api-key. Fuera de sus permisos, la llamada se rechaza.
Suscríbase a los eventos
Declare una dirección de webhook y los eventos que le interesan.
Siga las entregas
El registro de webhooks muestra cada envío; puede hacer pruebas y reenviar.
Una API pensada para producción
Tokens con permisos
Cada token personal lleva permisos precisos: leer el usuario, leer o administrar la organización, leer o escribir los tipos, leer la disponibilidad, leer o escribir las reservas, escribir los enlaces y gestionar los webhooks. Una llamada fuera de sus permisos recibe una respuesta 403. Un token nunca puede crear otro token.
Límites claros
Cada token puede hacer 100 llamadas por minuto. Las listas se paginan por número de página. Las creaciones aceptan una cabecera Idempotency-Key, que se conserva 24 horas: una llamada repetida tras un corte de red no crea duplicados. Las citas creadas por la API llevan el origen «api».
El mismo motor que la página de reservas
Una reserva creada por la API sigue las mismas reglas que en su página de reservas online: antelación, márgenes, máximo diario y calendarios conectados. Si el horario se acaba de ocupar, la respuesta es un rechazo claro, nunca una reserva duplicada.
Webhooks firmados
Los eventos
Su aplicación recibe un aviso cuando una cita se crea, se cambia, se cancela o se registra su resultado, cuando un invitado vota en una encuesta o se confirma una encuesta, y cuando cambia un tipo de cita. Cada envío está firmado (cabecera X-Signature): usted comprueba que procede realmente de Artibox Calendar.
Entregas fiables
Si su servidor no responde, la entrega se reintenta, de un minuto a doce horas. Tras 20 fallos consecutivos, la suscripción se desactiva. El registro conserva 30 días de entregas; un botón envía un evento de prueba y otro reenvía una entrega. Por seguridad, los webhooks no pueden apuntar a una dirección de la red interna.
OAuth para editores de software
¿Desarrolla una herramienta que usan otras organizaciones? Declare una aplicación OAuth en Ajustes › Integraciones. Sus usuarios ven una pantalla de consentimiento y después su aplicación recibe un código de un solo uso, válido 10 minutos y protegido con PKCE (S256). El token de acceso dura 2 horas; el token de actualización cambia en cada uso, y si se reutiliza se corta todo el acceso. Cada miembro puede retirar un acceso desde «Aplicaciones conectadas».
Sin código: Zapier, Make y el widget
Zapier y Make
Los conectores de Zapier y Make se conectan como aplicaciones OAuth: lance un escenario con cada nueva cita, envíe un enlace de reserva desde otra herramienta o busque una cita por correo electrónico.
El kit de integración
El script widget.js añade un botón o un enlace de reserva a su web. La reserva se abre en una ventana aparte. Los parámetros de seguimiento (utm_*, gclid, fbclid, ref) se guardan en la cita, y un contexto firmado puede rellenar la reserva desde su herramienta.
Planes y seguridad
La API (tokens personales, aplicaciones OAuth) y los conectores de Zapier y Make forman parte del plan Pro; los webhooks, del plan Equipo. El detalle está en la página de precios. Solo se conserva la huella de los tokens, nunca el token en claro: vea seguridad y RGPD.
Para empezar, siga la ayuda sobre API y tokens (FR) y webhooks (FR). Para elegir entre las dos herramientas de automatización, lea Zapier o Make (FR). Definiciones: API (FR), webhook (FR).
Para quién
Equipos comerciales
Conectar las citas con sus herramientas de ventas y de informes.
Agencias (FR)
Integrar la reserva de citas en las webs y las herramientas de sus clientes.
Selección de personal (FR)
Crear las entrevistas desde su software de seguimiento de candidatos.
Formadores (FR)
Enviar las inscripciones a las sesiones a su herramienta de gestión de formación.
Preguntas frecuentes
¿Cómo me autentico en la API de reserva de citas?
Con un token personal (rdv_pat_…) o un token de acceso OAuth, enviado en la cabecera x-api-key. Cada token tiene sus permisos.
¿Cuáles son los límites de llamadas?
100 llamadas por minuto y por token. Las creaciones aceptan una cabecera Idempotency-Key, que se conserva 24 horas.
¿Cómo compruebo que un webhook procede realmente de Artibox Calendar?
Cada envío está firmado en la cabecera X-Signature. Compruebe la firma antes de procesar el contenido.
¿Qué ocurre si mi servidor no está disponible?
La entrega se reintenta de un minuto a doce horas. Tras 20 fallos, la suscripción se desactiva; puede reenviar las entregas desde el registro, que se conserva 30 días.
¿En qué plan se incluye la API?
La API, Zapier y Make desde el plan Pro; los webhooks desde el plan Equipo. Vea los precios.
Conecte sus citas con sus herramientas
Cree su cuenta gratis y, después, su primer token de API.
Crear mi cuenta