API de Agendamiento para clientes e integradores

Integra disponibilidad, reservas, pagos y administracion operativa del sistema de agendamiento desde tu sitio web, app, CRM, ERP, call center o software interno.

Base URL: https://www.bitnodo.cl/api/v1/ Requiere credenciales Backend a backend Panel con token de sesion

Formato principal JSON UTF-8

Version actual /v1/*

Modo recomendado Tu backend consume la API

Centro base Necesitas center_ref

Entrada principal https://www.bitnodo.cl/api/v1/

Credencial minima Authorization: Bearer {API_KEY_PUBLIC|API_KEY_PANEL}

Acceso administrativo X-Panel-Token: {token}

Para quien aplica

Aplica a integraciones en sitios web, apps, ERP, CRM, call centers y otros sistemas externos.

Sitios web y apps propias

Muestra calendario, horarios y reserva dentro de tu web o app movil.

ERP, CRM o software interno

Puedes sincronizar profesionales, servicios, citas y estados para unificar operacion, ventas y soporte.

Contact center y canales asistidos

Tu equipo puede reservar desde otro sistema usando disponibilidad real y respetando las reglas del centro.

Partners o integradores SaaS

Pide credenciales separadas por ambiente y define si usaras solo agenda publica o tambien panel.

Credenciales requeridas

Antes de integrar, necesitas la URL base, llaves API y datos funcionales del centro.

API_KEY_PUBLIC

Para disponibilidad, contexto, reserva publica y consulta de pagos.

API_KEY_PANEL

Para operaciones administrativas y rutas de panel.

PUBLIC_GOOGLE_CLIENT_ID

Necesario para activar inicio/registro con Google en el sitio publico y login del panel.

Usuario de panel

Si usas panel, necesitas email, password y a veces center_slug para obtener X-Panel-Token.

Datos funcionales

Necesitas center_ref y, segun el flujo, service_ref, professional_ref o configuracion de pago.

Dato	Para que sirve	Obligatorio	Observacion
Base URL	Punto de entrada de la API	Si	https://www.bitnodo.cl/api/v1/
API_KEY_PUBLIC	Agenda publica, booking y pagos	Si para reservas	No debe exponerse en frontend publico.
API_KEY_PANEL	Panel y configuracion	Solo si administras el sistema	Trabaja junto con X-Panel-Token.
PUBLIC_GOOGLE_CLIENT_ID	Render de boton Google Identity Services	Si usaras Gmail/Google login	Configura origines autorizados en Google Cloud: https://www.bitnodo.cl y https://bitnodo.cl
Credenciales de panel	Login administrativo	Solo para rutas /v1/panel/*	Pueden requerir center_slug.
center_ref	Identifica el centro a consultar	Si	Se usa en contexto, slots, booking y pagos.

Arquitectura recomendada

Tu backend debe consumir la API y tu frontend debe consumir a tu backend.

Backend propio

Tu servidor llama a https://www.bitnodo.cl/api/v1/, firma con API key y entrega la respuesta procesada a tu web o app.

Frontend directo

No expongas API_KEY_PUBLIC ni API_KEY_PANEL en JavaScript del navegador.

Integracion en misma instancia

Si usas la agenda publica incluida en esta instalacion, existe una capa publica propia para ese flujo.

Panel administrativo

Las rutas /v1/panel/* son para sincronizar o administrar configuracion. No son necesarias si solo quieres mostrar disponibilidad y reservar.

Regla

No expongas llaves en el navegador. Consume https://www.bitnodo.cl/api/v1/ desde tu backend.

Flujo de integracion recomendado

Orden sugerido para una puesta en marcha limpia.

GET Paso 1 | /v1/status

Valida conectividad, credenciales y ambiente antes de desarrollar el resto de la integracion.

Requiere API key Primer request recomendado

POST Paso 2 | /v1/auth/login

Usalo cuando necesites configuracion o estados del panel. Devuelve el token de sesion administrativa.

Opcional Entrega X-Panel-Token

POST Paso 2.1 | /v1/auth/register

Registra usuarios finales por email o Google. Si el email ya existe, permite vincular el metodo faltante.

Requiere API_KEY_PUBLIC Soporta provider email y google

POST Paso 2.2 | /v1/auth/bootstrap-kit

Ejecuta setup inicial de cuenta recien creada: crea centro, horarios, profesionales y servicios en una sola llamada.

Requiere API_KEY_PUBLIC Usa X-Onboarding-Token de un solo uso

GET Paso 3 | /v1/public/agenda/context/{center_ref}

Carga centro, servicios, profesionales, branding, reglas de reserva y configuracion de pago.

Base funcional

GET Paso 4 | slots-range y slots-date

Consulta disponibilidad real para calendario mensual y horarios concretos del dia seleccionado.

Disponibilidad

POST Paso 5 | /v1/public/agenda/book/{center_ref}

Crea la reserva y devuelve appointment_id. Si hay pago obligatorio, deja la cita en pending_payment.

Reserva Devuelve appointment_id

POST Paso 6 | payment create + status

Si el centro cobra online, inicia Webpay o Flow y luego consulta el estado final de la cita y del cobro.

Solo si el centro cobra online

Convenciones

Patrones de request y response que deberias asumir en toda integracion externa.

Headers frecuentes

Accept: application/json
Authorization: Bearer {API_KEY_PUBLIC} para agenda y pagos
Authorization: Bearer {API_KEY_PANEL} para panel
X-Panel-Token: {token} para rutas administrativas
Content-Type: application/json salvo uploads de branding

Errores tipicos

400 parametros o payload invalido
401 credencial invalida o sesion expirada
404 recurso no encontrado
409 conflicto de cupo o concurrencia
422 validacion de negocio
429 rate limit excedido
500 o 502 error interno o del gateway de pago

Respuesta base

La API responde JSON UTF-8. En caso de error normalmente recibiras una llave error y, en ambientes de debug, una llave message con mayor detalle.

Ejemplo minimo

curl -X GET "https://www.bitnodo.cl/api/v1/public/agenda/context/mi-centro" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TU_API_KEY_PUBLIC"

Seguridad y operacion

Reglas que debes considerar para una integracion estable y segura.

No expongas credenciales

Las API keys deben vivir en variables de entorno o secretos de tu backend.

Rate limiting activo

La API aplica limites por bucket para login, consumo publico e integraciones internas.

request_id y soporte

Cada request recibe X-Request-Id. Guarda ese identificador en tus logs.

Pagos y callbacks

Las confirmaciones de pago son flujos server to server.

Escenario	Recomendacion	Motivo
Frontend propio	Consumir tu backend	Evita fuga de credenciales.
Reserva concurrente	Tratar 409 como conflicto real	El sistema bloquea cupos para evitar overbooking.
Pagos pendientes	Consultar estado antes de reintentar	Hay expiracion e idempotencia.
Flujos administrativos	Renovar token de panel al expirar	X-Panel-Token tiene vigencia acotada.

Autenticacion de usuarios finales

La API permite registro por email y por Google para usuarios customer del sistema.

POST /v1/auth/register

Registro o vinculacion de cuenta. Debes enviar Authorization con API_KEY_PUBLIC.

Headers

Accept: application/json
Authorization: Bearer {API_KEY_PUBLIC}
Content-Type: application/json

Reglas

full_name y email: obligatorios
provider: email o google
email exige password (minimo 8)
google exige google_sub

Ejemplos de request y response

{
  "full_name": "Ana Perez",
  "email": "ana@correo.cl",
  "phone": "+56912345678",
  "provider": "email",
  "password": "MiClaveSegura123"
}

{
  "full_name": "Ana Perez",
  "email": "ana@correo.cl",
  "provider": "google",
  "google_sub": "1160483928xxxxxxxxxxx",
  "avatar_url": "https://lh3.googleusercontent.com/a/..."
}

{
  "ok": true,
  "created": true,
  "user": {
    "id": 123,
    "full_name": "Ana Perez",
    "email": "ana@correo.cl",
    "phone": "+56912345678",
    "auth_provider": "email"
  },
  "bootstrap_kit": {
    "token": "obk_live_xxxxxxxxxxxxxxxxx",
    "expires_at": "2026-04-01T16:45:00Z",
    "header": "X-Onboarding-Token",
    "endpoint": "/v1/auth/bootstrap-kit"
  }
}

POST /v1/auth/bootstrap-kit

Endpoint de inicializacion de cuenta. Solo funciona una vez por usuario recien creado y con token de onboarding vigente.

Headers

Authorization: Bearer {API_KEY_PUBLIC}
X-Onboarding-Token: {token_recibido_en_register}
Content-Type: application/json

Incluye

center: nombre, slug, timezone, plan
business_hours: tramos por dia
professionals[]
services[]
Devuelve panel_session para acceso inmediato

Ejemplo de request minimo

{
  "center": {
    "name": "Centro Norte",
    "slug": "centro-norte",
    "timezone": "America/Santiago",
    "business_hours": [
      { "day_of_week": 1, "start_time": "09:00", "end_time": "18:00" },
      { "day_of_week": 2, "start_time": "09:00", "end_time": "18:00" },
      { "day_of_week": 3, "start_time": "09:00", "end_time": "18:00" },
      { "day_of_week": 4, "start_time": "09:00", "end_time": "18:00" },
      { "day_of_week": 5, "start_time": "09:00", "end_time": "18:00" }
    ]
  },
  "professionals": [
    { "full_name": "Dra. Camila Soto", "specialty": "Kinesiologia" }
  ],
  "services": [
    { "name": "Consulta Inicial", "duration_minutes": 30, "price": 20000 }
  ]
}

Errores comunes de onboarding (ejemplos)

{
  "error": "onboarding_token_required"
}

{
  "error": "onboarding_token_invalid"
}

{
  "error": "onboarding_token_expired"
}

{
  "error": "onboarding_token_already_used"
}

{
  "error": "bootstrap_not_allowed",
  "message": "Este usuario ya tiene un centro asociado"
}

POST Flujo rapido con curl (3 llamadas)

Secuencia recomendada para activar una cuenta nueva y dejarla lista para operar.

1) Registro por email y captura del token

curl -X POST "https://www.bitnodo.cl/api/v1/auth/register" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TU_API_KEY_PUBLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ana Perez",
    "email": "ana@correo.cl",
    "phone": "+56912345678",
    "provider": "email",
    "password": "MiClaveSegura123"
  }'

# Guarda bootstrap_kit.token del response
# Ejemplo: export ONBOARDING_TOKEN="obk_live_xxxxxxxxxxxxxxxxx"

2) Registro por Google (alternativa)

curl -X POST "https://www.bitnodo.cl/api/v1/auth/register" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TU_API_KEY_PUBLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ana Perez",
    "email": "ana@correo.cl",
    "provider": "google",
    "google_sub": "1160483928xxxxxxxxxxx",
    "avatar_url": "https://lh3.googleusercontent.com/a/..."
  }'

3) Bootstrap inicial con token de onboarding

curl -X POST "https://www.bitnodo.cl/api/v1/auth/bootstrap-kit" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TU_API_KEY_PUBLIC" \
  -H "X-Onboarding-Token: ${ONBOARDING_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "center": {
      "name": "Centro Norte",
      "slug": "centro-norte",
      "timezone": "America/Santiago",
      "business_hours": [
        { "day_of_week": 1, "start_time": "09:00", "end_time": "18:00" },
        { "day_of_week": 2, "start_time": "09:00", "end_time": "18:00" },
        { "day_of_week": 3, "start_time": "09:00", "end_time": "18:00" },
        { "day_of_week": 4, "start_time": "09:00", "end_time": "18:00" },
        { "day_of_week": 5, "start_time": "09:00", "end_time": "18:00" }
      ]
    },
    "professionals": [
      { "full_name": "Dra. Camila Soto", "specialty": "Kinesiologia" }
    ],
    "services": [
      { "name": "Consulta Inicial", "duration_minutes": 30, "price": 20000 }
    ]
  }'

# Si el token fue usado o expiro: HTTP 401/422 segun caso
# Si la cuenta ya tiene centro asociado: HTTP 409 (solo aplica a cuentas nuevas)

Endpoints principales para integracion externa

Endpoints mas utiles para integrar agenda, reserva y consulta operacional desde otro sistema.

GET /v1/status

Health check con informacion basica del servicio y del ambiente de pago.

POST /v1/auth/login

Body JSON

email: requerido
password: requerido
center_slug: opcional

Respuesta

token
expires_at
user
center
o requires_center_selection con centers[]

POST /v1/auth/register

Registra usuarios customer por email o Google. Usa API_KEY_PUBLIC y no expongas la llave en frontend.

Body JSON

full_name: requerido
email: requerido
provider: email o google
password: requerido si provider=email
google_sub: requerido si provider=google
phone y avatar_url: opcionales

Respuesta

ok
created (true si creo, false si solo vinculo)
user.id
user.auth_provider (email, google o both)
bootstrap_kit.token (solo si created=true)
bootstrap_kit.expires_at y bootstrap_kit.header

POST /v1/auth/bootstrap-kit

Crea kit inicial para cuenta nueva. Requiere token temporal de onboarding emitido en /v1/auth/register.

Body JSON

center.name: requerido
center.business_hours[]: opcional (si no, se crea L-V 09:00-18:00)
professionals[]: opcional
services[]: opcional

Respuesta

ok
center.id, center.slug
created.professionals, created.services
panel_session.token, panel_session.expires_at

GET /v1/public/agenda/context/{center_ref}[/{service_ref}[/{professional_ref}]]

Devuelve la fotografia base del centro para pintar la experiencia de agenda en tu sistema.

GET /v1/public/agenda/slots-range/{center_ref}/{from}/{to}[/{service_ref}[/{professionalRef}]]

Entrega disponibilidad diaria en rango para construir calendarios o vistas mensuales.

GET /v1/public/agenda/slots-date/{center_ref}/{date}[/{service_ref}[/{professional_ref}]]

Devuelve los horarios disponibles del dia seleccionado.

POST /v1/public/agenda/book/{center_ref}

Crea la reserva desde tu sistema. Si el servicio requiere pago online, devuelve una cita pendiente de pago para continuar el flujo.

Ejemplo de request y response

{
  "slot_id": 123,
  "customer": {
    "rut": "12.345.678-5",
    "full_name": "Nombre Cliente",
    "phone": "+56912345678",
    "email": "cliente@correo.cl"
  },
  "notes": "Primera visita"
}

{
  "ok": true,
  "appointment_id": 456,
  "requires_payment": true,
  "gateway": "webpay",
  "total_amount": 25000
}

GET /v1/public/agenda/payment/status/{center_ref}/{appointment_id}

Consulta el resultado actual del pago y del estado de la cita para cerrar el flujo en tu sistema.

Pagos

Si el centro tiene cobro online habilitado, el flujo de reserva se completa con Webpay o Flow segun configuracion.

POST /v1/public/agenda/payment/webpay-create/{center_ref}/{appointment_id}

Inicializa una transaccion Webpay Plus y devuelve la URL de redireccion al checkout.

POST /v1/public/agenda/payment/webpay-commit/{center_ref}

Confirma una transaccion Webpay desde backend y consolida el estado final de la cita.

POST /v1/public/agenda/payment/flow-create/{center_ref}/{appointment_id}

Genera un cobro Flow firmado y devuelve la URL para continuar el checkout.

POST /v1/public/agenda/payment/flow-confirm/{center_ref}

Callback de Flow para confirmacion automatica server to server.

GET /v1/public/agenda/payment/flow-return/{center_ref}?token=...

Consulta el resultado final de una transaccion Flow usando el token local asociado a la cita.

Requisito

Antes de usar pagos, valida con el administrador que el centro tenga gateway, ambiente y credenciales del proveedor correctamente configuradas.

Sincronizacion administrativa

Estas rutas sirven para mantener maestros o estados desde un software externo.

GET /v1/panel/dashboard

Devuelve contexto de sesion y datos basicos del centro actual.

GET POST /v1/panel/services

Lista o crea servicios del centro.

GET POST /v1/panel/professionals

Lista o crea profesionales del centro.

GET /v1/panel/agenda/events?from=YYYY-MM-DD&to=YYYY-MM-DD

Recupera citas y contexto del calendario.

POST /v1/panel/agenda/appointments/status

Actualiza el estado operativo de una cita.

Datos a mapear en tu sistema

Identificadores y objetos que conviene guardar o relacionar.

Dato	Uso	Recomendacion
center_ref	Identifica el centro de agenda	Guardarlo como clave de configuracion por cliente o sucursal.
service_id o service_ref	Identifica el servicio reservable	Mapearlo con tu catalogo comercial o medico.
professional_id o professional_ref	Identifica al profesional asignable	Sincronizarlo con tus fichas internas.
slot_id	Representa el cupo a reservar	Usarlo cuando reserves desde disponibilidad ya consultada.
appointment_id	Identifica la reserva creada	Persistirlo para estados, pagos y conciliacion.
customer.rut	Identidad del cliente final	Enviar RUT normalizado y mantenerlo consistente entre sistemas.

Checklist de salida

Antes de pasar a produccion, valida estos puntos.

Credenciales separadas por ambiente

Confirma URL, API keys y accesos distintos para sandbox, QA o produccion.

center_ref validado

Asegura que el centro, servicios y profesionales usados por tu integracion existen y estan activos.

Pagos probados extremo a extremo

Prueba create, retorno y consulta de estado con casos exitosos y fallidos.

Logs con request_id

Guarda request_id, appointment_id y errores devueltos para soporte y conciliacion.

Politica de reintentos

Define como responder a 409, 422 y 429 sin duplicar reservas.

Panel solo si lo usaras

Si no administraras maestros ni configuracion, limita la integracion a agenda publica.