Agendar desde tu sitio web y API

Botón o calendario en tu sitio, y la API para ver sillones libres y agendar citas.

Tus pacientes pueden agendar sin salir de tu sitio web, y tu sitio o tu sistema pueden ver los sillones libres y agendar citas a través de la API.

Agregar el calendario a tu sitio web

Primero activa Citas en línea (ver La agenda). Después, en Mi clínica → Pacientes y agenda → Citas en línea → Agregar a tu sitio web, elige cómo mostrarlo y toca el botón de copiar:

Botón: un botón flotante Agendar cita en la esquina de tu página que abre el calendario en una ventana. Pega el código antes de </body>. Puedes cambiar el texto con data-label, el color con data-color="#0f766e" y ponerlo a la izquierda con data-position="left".
Integrado: el calendario dentro de tu página, donde pongas el código (por ejemplo, en tu sección de Contacto). Se ajusta solo a su contenido.
Enlace: la dirección para un botón o menú que ya tengas.

Funciona en WordPress, Wix, Squarespace o cualquier página donde puedas pegar HTML. Funciona en todos los planes que incluyen citas en línea. Toca Vista previa para verlo tal como lo verán tus pacientes.

De dónde llegan las citas

Cada cita guarda de dónde llegó: el valor de data-source en el código (por ejemplo, sitio-web o google). Así sabes qué canal te trae pacientes. Si mides conversiones (Google Analytics, Meta), tu página recibe el evento toothbuddy:booked cuando alguien agenda; no lleva datos del paciente:

```html <script> window.addEventListener('toothbuddy:booked', function () { gtag('event', 'cita_agendada'); }); </script> ```

Sitios permitidos

Si dejas Sitios permitidos vacío, cualquier sitio puede mostrar tu calendario (como pasa con el enlace). Si escribes tus dominios (hasta 5, por ejemplo https://www.miclinica.com), solo aparecerá en ellos. Toca Guardar después de cambiarlos.

La API

Con los planes Progreso y Clínica Pro, en Mi clínica → Marca e integraciones → API y conexiones el Propietario(a) o el Administrador(a) crea claves para que otros sistemas trabajen con Tooth Buddy:

Solo disponibilidad: cuántos sillones están ocupados y libres en un periodo, y los horarios que se pueden agendar.
Disponibilidad + agendar: además agenda citas, para que tu programador(a) haga el calendario con tu propio diseño.

La API nunca da datos de tus pacientes: ni nombres, ni teléfonos, ni correos, ni sus citas. Solo cuenta sillones ocupados.

La clave se muestra una sola vez: cópiala al crearla. Trátala como una contraseña: úsala solo en tu servidor, nunca en el código de la página, porque cualquiera podría verla. Puedes revocarla en cualquier momento.

Disponibilidad y citas a través de la API

Cada petición lleva la clave en el encabezado Authorization: Bearer tbk_…. Para agendar, los horarios, la duración y los días son los mismos que configuraste en Citas en línea, que debe estar activado. La respuesta trae solo el número de la cita, su fecha, duración y estado.

GET /api/v1/booking: duración, días, cuántos días adelante, motivos, zona horaria y el enlace a tu aviso de privacidad.
GET /api/v1/booking/occupancy?from=2026-11-03T00:00:00Z&to=2026-11-04T00:00:00Z: por cada media hora del periodo (hasta 31 días), cuántos sillones están ocupados (busy) y libres (free), de un total de chairs. No necesita las citas en línea activadas.
GET /api/v1/booking/slots?date=2026-11-03: los horarios libres de ese día (en UTC) según tu configuración de citas en línea.
POST /api/v1/booking/appointments: agenda la cita.

```bash curl -X POST https://toothbuddy.app/api/v1/booking/appointments \ -H "Authorization: Bearer tbk_…" -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-123" \ -d '{"start":"2026-11-03T16:00:00.000Z","first_name":"Ana","last_name":"López", "phone":"5512345678","email":"ana@correo.com","reason":"cleaning", "accept_privacy":true,"source":"mi-app"}' ```

reason es checkup, cleaning, pain u other. Tu sitio debe mostrar tu aviso de privacidad y enviar accept_privacy: true solo si el paciente lo aceptó.
Si repites la petición con el mismo Idempotency-Key durante 24 horas (por ejemplo, tras un error de red), recibes la misma cita en lugar de una nueva. Si la primera petición falló, puedes reintentar con la misma clave. Usar la misma clave con otros datos da 422 idempotency_key_reused, y repetirla mientras la primera sigue en curso da 409 idempotency_in_progress (reintenta en unos segundos).
Como en la página de citas en línea, se usa la ficha del paciente si ya existe (mismo correo, o mismo teléfono y nombre), recepción recibe un aviso y el paciente un correo de confirmación.