Conceptos
Subjects, plantillas, credenciales, canales, distribuciones y eventos — y cómo se relacionan.
Seis objetos. Todo en el API es uno de ellos, o una lista de uno de ellos.
| Objeto | Prefijo | Qué es |
|---|---|---|
| Organización | org_ | El inquilino. Una llave de API pertenece exactamente a una, y por eso ningún endpoint recibe un parámetro de organización. |
| Subject | sub_ | La persona de la que trata una credencial, con tu externalId como llave. Una proyección de tu registro, no una copia de tu base de datos. |
| Plantilla | tpl_ / tpv_ | Qué dice y cómo se ve una credencial. Una plantilla tiene versiones; una versión se publica y queda congelada. |
| Credencial | cred_ | Una credencial de una persona. Tiene estado, campos resueltos al emitirse e historia. |
| Canal | cch_ | La credencial en una cartera. Apple Wallet es un archivo firmado; Google Wallet es un registro que guarda Google. |
| Distribución | — | Un acto de entregar una credencial: un enlace, un QR, un correo, una etiqueta NFC. |
Estados de una credencial
Una credencial está exactamente en uno de cinco estados: draft, issued, suspended, expired, revoked. La suspensión se deshace; la revocación no. El vencimiento ocurre solo, por la regla de validez de la versión de la plantilla o por el expiresAt que se dio al emitir.
Estados de un canal
Cada canal lleva su propio estado — pending, provisioned, installed, stale, failed, removed — porque que una credencial sea válida y que un teléfono la tenga de verdad son dos hechos distintos. Una credencial en issued con un canal en failed es una situación real, y el API lo dice en vez de promediar las dos.
Logros y otorgamientos
Nomi Academic cambia la plantilla por un logro: qué se obtuvo, sus criterios, sus habilidades y su nivel. Otorgarlo emite una credencial común respaldada por ese logro, con código público de verificación desde que existe. Todo lo que viene después —revocar, suspender, vencer, webhooks— es el mismo ciclo de vida.