Crear una credencial
Plantillas, versiones y campos: definir qué dice una credencial antes de que alguien la tenga.
Antes de emitir hay que decir qué contiene la credencial. Para credenciales de cartera eso es una plantilla; para diplomas y certificados, un logro. Los dos funcionan igual: una definición con versiones, donde publicar una versión congela lo que significa para todo el que la reciba.
POST/v1/templates
Crea la plantilla y su primera versión en borrador.
POST /v1/templates
curl -X POST https://api.nomi-tech.com/v1/templates \
-H "Authorization: Bearer nomi_sk_live_EXAMPLE" \
-H "Content-Type: application/json" \
-d '{
"key": "membership_platinum",
"name": "Platinum membership",
"kind": "membership",
"definition": {
"fields": [
{ "key": "tier", "label": "Tier", "source": "attributes.tier", "placement": "primary" },
{ "key": "member", "label": "Member", "source": "displayName", "placement": "secondary" },
{ "key": "since", "label": "Since", "source": "attributes.memberSince", "placement": "auxiliary", "format": "date" }
],
"style": {
"backgroundColor": "#0A0A0A",
"foregroundColor": "#FFFFFF",
"labelColor": "#DFFF00"
},
"barcode": { "format": "qr", "source": "serial" },
"validity": { "duration": "P1Y" }
}
}'Los campos salen del subject
Cada campo nombra un source: una ruta del subject, como displayName o attributes.tier. Eso es lo que hace que una credencial siga a un registro en vez de congelar una copia suya — corrige el nivel de alguien en el subject y todas sus credenciales muestran el nuevo.
| Propiedad | Valores | Notas |
|---|---|---|
kind | membership, employee_id, student_id, loyalty, event, benefit, access, generic | Qué clase de credencial es. Decide el estilo de pase de la cartera. |
placement | header, primary, secondary, auxiliary, back | Dónde va el campo dentro del pase. |
format | text, date, number, currency | Cómo se dibuja el valor, en el idioma de quien lo lleva. |
barcode.format | qr, code128, pdf417, aztec | Lo que lee el lector en la puerta. |
validity.duration | Una duración ISO-8601, p. ej. P1Y | Cuánto dura una credencial emitida desde esta versión. |
Versiones
Una plantilla nace en borrador. POST /v1/templates/{id}/versions/{versionId}/publish es lo que la vuelve emitible, y es un acto aparte a propósito: lo que dice una versión publicada es lo que una credencial va a mostrar durante años, así que nada la publica por accidente. Editar una versión publicada significa crear otra — las credenciales ya emitidas se quedan con la versión con la que se emitieron.