05 — Dispositivos

Consulta de solo lectura sobre los celulares vinculados que capturan notificaciones de pago. La vinculación, pausa, reanudación y revocación de dispositivos son operaciones exclusivas del panel administrativo (requieren rol ADMIN con sesión de usuario) — una clave de API con alcance devices:read solo puede consultar su estado, no gestionarlos.

`GET /v1/devices`

curl https://api.yallego.app/v1/devices \
  -H "Authorization: Bearer yk_live_..."

La respuesta es un arreglo plano, sin data ni pagination (a diferencia de los listados de transacciones y entregas): un comercio tiene pocos dispositivos.

[
  {
    "id": "...",
    "label": "Celular caja principal",
    "manufacturer": "Xiaomi",
    "model": "Redmi Note 12",
    "os_version": "13",
    "app_version": "1.0.4",
    "status": "ACTIVE",
    "connectivity": "ONLINE",
    "last_seen_at": "2026-05-14T18:37:12Z",
    "paired_at": "2026-04-02T10:15:00Z",
    "paused_at": null,
    "paused_by": null,
    "paused_by_name": null,
    "latest_app_version": "1.0.5",
    "update_available": true,
    "app_download_url": "https://yallego.app/descargar"
  }
]

Campo	Valores	Significado
`status`	`ACTIVE`, `PAUSED`, `REVOKED`	Estado de gestión, lo controla el panel
`connectivity`	`ONLINE`, `DEGRADED`, `OFFLINE`	Derivado de `last_seen_at` al consultar (ver abajo)
`paused_at`, `paused_by`, `paused_by_name`	fecha, uuid, texto o `null`	Cuándo y quién pausó el dispositivo. Solo con `status: PAUSED`; `null` si no hay registro de esa pausa
`latest_app_version`	texto o `null`	Última versión publicada del app; `null` si Yallegó no la tiene configurada
`update_available`	booleano	`true` si `app_version` es menor que `latest_app_version`, sin contar sufijos como `-staging`. `false` si alguna de las dos se desconoce
`app_download_url`	URL o `null`	Enlace para descargar el app

Conectividad

connectivity se calcula con el tiempo desde el último heartbeat (el celular envía uno cada 2 minutos):

Valor	Último heartbeat
`ONLINE`	Hace menos de 3 minutos
`DEGRADED`	Hace 3 a 15 minutos
`OFFLINE`	Hace 15 minutos o más, o nunca envió uno

DEGRADED es un aviso temprano y no genera evento: el webhook device.offline sale al pasar a OFFLINE y device.online, cuando vuelve (ver 06 — Catálogo de eventos).

Filtrar por estado

Sin filtro, el listado incluye todos los dispositivos, también los desvinculados (REVOKED): así se comportó siempre y no cambia para quien ya consume la ruta. Para quedarte solo con algunos estados, usa status con uno o varios valores separados por coma (o repitiendo el parámetro):

# Solo los vinculados: activos y pausados
curl "https://api.yallego.app/v1/devices?status=ACTIVE,PAUSED" \
  -H "Authorization: Bearer yk_live_..."

Un valor que no sea ACTIVE, PAUSED o REVOKED responde 400 VALIDATION_ERROR.

`GET /v1/devices/{id}`

Mismo formato que un elemento del listado. 404 NOT_FOUND si el dispositivo no existe, pertenece a otro tenant o el id no es un UUID.

Uso típico

Si tu integración depende de que el dispositivo de captura esté en línea (por ejemplo, para alertar a un supervisor si dejó de recibir cobros), suscribe el evento device.offline en un webhook en vez de hacer polling sobre este endpoint — ver 06 — Catálogo de eventos.