Pasaportes — referencia de la API de PassportCraft

Listar pasaportes.

get/organizations/{organization}/passports

Ámbito: passports:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

Parámetros de consulta

limitcadenaOpcional

Cuántos registros devolver. El servidor puede devolver menos.

cursorcadenaOpcional

El next_cursor de la página anterior. Un cursor codifica los filtros con los que se emitió; enviarlo con otros filtros se rechaza con cursor_invalid.

statuscadenaOpcional

Devuelve solo los pasaportes que estén en este estado.

categorycadenaOpcional

Devuelve solo los pasaportes de esta categoría.

updated_sincecadenaOpcional

Una marca de tiempo RFC 3339. Devuelve los pasaportes actualizados en ese instante o después, que es como un integrador consulta los cambios sin volver a leer el catálogo entero.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports?status=published&limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 200

{
  "object": "list",
  "data": [
    {
      "object": "passport",
      "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "category": "textile",
      "status": "published",
      "gtin": "02000000000053",
      "external_id": "SKU-4471-BLK",
      "version": 4,
      "livemode": true,
      "created_at": "2026-08-01T09:12:44.918Z",
      "updated_at": "2026-08-01T14:03:22.501Z",
      "data": {
        "product_name": "Merino Crew Neck",
        "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
        "manufacturer_name": "Atelier Kestrel SAS",
        "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
        "manufacturer_country": "FR",
        "material_composition": [
          {
            "fiber": "Merino wool",
            "percentage": 100
          }
        ],
        "substances_of_concern": [
          "None above threshold"
        ],
        "gtin": "02000000000053"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports?status=published&limit=25

Crear un pasaporte.

post/organizations/{organization}/passports

Ámbito: passports:write
Idempotency-Key: Se acepta
Devuelve: 201

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

Cuerpo de la solicitud

categorycadenaObligatorio

Un id de categoría de GET /categories. Fija el esquema de campos y ya no puede cambiarse después.

external_idcadenaOpcional

Su propio identificador para este producto, de 1 a 255 caracteres. Único dentro de la organización y del modo, que es lo que permite conciliar sin guardar nuestros ids: el mismo id puede existir una vez en prueba y otra en producción.

dataobjetoOpcional

El documento del pasaporte. Las claves son nombres de campo del esquema de la categoría, más la clave document_id_key de cada campo que admite documentos; cualquier otra cosa se rechaza en lugar de guardarse en silencio.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "textile",
  "external_id": "SKU-4471-BLK",
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR"
  }
}'

Respuesta · 201

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": null,
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 1,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T09:12:44.918Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ]
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports

Obtener un pasaporte.

get/organizations/{organization}/passports/{id}

Ámbito: passports:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "published",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 4,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T14:03:22.501Z",
  "published_at": "2026-08-01T14:03:22.501Z",
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41

Aplicar un JSON Merge Patch a un pasaporte.

patch/organizations/{organization}/passports/{id}

Ámbito: passports:write
Idempotency-Key: Se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Cabeceras de solicitud

Expected-VersionenteroOpcional

La version del pasaporte que acaba de leer, como número entero. La escritura se rechaza con precondition_failed si el pasaporte cambió entretanto, que es la única forma de hacer segura una secuencia de leer, modificar y escribir frente a un editor concurrente. Use esta cabecera en lugar de If-Match. Reintente una escritura rechazada con una Idempotency-Key NUEVA: el rechazo queda registrado con la anterior y se reproduciría.

If-MatchcadenaOpcional

RECHAZADO con invalid_request salvo que sea exactamente *, y por tanto en cuanto lleva un ETag. Nuestra CDN compara If-Match con la RESPUESTA y reescribe el resultado: una escritura condicional se aplicaría y aun así se le comunicaría como 412, y el rechazo es lo que lo evita. Envíe la versión en Expected-Version. If-Match: *, que solo pide que el pasaporte siga existiendo, sí se acepta.

Cuerpo de la solicitud

dataobjetoOpcional

Un JSON Merge Patch (RFC 7386) que se aplica al documento del pasaporte. Omita una clave para dejarla intacta; envíe null para borrarla. Las listas se reemplazan enteras, nunca se fusionan.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41" \
  -X PATCH \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "recycled_content_percentage": 38,
    "recycling_instructions": "Return to any Atelier Kestrel store for fibre recovery."
  }
}'

