API HTTP¶

El backend de WorkDone Sanitarios expone una API REST versionada. Esta página cubre las convenciones generales, los endpoints principales agrupados por consumidor, y en profundidad el endpoint /sync —el transaccional que mueve toda la operación offline-first.

Convenciones generales¶

• Versión 2 del contrato. Los endpoints custom van bajo /api/v1/app/*, /api/v1/admin/*, /api/v1/cliente/*, /api/v1/publico/* y /api/v1/smiley/*. El CRUD scaffold de JHipster queda en /api/* (sin /v1) por compatibilidad.
• Errores RFC 7807 (problem+json).
• Timestamps ISO 8601 con offset (ej. 2026-06-10T10:15:32.123-03:00).
• Autenticación según consumidor (ver Autenticación y autorización):
  • Operario móvil: JWT (Authorization: Bearer …), header X-Device-UUID obligatorio en login/refresh.
  • Terminal Smiley: headers X-Device-Uuid + X-Api-Key.
  • BackOffice / portal cliente: JWT.
  • QR público: sin auth, rate-limited por IP.

Endpoints principales¶

La tabla resume los endpoints documentados, agrupados por consumidor. No es exhaustiva del CRUD scaffold.

Autenticación¶

App móvil — operación¶

App móvil — gestión NFC¶

Admin (BackOffice) — selección¶

Terminal Smiley (kiosk)¶

Público (QR)¶

CRUD scaffold (JHipster, sin /v1)¶

Todo el CRUD scaffold /api/* exige ROLE_ADMIN. Endpoints verificados: /api/sanitarios, /api/tag-nfcs, /api/operarios, /api/sla-limpiezas, /api/dispositivos, /api/trabajos, /api/alertas, /api/empresas, /api/sucursals, /api/sectors, /api/tipo-sanitarios, /api/evento-limpiezas.

El endpoint /sync en profundidad¶

POST /api/v1/app/sync es el endpoint único transaccional del sync de operarios: en una sola llamada el cliente baja deltas de catálogos (pull) y sube su cola de trabajos y eventos NFC (push). Es retrocompatible con clientes v1.

Request¶

{
  "device_uuid": "...",
  "operario_id": 5,
  "last_sync": {              // null por tabla = pull completo de esa tabla
    "sanitario": "...", "tag_nfc": "...", "operario": "...",
    "sucursal": "...", "sector": "...", "tipo_sanitario": "...", "evento_limpieza": "..."
  },
  "trabajos_pendientes": [{
    "client_uuid": "...", "uuid_tag_leido": "...", "operario_id": 5,
    "ts_local_device": "2026-06-10T10:42:18.456-03:00",
    "tipo_tentativo": "EGRESO",
    "tipo": "LIMPIEZA",                       // v2 · LIMPIEZA | SUPERVISION · default LIMPIEZA
    "eventos": [{ "evento_id": 3, "codigo": "REPONER_INSUMOS", "observacion": "..." }]   // v2 · solo EGRESO
  }],
  "nfc_eventos_pendientes": [{                 // v2 · cola de gestión NFC (rol ADMIN)
    "client_uuid": "...", "accion": "ALTA_STOCK|ASIGNACION|DESASIGNACION|REASIGNACION",
    "uuid_tag": "...", "alias": "...", "sanitario_id": 12, "sanitario_nuevo_id": null,
    "ts_local_device": "..."
  }],
  "device_now": "2026-06-10T10:42:20.000-03:00",  // ANEXO DT/DT-B4 · hora del device al enviar · OPCIONAL
  "app_version": "0.1.0",                          // G1 · telemetría · OPCIONAL
  "os_version": "Android 15",
  "bateria_pct": 87,
  "red_tipo": "WIFI"                               // WIFI | CELULAR | ETHERNET | OTRA | SIN_RED
}

Response¶

{
  "server_ts": "...",                          // nuevo watermark
  "deltas": { /* updated[] + deleted_ids[] por cada uno de los 7 catálogos */ },
  "trabajos_procesados": [{
    "client_uuid": "...", "estado": "OK", "accion_real": "EGRESO",
    "trabajo_id": 1235, "sanitario_id": 5,
    "inicio_ts": "2026-06-10T10:15:32.000-03:00",   // verdad del server (clave en cierre automático)
    "fin_ts": "2026-06-10T10:42:18.000-03:00",      // null si quedó abierto (INGRESO) o no se persistió trabajo
    "duracion_seg": 1606,
    "tipo": "LIMPIEZA", "eventos": [{ "codigo": "...", "nombre": "...", "observacion": "..." }],
    "warnings": []
  }],
  "nfc_eventos_procesados": [{ "client_uuid": "...", "estado": "OK" }],
  "mi_ruta_hoy": { /* ... */ },                // V21_RUTAS · ruta asignada al operario hoy · OPCIONAL (NON_NULL)
  "config": { "silencio_cliente_seg": 8, "confirmar_egreso_min": 2 }   // ANEXO DT/DT-B4 · config remota anti doble-tap
}

Notas de los deltas (7 catálogos): tag_nfc expone estado + alias (la app resuelve taps solo contra estado='ASIGNADO'); operario expone rol; sanitario expone sector_id + tipo_sanitario_id; evento_limpieza.roles_permitidos viaja como array JSON (["OPERADOR_LIMPIEZA","SUPERVISOR"]), no CSV.

Estados por trabajo¶

El campo estado de cada ítem de trabajos_procesados puede ser:

Drift de reloj¶

Si el request trae device_now, el server estampa dispositivo.drift_seg = |device_now − server_now|. Si excede app.tap.drift-max-seg (default 300 s), genera una alerta RELOJ_DESVIADO por device (dedup por dispositivo_id), auto-atendida cuando un sync posterior reporta drift normal.

Códigos de error y conflictos¶

Errores RFC 7807. Códigos custom v2:

La resolución de conflictos en el push (asignación NFC, máquina de estados del tag) se explica en detalle en Sincronización.