API de Undarda Behavior

Conecta el sistema de tu residencial con Undarda Behavior: da de alta personas, reporta incidentes y consulta el semáforo — todo por HTTPS, sin instalar nada.

¿Qué es esto? Tu software (el que ya usas en tu residencial: caseta, base de datos, sistema de acceso) llama a esta API desde donde ya corre. No se instala ningún programa de Undarda. Es como cuando un sitio cobra con una pasarela de pago: tu código hace las llamadas.

URL base: https://api.grupoundarda.com

Todas las respuestas son JSON. Todas las peticiones y respuestas usan UTF-8 y HTTPS obligatorio.

Autenticación

Cada petición lleva tu API key en un encabezado. No uses tokens de usuario ni contraseñas.

# En cada llamada:
X-Undarda-Service-Key: uk_a1b2c3d4e5f6...

La llave identifica a tu residencial y define qué puedes hacer (sus permisos) y cuántas llamadas por minuto (su límite). Cada petición queda auditada.

Obtener una API key

El administrador del residencial la genera desde el portal:

1.	Entra a app.grupoundarda.com → Integraciones.
2.	Crea una integración, elige sus permisos y su límite por minuto.
3.	Copia la llave `uk_…` — se muestra una sola vez. Guárdala en un lugar seguro (variable de entorno, gestor de secretos). Nunca la pongas en código público ni en el navegador.

Si una llave se filtra o deja de usarse, revócala desde el mismo portal — deja de funcionar al instante.

Permisos (scopes)

Permiso	Qué habilita
subjects:read	Consultar personas por documento o nombre (con semáforo).
subjects:write	Dar de alta personas en el padrón.
events:write	Reportar eventos de comportamiento sobre personas.
watchlist:read	Descargar el archivo completo de watchlist (para acceso/cámaras).

Reglas generales

Idempotencia	Toda escritura (alta, evento) exige el encabezado `Idempotency-Key` (mínimo 8 caracteres, único por operación). Si repites la misma llamada con la misma llave de idempotencia, no se duplica: te devolvemos la respuesta original con el encabezado `Idempotent-Replay: true`. Usa esto para reintentar sin miedo.
Límite de tasa	Cada API key tiene su tope de solicitudes por minuto. Al excederlo recibes `429`. Espera y reintenta.
Documentos	El documento (INE/CURP/pasaporte) es la llave para cruzar personas de forma confiable — captúralo cuando lo tengas.

GET/service/v1/subjects/lookupsubjects:read

Consultar una persona

Busca por documento exacto (recomendado) o por nombre. Ideal para la caseta: "¿quién es esta persona y de qué color está?".

Parámetros (query): documentType + documentId, o name (mínimo 2 caracteres).

GET /service/v1/subjects/lookup?documentType=INE&documentId=PEREZJ900101
X-Undarda-Service-Key: uk_...

// Respuesta 200 — con coincidencia:
{
  "match": true,
  "subject": {
    "id": "uuid-de-la-persona",
    "kind": "EMPLOYEE",
    "displayName": "JUAN PEREZ LOPEZ",
    "vitalStatus": "ACTIVE",
    "semaforo": { "color": "ROJO", "countDisabling": 1, "countNegative": 0, "countPositive": 2 }
  }
}
// Sin coincidencia:  { "match": false }

Con ?name= la respuesta trae subjects (hasta 5). El semáforo es un indicador de apoyo: la decisión de acceso siempre es del residencial.

POST/service/v1/subjectssubjects:write

Dar de alta una persona

Registra a una persona en el padrón desde tu base de datos. Es el endpoint que "alimenta" Undarda automáticamente.

Requisito legal: tu residencial es el responsable de los datos. Debes enviar privacyNoticeGiven: true, afirmando que ya entregaste el aviso de privacidad a esa persona. transferConsent: true solo si el aviso incluye la cláusula de compartir en la red (sin ella, la persona nunca se comparte con otros residenciales).

POST /service/v1/subjects
X-Undarda-Service-Key: uk_...
Idempotency-Key: alta-empleado-88421
Content-Type: application/json

{
  "kind": "EMPLOYEE",              // o "RESIDENT"
  "displayName": "JUAN PEREZ LOPEZ",
  "documentType": "INE",          // INE | CURP | PASSPORT | NONE
  "documentId": "PEREZJ900101",
  "contactPhone": "5512345678",   // opcional
  "privacyNoticeGiven": true,       // obligatorio
  "transferConsent": true            // habilita la red
}

