API de Órbita

Para que un sistema de tu clínica lea sus números de Órbita: líneas de WhatsApp, chats recibidos y envíos de plantillas. Es sólo de lectura y nunca entrega mensajes, nombres ni teléfonos de pacientes.

Sacar el token

Lo hace el dueño o administrador de la clínica desde Órbita.

Entrá a Configuración › API

Engranaje de abajo a la izquierda › Integraciones › API. Tocá Nuevo token.
Elegí qué puede leer

Un nombre, qué puede leer, qué líneas ve y cuándo vence. Tocá Crear token.
Copialo

Se muestra una sola vez. Si se pierde, creá otro y revocá el viejo.

Cómo se usa

Pedidos GET a https://api.hiorbita.com, con el token en el encabezado. Las respuestas son JSON.

curl https://api.hiorbita.com/v1/lineas \ -H 'Authorization: Bearer oapi_TU_TOKEN'

Las fechas van con zona horaria: 2026-10-17T00:00:00-03:00. desde se incluye y hasta no.
Cada pedido abarca hasta 31 días.
Las fechas de las respuestas vienen en UTC.

GET

/v1/lineas

Las líneas de WhatsApp que ve el token.

{ "lineas": [ { "id": "16e542db-…", "nombre": "Recepción", "telefono": "5491100000000", "activa": true } ] }

GET

/v1/chats

permiso: chats recibidos

Los chats en los que el paciente escribió en el rango. Un chat es una línea y un celular.

GET /v1/chats?desde=2026-10-17T00:00:00-03:00&hasta=2026-10-18T00:00:00-03:00

Parámetros

`desde`, `hasta`	Obligatorios.
`linea`	Opcional: el id de una línea.
`limite`	Opcional: filas por página, hasta 500.
`cursor`	Para la página siguiente: el `siguiente` de la respuesta anterior. Cuando viene en `null`, no hay más.

Respuesta

{ "chats": [ { "chatId": "yUQVYH2p0IDf3bJnSEVL1E", "lineaId": "16e542db-…", "chatCreadoAt": "2026-10-17T11:38:45.630Z", "primerEntranteAt": "2026-10-17T11:38:42.000Z", "iniciadoPor": "paciente", "plantilla": null } ], "siguiente": null }

`chatId`	Id fijo del chat. No es el teléfono.
`chatCreadoAt`	Desde cuándo existe el chat de ese celular en esa línea.
`primerEntranteAt`	Primer mensaje del paciente dentro del rango.
`iniciadoPor`	`paciente`, `plantilla` (respondía a un envío de la clínica) o `clinica` (la clínica le había escrito antes).
`plantilla`	Nombre de la plantilla, si respondía a una.

GET

/v1/envios

permiso: envíos de plantillas

Cómo les fue a las plantillas: una fila por plantilla, día y línea.

GET /v1/envios?desde=2026-10-10T00:00:00-03:00&hasta=2026-10-17T00:00:00-03:00

Acepta también linea y plantilla (nombre exacto) para filtrar.

Respuesta

{ "envios": [ { "plantilla": "recontacto_semana_corta", "dia": "2026-10-16", "lineaId": "f900819f-…", "enviados": 20, "entregados": 16, "leidos": 13, "respondidos": 3, "fallidos": 3 } ] }

`leidos`	Si el paciente apagó las confirmaciones de lectura, WhatsApp no avisa y no cuenta.
`respondidos`	El paciente escribió dentro de las 24 h siguientes.

Límites

Qué	Límite
Por minuto	60 pedidos por token (hasta 10 seguidos)
A la vez	4 pedidos por token
Por día	10.000 pedidos por token
Rango	31 días por pedido
Página	500 chats

Si te pasás, la respuesta es 429 con Retry-After: esperá esos segundos y reintentá. Para un tablero alcanza con consultar cada 5 o 15 minutos.

Errores

Siempre en JSON, con un error que dice qué pasó.

Código	Cuándo
`400`	Un parámetro está mal (por ejemplo, fecha sin zona o más de 31 días).
`401`	Falta el token, está mal, venció o fue revocado.
`403`	El token no tiene ese permiso o no ve esa línea.
`429`	Se pasó un límite.
`503`	La consulta tardó demasiado: pedí un rango más corto.