Respuesta · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": null,
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 2,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T10:44:12.700Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "recycled_content_percentage": 38,
    "recycling_instructions": "Return to any Atelier Kestrel store for fibre recovery."
  }
}

PATCH /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41

Publicar un pasaporte.

post/organizations/{organization}/passports/{id}/publish

Ámbito: passports:write
Idempotency-Key: Se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Cuerpo de la solicitud

variant_review_fingerprintcadenaOpcional

Obligatorio cuando el pasaporte contiene tallas y colores introducidos por un asistente: la huella que devuelve GET …/variants/review, enviada después de que una persona haya revisado esas filas. Sin ella, la publicación se rechaza con variant_review_required; si las tallas y colores cambiaron después de esa revisión, con variant_review_changed. Envíela con una nueva clave de idempotencia. Cadena hexadecimal de 64 caracteres.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/publish" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Respuesta · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "published",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 4,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T14:03:22.501Z",
  "published_at": "2026-08-01T14:03:22.501Z",
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  },
  "warnings": [
    {
      "code": "environmental_claim_detected",
      "message": "This passport contains environmental claims (carbon neutral), found in its wording or in fields the brand marked as environmental information. From 27 September 2026, Directive (EU) 2024/825 requires the trader placing the product on the market to hold substantiation for such claims. Publishing succeeded; confirm the substantiation exists.",
      "doc_url": "https://passportcraft.com/docs/api/errors#environmental_claim_detected"
    }
  ]
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/publish

Despublicar un pasaporte.

Destructiva

post/organizations/{organization}/passports/{id}/unpublish

Ámbito: passports:write
Idempotency-Key: Se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/unpublish" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Respuesta · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 5,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:15:09.113Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/unpublish

Enviar un pasaporte a la papelera.

Destructiva

post/organizations/{organization}/passports/{id}/trash

Ámbito: passports:write
Idempotency-Key: Se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/trash" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Respuesta · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "trashed",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 6,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:19:44.002Z",
  "published_at": null,
  "trashed_at": "2026-08-02T08:19:44.002Z",
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/trash

Restaurar un pasaporte desde la papelera.

post/organizations/{organization}/passports/{id}/restore

Ámbito: passports:write
Idempotency-Key: Se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/restore" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Respuesta · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 7,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:21:03.884Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/restore

Comprobar un pasaporte contra el esquema de su categoría sin guardar.

post/organizations/{organization}/passports/{id}/validate

Ámbito: passports:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Cuerpo de la solicitud

dataobjetoOpcional

Campos que se fusionan antes de la comprobación, para que pueda probar una edición sin guardarla. En ningún caso se escribe nada.

variant_review_fingerprintcadenaOpcional

La huella que devuelve GET …/variants/review. Envíela para preguntar si la publicación que la lleva tendría éxito; sin ella, un pasaporte con tallas y colores introducidos por un asistente informa de la revisión como un error. Cadena hexadecimal de 64 caracteres; una huella caducada o mal formada se informa como incidencia en lugar de rechazarse, porque este punto final responde con una predicción.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validate" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "material_composition": null
  }
}'

Respuesta · 200

