API overview
Cuatro recursos, y las relaciones entre ellos
Los pasaportes describen. Los eventos registran. Las credenciales demuestran. La resolución sirve. Tener claros esos cuatro antes de empezar es lo que evita tener que deshacer una integración seis meses después.
- Ruta base
- /v1
- Formato
- JSON sobre HTTPS
- Auth
- Claves portadoras acotadas
Definition
¿Cómo está estructurada la API del pasaporte?
En torno a cuatro recursos. Los pasaportes contienen el registro de producto y su política de acceso. Los eventos registran qué le ocurrió a un objeto, serializados como GS1 EPCIS 2.0. Las credenciales portan declaraciones firmadas como W3C Verifiable Credentials. La resolución convierte un identificador GS1 Digital Link en la vista a la que un llamante tiene derecho.
Each serialises somebody else’s standard — EPCIS 2.0, VC 2.0 and GS1 Digital Link — so what you build against these endpoints keeps working against a conforming implementation that is not ours.
El modelo
Qué recurso responde a qué pregunta
| Resource | Respuestas | Estándar |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | Modelo alineado con CIRPASS |
| Event | "What happened to this object, where and when?" | GS1 EPCIS 2.0 (JSON-LD) |
| Credential | "Who asserted this, and can I check it myself?" | W3C Verifiable Credentials 2.0 |
| Resolution | "Someone scanned this — what do they get?" | GS1 Digital Link |
Endpoints
La superficie, en resumen
Pasaportes
Cree, lea, actualice y versione el registro de producto. Informe de brechas frente al grupo de productos.
Eventos
Añada eventos EPCIS 2.0 y consulte el historial completo de una identidad de objeto.
Credenciales
Emitir, presentar, verificar y revocar declaraciones firmadas contra un pasaporte.
Resolución
La ruta de lectura pública que sigue un escaneo, devolviendo el nivel adecuado a quien llama.
Autenticación
Claves portadoras acotadas, por entorno y por capacidad.
Referencia completa
Cada endpoint, parámetro, forma de respuesta y código de error.
Respuestas
Preguntas frecuentes
¿Cuáles son los recursos principales de la API?
Cuatro. Los pasaportes contienen el registro de producto y su política de acceso. Los eventos registran qué le ocurrió a un objeto, serializados como EPCIS 2.0. Las credenciales portan declaraciones firmadas como W3C Verifiable Credentials. La resolución es la vía de lectura: entra un identificador GS1 Digital Link, sale la vista adecuada al llamante.
¿Cuándo debo escribir un evento en lugar de actualizar el pasaporte?
Actualice el pasaporte cuando esté corrigiendo o completando su descripción. Escriba un evento cuando haya ocurrido algo: un paso completado, una custodia transferida, una reparación realizada. La regla práctica es que un campo del pasaporte responde a «¿qué es esto?» y un evento responde a «¿qué le ha pasado?».
¿Por qué la resolución es algo distinto de leer un pasaporte?
Porque la resolución es lo que hace un escaneo, y es pública, anónima y cacheable. Leer un pasaporte por la API está autenticado y devuelve aquello a lo que su clave da derecho. Sirven a llamantes distintos con garantías distintas, así que confundirlos supondría que la vía pública heredase el coste de la privada.
¿Está versionada la API?
Sí, en la ruta: todo está bajo `/v1`. Los cambios aditivos se publican sin subir de versión; cualquier cosa que rompiera una integración existente recibe una versión nueva con un periodo de solapamiento. Los registros de pasaporte se versionan por separado, porque un pasaporte sobrevive a cualquier versión de API con la que se creó.
Next step
Leer después la referencia
Ya tiene el modelo. La referencia contiene el esquema, los parámetros y el contrato de errores.