La API de Odontosys

La API de Odontosys deja que el sistema de una clínica —su sitio de reservas, su central de citas, un CRM, un asistente de inteligencia artificial— consulte la agenda y cree y elimine citas sin que nadie pase por la pantalla de Odontosys.

Esta documentación es para quien programa esa integración. Si sos de la clínica y buscás cómo crear la clave, está en la ayuda de Odontosys.

La API está en piloto. Se activa clínica por clínica y, durante el piloto, no tiene costo. Si la clínica todavía no la tiene, cualquier pedido responde 403 api_deshabilitada: la clínica la pide a Odontosys.

Qué se puede hacer

Operación	Para qué
`GET /ping`	Probar la clave y ver sus permisos, límites y uso del día
`GET /agendas`	Listar las agendas de la clínica con su jornada semanal
`GET /agendas/{id}/disponibilidad`	Ver los horarios libres de una agenda, día por día
`GET /pacientes/buscar`	Encontrar un paciente con ficha por celular, correo o número de ficha
`GET /citas` y `GET /citas/{id}`	Consultar citas
`POST /citas`	Crear una cita
`DELETE /citas/{id}`	Eliminar una cita que creó la integración

El detalle de cada una está en la Referencia. Modificar citas, dar de alta pacientes y recibir avisos cuando algo cambia (webhooks) no están en esta versión.

1. Conseguí una clave

La clave la crea el administrador de la clínica en Odontosys, en Configuración → Avanzado → API e integraciones. Al crearla elige:

Qué puede hacer (los permisos).
En qué agendas: todas, o sólo algunas.

La clave se ve una sola vez, al crearla. Tiene esta forma:

osk_3f9k2m7q_Xk3vN9…

osk_, un prefijo de 8 caracteres que identifica la clave (es público: aparece en la pantalla de la clínica y en los registros), otro _ y un secreto de 43 caracteres. Tratala como una contraseña: ver Seguridad.

2. Hacé el primer pedido

Todos los pedidos van a esta dirección, con la clave en la cabecera Authorization:

https://api.odontosys.com/publica/v1

curl https://api.odontosys.com/publica/v1/ping \
  -H "Authorization: Bearer osk_3f9k2m7q_…"

La respuesta dice con qué clínica estás hablando, qué permite la clave y cuánto te queda del día:

{
  "clinica": { "id": "10", "nombre": "Clínica Demo", "zonaHoraria": "America/Montevideo" },
  "clave": {
    "nombre": "Sitio web",
    "prefijo": "3f9k2m7q",
    "permisos": ["agendas:leer", "citas:crear"],
    "agendasPermitidas": null
  },
  "limites": { "porMinuto": 60, "altasPorDia": 100, "bajasPorDia": 50, "lecturasPorDia": 5000 },
  "uso": { "fecha": "2026-09-21", "altas": 3, "bajas": 0, "lecturas": 120 },
  "hora": "2026-09-21T14:03:11-03:00"
}

Si responde 401 no_autenticado, la clave no está bien copiada, se revocó o falta la palabra Bearer. Si responde 403 api_deshabilitada, la clínica todavía no tiene la API activa.

3. Seguí por la guía

Conceptos: la clave es la clínica, permisos, fechas y horas, ids.
Agendar una cita, paso a paso: el recorrido completo de un sitio de reservas.
Errores y Límites y reintentos: qué hacer con cada respuesta que no es un 2xx.

Probar sin molestar a nadie

Durante el piloto no hay un ambiente de prueba separado: las pruebas se hacen sobre la agenda real de la clínica. Para que no tengan efectos:

Creá las citas de prueba para alguien sin ficha ("paciente": { "nombre": "…", "telefono": "…" }): esas citas no mandan recordatorios. Una cita con paciente.id le manda al paciente real el recordatorio de siempre.
Usá fechas lejanas y una referenciaExterna que las identifique ("prueba-…"), y eliminalas al terminar con DELETE /citas/{id}.
Avisale a la clínica: las citas de prueba aparecen en su agenda mientras existen, y quedan en su Historial de actividad.

Descargar la descripción

La descripción completa de la API, en formato OpenAPI 3.1, está en https://api.odontosys.com/publica/v1/openapi.json. Se puede importar en Postman, Insomnia o un generador de clientes. No pide clave.

La API de Odontosys

#Qué se puede hacer

#1. Conseguí una clave

#2. Hacé el primer pedido

#3. Seguí por la guía