CirculeID

Documentation

Empiece aquí

Todo lo necesario para emitir un pasaporte, añadir eventos de la cadena y verificar una credencial, con los estándares a los que se mapea cada cosa, de modo que nada de lo que construya quede cautivo de esta plataforma.

Referencia de la APIObtener una clave de API
Protocolo
JSON sobre HTTPS
Eventos
EPCIS 2.0 JSON-LD
Credenciales
W3C VC 2.0

Definition

¿Cómo se emite un pasaporte digital de producto mediante una API?

Cree un recurso de pasaporte sobre un identificador GS1 con el registro de producto, añada eventos EPCIS 2.0 conforme el producto se mueve, y emita W3C Verifiable Credentials para las declaraciones que deban ser demostrables. La lectura resuelve el identificador y devuelve la vista a la que dan derecho las credenciales del llamante.

The wire formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.

Inicio rápido

Su primer pasaporte

Una petición autenticada. La respuesta lleva el Digital Link resoluble y la carga útil del portador que usted imprime o codifica.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Content-Type: application/json" \
  -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 }
      ]
    }
  }'

Illustrative request shape. The API reference carries the authoritative schema and error contract.

Referencia

Adónde ir después

Ocho páginas cubren toda la superficie. Están ordenadas como suele avanzar una integración.

Ruta de integración

De la clave de API a un pasaporte resoluble

Cuatro pasos. El segundo es el único que suele llevar más de una tarde.
  1. 01

    Obtener una clave acotada

    Las claves se acotan por entorno y por capacidad, de modo que un servicio de emisión nunca tiene acceso de lectura a datos restringidos.

  2. 02

    Mapear el registro de producto

    Envíe su maestro de producto contra su identificador GS1. La respuesta nombra los campos que el grupo de productos sigue exigiendo.

  3. 03

    Añadir eventos y credenciales

    Escriba eventos EPCIS 2.0 a medida que el artículo se mueve; emita credenciales para las afirmaciones que deban resistir un escrutinio independiente.

  4. 04

    Resolver y suscribirse

    El identificador resuelve a la vista adecuada al llamante, y los webhooks avisan a sus sistemas cuando algo cambia.

Respuestas

Preguntas frecuentes

¿Qué necesito antes de poder emitir un pasaporte?

Una clave de API, un identificador GS1 para el producto y el propio registro de producto. Si aún no tiene identificadores GS1, esa es la primera dependencia a resolver: proceden de su organización miembro de GS1, no de nosotros, porque la identidad debe ser globalmente única fuera de nuestra plataforma.

¿Hay un entorno de pruebas?

Sí. Las claves están limitadas por entorno, así que las de sandbox no pueden tocar pasaportes de producción y las de producción no pueden usarse por accidente en un banco de pruebas. Los pasaportes de sandbox se resuelven exactamente igual que los de producción, contra un nombre de host de resolutor distinto.

¿Cuáles son los formatos de transporte?

JSON sobre HTTPS para la API. Los eventos siguen la serialización JSON-LD de GS1 EPCIS 2.0, y las credenciales el modelo de datos de W3C Verifiable Credentials 2.0. Donde un estándar define una representación la usamos en vez de inventar una, lo que significa que el utillaje existente para esos estándares funciona con nuestra salida.

¿Cómo deben tratarse los errores?

La API devuelve códigos de estado HTTP convencionales con un cuerpo de error estructurado que nombra el campo y la restricción incumplida. Los errores de validación se devuelven completos y no de uno en uno, de modo que un registro mal formado muestra todos sus problemas en una respuesta en vez de en cinco viajes de ida y vuelta.

¿Cómo obtenemos soporte durante la integración?

Por el canal de soporte de su cuenta, o por la vía de contacto si todavía está evaluando. Las preguntas de integración que revelan una laguna en la documentación se tratan como defectos de documentación, que es la única manera de que una referencia siga siendo exacta a medida que la API crece.

Next step

Emitir un pasaporte contra su propio GTIN

Obtenga una clave de sandbox, envíe un registro de producto y vea qué resuelve el portador que devuelve.

Obtener una clave de APIReferencia de la API

Index

Lecturas relacionadas