// Respuesta 200:
{ "id": "uuid-nuevo", "kind": "EMPLOYEE", "displayName": "JUAN PEREZ LOPEZ",
  "documentType": "INE", "documentId": "PEREZJ900101", "createdAt": "2026-..." }

Guarda el id devuelto: lo necesitas para reportar eventos. Si la persona ya existe (mismo documento), recibes 409; usa el lookup para obtener su id.

POST/service/v1/eventsevents:write

Reportar un evento

Registra un evento de comportamiento sobre una persona existente (su id).

Categorías: POSITIVE (verde), NEGATIVE (amarillo), DISABLING (rojo — inhabilitante). Los DISABLING son imputación grave: el sistema espera el folio de la denuncia ante el Ministerio Público en mpComplaintNumber.

POST /service/v1/events
X-Undarda-Service-Key: uk_...
Idempotency-Key: evento-2026-000455
Content-Type: application/json

{
  "subjectId": "uuid-de-la-persona",
  "category": "NEGATIVE",
  "observations": ["LENTITUD", "ACTITUD_NEGATIVA"],
  "customText": "Detalle interno (no se comparte con la red)",
  "mpComplaintNumber": "CI-FGJ/774/2026"   // requerido si DISABLING
}

// Respuesta 200:
{ "id": "uuid-evento", "subjectId": "...", "category": "NEGATIVE",
  "observations": ["LENTITUD","ACTITUD_NEGATIVA"], "reportedAt": "2026-..." }

Un DISABLING sobre una persona con consentimiento de transferencia dispara la alerta de red a los residenciales donde esa persona coincide por documento.

GET/service/v1/watchlistwatchlist:read

Descargar la watchlist

Devuelve el padrón con semáforo, eventos codificados y fotos — pensado para sistemas de control de acceso o cámaras que precargan la lista. No incluye narrativas ni identidad de quien reporta. Contrato estable undarda-watchlist-v1.

GET /service/v1/watchlist
X-Undarda-Service-Key: uk_...

// Respuesta 200 (resumida):
{ "schema_version": "undarda-watchlist-v1", "total_subjects": 42,
  "subjects": [ { "id":"...", "display_name":"...", "document_id":"...",
    "semaforo":{"color":"ROJO"}, "events":[ ... ] } ] }

Errores

Los errores son JSON: { "statusCode": 403, "message": "…" }.

Código	Significa	Qué hacer
`400`	Petición inválida o falta `Idempotency-Key`	Corrige el cuerpo/encabezados.
`401`	Falta la llave o es inválida/revocada	Revisa `X-Undarda-Service-Key`.
`403`	La llave no tiene el permiso, o la licencia venció	Ajusta permisos en el portal / renueva licencia.
`404`	La persona no existe	Da de alta primero, o usa lookup.
`409`	Ya existe (documento duplicado)	Usa lookup para obtener su `id`.
`429`	Excediste el límite por minuto	Espera y reintenta (con la misma `Idempotency-Key`).

Flujo recomendado

Para "espejear" tu base de datos hacia Undarda cada vez que agregas o reportas a alguien:

1. Nueva persona en tu sistema
   → POST /service/v1/subjects   (con Idempotency-Key = tu id interno)
   → guarda el "id" de Undarda junto a tu registro

2. Incidente/observación en tu sistema
   → si no tienes el id: GET /service/v1/subjects/lookup?documentType&documentId
   → POST /service/v1/events   (con Idempotency-Key = tu folio interno)

3. En la caseta, alguien se presenta
   → GET /service/v1/subjects/lookup  → muestra el semáforo al guardia

Usa como Idempotency-Key un identificador estable de tu sistema (tu folio interno, tu id de empleado). Así, si tu proceso reintenta, nunca duplicas.

Aviso legal

Tu residencial es responsable de los datos que envía (LFPDPPP). Al dar de alta personas confirmas que entregaste el aviso de privacidad correspondiente. La información de esta API es de uso interno del residencial y de la red bajo convenio — nunca es pública. El semáforo es un apoyo a la decisión, no un veredicto.

Undarda Behavior — API v1 · Un producto de Grupo Undarda · Soporte de integración: ludemay@grupoundarda.com