Destinatarios

Subjects: crearlos de forma idempotente, encontrarlos y qué significa borrar uno.

Las personas de las que tratan las credenciales son subjects, y llevan como llave tu propio externalId en vez de un identificador que inventemos nosotros. Esa es toda la razón por la que una sincronización se puede volver a correr sin producir dos de cada quien.

PUT/v1/subjects

Crear o actualizar, idempotente sobre externalId. Manda el mismo cuerpo dos veces y obtienes el mismo subject.

Cuerpo

{
  "externalId": "crm_example_001",
  "displayName": "Alex Morgan",
  "email": "alex@example.com",
  "status": "active",
  "attributes": { "tier": "Platinum", "department": "Operations" },
  "attributesMode": "merge"
}

En attributes vive todo lo que una plantilla pueda leer. attributesMode decide si el cuerpo se mezcla con lo que ya había o lo reemplaza — merge cuando un sistema es dueño de un campo, replace cuando es dueño del registro entero.

Manda lo que la credencial necesita, y nada más

attributes acepta cualquier cosa, y por eso el camino más corto —empujar el registro entero que tu sistema ya tiene— es justo el que hay que evitar. Una credencial es un objeto que da la cara: lo que se le mete puede acabar impreso en un pase, mostrado en una página de verificación, exportado, y habrá que responder por ello después.

  • Manda los campos que lee una plantilla. Si ningún campo, regla ni diseño lo nombra, no pertenece a la credencial.
  • Deja donde están los datos sensibles. Número de identificación, salud, salario, anotaciones — nada de eso hace falta para probar que alguien es socio, estudiante o empleado.
  • Usa externalId como enlace. Es tu propia llave para esa persona, así tu sistema sigue siendo el sitio donde vive el expediente completo y Nomi guarda una proyección.
  • Elige attributesMode a conciencia. merge cuando un sistema es dueño de un campo; replace cuando es dueño del conjunto y un campo ausente significa *quitado*.
  • Desactiva en vez de borrar, y borra primero en tu sistema: lo que no se manda no se filtra ni hay que limpiarlo aquí.

GET/v1/subjects

Lista, con status y una q de texto libre sobre nombre, correo e identificador externo.

GET/v1/subjects/{id}

Un subject, con la cuenta de credenciales que lleva.

DELETE/v1/subjects/{id}

Solo para quien no lleva ninguna credencial — en cualquier otro caso contesta 409.

Fotografías

PUT /v1/subjects/{id}/photo adjunta el retrato que muestra un carné de empleado o estudiantil. GET /v1/subjects/{id}/photo/{density} la sirve en la densidad que pida el dispositivo.

Grupos

/v1/groups junta subjects en cohortes: un grupo de clase, un departamento, una promoción. Un grupo también es aquello sobre lo que decide una política, y por eso meter a alguien en uno puede emitirle su credencial.

Verificación

Preguntar si una sirve.

API REST

Conectar tu propio sistema.