Examples
Las cinco peticiones que realmente hace una integración
Emitir un pasaporte. Añadir un evento. Firmar una declaración de proveedor. Verificar una. Servir un escaneo. La mayoría de integraciones son estas cinco, repetidas; todo lo demás es mapeo.
- Empiece con
- Emitir + añadir
- Añadir más adelante
- Declaraciones firmadas
- Entorno
- Primero el sandbox
Definition
¿Qué hace realmente una integración de pasaportes típica?
Cinco operaciones, repetidas. Emitir un pasaporte contra un identificador GS1. Añadir eventos EPCIS 2.0 conforme el producto se mueve. Recoger declaraciones firmadas de proveedores. Verificar una declaración que le presentan. Y servir la vista pública cuando alguien escanea el portador del producto.
The volume is dominated by the first two. The difficulty is dominated by the third, which is a supplier relationship problem rather than a technical one.
01
Emitir un pasaporte
curl https://api.circuleid.com/v1/passports \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"gtin": "09506000134352",
"productGroup": "textiles",
"level": "model",
"record": {
"name": "Merino Crew Knit",
"materials": [
{ "name": "merino wool", "share": 0.82, "certification": "RWS" },
{ "name": "recycled polyamide", "share": 0.18 }
],
"carbonFootprint": { "value": 14.2, "unit": "kgCO2e", "method": "ISO 14067" }
}
}'02
Añadir un evento de la cadena de suministro
curl https://api.circuleid.com/v1/events \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-d '{
"type": "ObjectEvent",
"action": "OBSERVE",
"eventTime": "2026-03-14T09:22:00+01:00",
"epcList": ["urn:epc:id:sgtin:0950600.013435.SN8817403"],
"bizStep": "urn:epcglobal:cbv:bizstep:commissioning",
"disposition": "urn:epcglobal:cbv:disp:active",
"bizLocation": { "id": "urn:epc:id:sgln:0950600.00001.0" }
}'03
Firmar una declaración de proveedor
curl https://api.circuleid.com/v1/credentials \
-H "Authorization: Bearer $SUPPLIER_API_KEY" \
-d '{
"type": "RecycledContentCredential",
"issuer": "did:web:mill.example.com",
"subject": "01/09506000134352",
"validUntil": "2027-03-14T00:00:00Z",
"claim": {
"material": "polyamide",
"recycledShare": 0.18,
"basis": "mass",
"chainOfCustody": "mass-balance"
}
}'04
Verificar una afirmación que le han presentado
curl https://api.circuleid.com/v1/credentials/verify \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-d '{ "credential": { /* the credential as presented */ } }'
# {
# "verified": true,
# "issuer": "did:web:mill.example.com",
# "issuedAt": "2026-03-14T09:31:02Z",
# "status": "active" # "revoked" fails verification
# }05
Servir un escaneo
# What the phone requests when a consumer scans the carrier:
curl https://id.circuleid.com/01/09506000134352 \
-H "Accept: application/json"
# A browser gets the rendered public passport instead.
# A verified recycler presenting a credential gets the treatment tier
# from the same URL — the resolver decides, not the caller.Patrones
Dónde suele residir cada uno
Tubería de emisión
Un trabajo programado que lee el PLM y emite pasaportes para la siguiente serie de producción.
Ingesta de eventos
Un servicio que traduce mensajes de WMS y MES a eventos EPCIS conforme se producen.
Portal de proveedores
Donde los proveedores de segundo nivel envían y firman las afirmaciones que usted no puede hacer por sí mismo.
Tienda
Leer el nivel público para mostrar datos de sostenibilidad respaldados en una ficha.
El propio portador
Ningún código suyo: el resolutor sirve el escaneo directamente.
Recepción de la recogida
Leer el nivel de tratamiento en la línea de una instalación de devoluciones o reciclaje.
Respuestas
Preguntas frecuentes
¿De qué ejemplo debería partir?
Emitir un pasaporte y luego añadir un evento. Esas dos operaciones cubren la mayor parte del tráfico de una integración y le obligan a fijar el modelo de identidad —modelo, lote o artículo—, que es la decisión de la que depende todo lo demás y la más difícil de cambiar después.
¿Tengo que manejar credenciales desde el primer día?
No. Un pasaporte con datos sin firmar sigue siendo un pasaporte que funciona; simplemente no puede demostrar quién afirmó cada cifra. La mayoría de programas emiten primero y añaden declaraciones firmadas de proveedores a medida que estos se incorporan, que es además el orden que la realidad permite.
¿Qué recibe realmente el consumidor de un escaneo?
El nivel público del pasaporte, resuelto desde el identificador GS1 Digital Link del soporte, presentado como página para un navegador o devuelto como JSON al sistema que lo solicite. Sin autenticación, sin cuenta y sin perfil de la persona que escanea.
¿Podemos probar sin tocar producción?
Sí. Las claves de sandbox se resuelven contra un nombre de host distinto, y los pasaportes de sandbox se comportan exactamente como los de producción. Como un pasaporte de producción es un artefacto público de larga vida, la separación se impone en lugar de ser convencional: una clave de sandbox simplemente no llega a producción.
Next step
Ejecute las dos primeras con una clave de sandbox
Emita un pasaporte y añada un evento. Con eso basta para fijar el modelo de identidad, la decisión sobre la que descansa todo lo demás.