{
  "object": "validation",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validation",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "category": "textile",
  "schema_version": "1.0.0-draft",
  "dry_run": true,
  "valid": false,
  "publishable": false,
  "error_count": 2,
  "warning_count": 0,
  "checked_at": "2026-08-02T08:26:11.409Z",
  "issues": [
    {
      "object": "validation_issue",
      "field": "material_composition",
      "source": {
        "pointer": "/data/material_composition"
      },
      "rule": "required",
      "severity": "error",
      "message": "Material Composition is required",
      "message_key": "required",
      "message_params": {
        "field": "Material Composition"
      },
      "writable_via_api": true
    },
    {
      "object": "validation_issue",
      "field": "gtin",
      "source": {
        "pointer": "/data/gtin"
      },
      "rule": "required",
      "severity": "error",
      "message": "A GTIN is required before this passport can be published. A saved size or colour with its own barcode also satisfies this.",
      "writable_via_api": true
    }
  ]
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validate

Obtener las URL públicas y los GS1 Digital Links. gs1_digital_links incluye todas las variantes con variant_id, size y colour. La URI del GTIN principal aparece una vez con los datos de su variante; una URI principal con número de serie permanece separada.

get/organizations/{organization}/passports/{id}/links

Ámbito: passports:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 200

{
  "object": "passport_links",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "status": "published",
  "livemode": true,
  "gtin": "02000000000053",
  "serial_number": null,
  "public_url": "https://passportcraft.com/passport/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "qr_target": "https://passportcraft.com/01/02000000000053",
  "gs1_digital_links": [
    {
      "uri": "https://passportcraft.com/01/02000000000053",
      "gtin14": "02000000000053",
      "serial": null,
      "linkset_url": "https://passportcraft.com/01/02000000000053?linkType=linkset",
      "unavailable_reason": null,
      "variant_id": null,
      "size": null,
      "colour": null
    }
  ],
  "gs1_digital_link": {
    "uri": "https://passportcraft.com/01/02000000000053",
    "gtin14": "02000000000053",
    "serial": null,
    "linkset_url": "https://passportcraft.com/01/02000000000053?linkType=linkset",
    "unavailable_reason": null
  },
  "resolves_publicly": true,
  "not_resolvable_reason": null,
  "preview_url": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links

Listar lecturas de batería.

get/organizations/{organization}/passports/{id}/units/{unitId}/readings

Ámbito: units:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

unitIdcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Parámetros de consulta

limitcadenaOpcional

Número de lecturas que se devolverán, entre 1 y 100.

cursorcadenaOpcional

El next_cursor de la página anterior. Mantenga el mismo filtro de campo.

fieldcadenaOpcional

Devolver solo lecturas de este campo.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings?field=status&limit=50" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 200

{
  "object": "list",
  "data": [
    {
      "object": "unit_reading",
      "id": "a1100000-0000-4000-8000-000000000001",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings/a1100000-0000-4000-8000-000000000001",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "livemode": true,
      "field": "status",
      "value": "original",
      "observed_on": "2026-08-02",
      "source": "brand_statement",
      "note": null,
      "document_id": null,
      "recorded_by": "a1100000-0000-4000-8000-000000000002",
      "recorded_actor_type": "api_key",
      "recorded_via": "api",
      "recorded_at": "2026-08-02T09:31:18.446123Z",
      "legacy_import": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings?field=status&limit=50

Registrar una lectura de batería.

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

Ámbito: units:write
Idempotency-Key: Se acepta
Devuelve: 201

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

unitIdcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Cuerpo de la solicitud

fieldcadenaObligatorio

Un campo por batería del esquema de categoría.

valuetexto, número o número con unidadObligatorio

Un valor conforme a la definición del campo; número y unidad cuando el campo permite elegir unidad.

observed_oncadenaObligatorio

Fecha en que se midió o declaró el valor, con formato AAAA-MM-DD.

sourcecadenaObligatorio

measurement o brand_statement.

notecadenaOpcional

Nota opcional sobre el método o la evidencia, de hasta 500 caracteres.

document_idcadenaOpcional

Documento opcional de la biblioteca de la organización que respalda esta lectura.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "status",
  "value": "original",
  "observed_on": "2026-08-02",
  "source": "brand_statement"
}'

Respuesta · 201

{
  "object": "unit_reading",
  "id": "a1100000-0000-4000-8000-000000000001",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings/a1100000-0000-4000-8000-000000000001",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
  "unit_id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
  "unit": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "livemode": true,
  "field": "status",
  "value": "original",
  "observed_on": "2026-08-02",
  "source": "brand_statement",
  "note": null,
  "document_id": null,
  "recorded_by": "a1100000-0000-4000-8000-000000000002",
  "recorded_actor_type": "api_key",
  "recorded_via": "api",
  "recorded_at": "2026-08-02T09:31:18.446123Z",
  "legacy_import": false
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings

Desvincular un documento y eliminarlo de la biblioteca cuando ya no lo use nada más.

delete/organizations/{organization}/passports/{id}/documents/{documentId}

Ámbito: documents:write
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

documentIdcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Cabeceras de solicitud

If-MatchcadenaOpcional

RECHAZADO con invalid_request salvo que sea exactamente *. Este punto final no tiene forma condicional. DELETE es el único método que no hemos medido frente a nuestra CDN, que en algunas rutas compara If-Match con la RESPUESTA y reescribe un éxito como 412, y una desvinculación ya aplicada nunca debe comunicársele como un rechazo. If-Match: *, que solo pide que el documento siga existiendo, sí se acepta.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 200

{
  "object": "document.deleted",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "livemode": true,
  "detached": true,
  "deleted_from_library": true,
  "remaining_links": 0,
  "document_limit": 50
}

DELETE /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b