Ir al contenido

Recursos

Variantes

Todos los endpoints de Variantes, con el ámbito que imponen, el cuerpo que admiten, una respuesta legible y los rechazos que pueden devolver.

Listar variantes de talla y color.

get/organizations/{organization}/passports/{id}/variants
Á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.

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.

gtincadenaOpcional

Devolver solo la variante con este GTIN. Los GTIN válidos de 8, 12, 13 o 14 dígitos se normalizan a 14 dígitos.

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/variants?limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Respuesta · 200
{
  "object": "list",
  "data": [
    {
      "object": "variant",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

Crear variantes de talla y color.

post/organizations/{organization}/passports/{id}/variants
Á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.

idcadenaObligatorio

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

Cuerpo de la solicitud

variantslista de objetosObligatorio

Envíe entre 1 y 1000 variantes de un pasaporte textil o general, hasta un total de 2000 por pasaporte entre todas las solicitudes. El lote completo se inserta o se rechaza y se devuelve en el orden de la solicitud. Los GTIN y los pares de talla y color deben ser únicos. Se permite el GTIN principal del propio pasaporte. Se rechaza el GTIN principal o de variante de otro pasaporte de la misma organización y modo, incluidos los pasaportes de la papelera. Las solicitudes completadas que se repiten con la misma Idempotency-Key devuelven el resultado antes de comprobar conflictos y capacidad. Los rechazos corregibles de la comprobación previa no reservan la clave. Las credenciales del conector permiten añadir variantes solo a borradores; no permiten eliminarlas.

gtincadenaObligatorio

Un GTIN válido de 8, 12, 13 o 14 dígitos, incluido el dígito de control. Se guarda y devuelve con 14 dígitos.

sizecadenaOpcional

Talla de 1 a 70 caracteres Unicode tras quitar los espacios iniciales y finales. Indique talla, color o ambos.

colourcadenaOpcional

Color de 1 a 70 caracteres Unicode tras quitar los espacios iniciales y finales. Los pares de talla y color son únicos sin distinguir mayúsculas de minúsculas.

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/variants" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "variants": [
    {
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy"
    }
  ]
}'
Respuesta · 201
{
  "object": "list",
  "data": [
    {
      "object": "variant",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

Eliminar una variante. Las credenciales del conector no permiten eliminar variantes.

Destructiva
delete/organizations/{organization}/passports/{id}/variants/{variantId}
Á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.

variantIdcadenaObligatorio

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/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Respuesta · 200
{
  "object": "variant",
  "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "deleted": true
}

DELETE /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84

Eliminar variantes por GTIN.

Destructiva
post/organizations/{organization}/passports/{id}/variants/remove
Á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

gtinsmatriz de cadenasObligatorio

Envíe entre 1 y 1000 GTIN válidos, normalizados a 14 dígitos. Se eliminan las entradas presentes y las ausentes se incluyen en absent. Al repetir una solicitud completada con la misma clave se devuelve el resultado original; sin clave, las entradas ya eliminadas aparecen en absent. Cada llamada que elimina variantes de un pasaporte publicado o desactivado consume una unidad del límite de operaciones destructivas. Las credenciales del conector no permiten eliminarlas. La eliminación se realiza en lotes limitados. Si falla un lote posterior, error.details.removed indica las eliminaciones completadas. Repita sin Idempotency-Key para conciliar las restantes; la misma clave devuelve el fallo registrado.

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/variants/remove" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "gtins": [
    "03453120000011"
  ]
}'
Respuesta · 200
{
  "removed": [
    "03453120000011"
  ],
  "absent": []
}

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

Lee las tallas y colores que una persona revisa antes de publicar, con su huella.

get/organizations/{organization}/passports/{id}/variants/review
Á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/variants/review" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Respuesta · 200
{
  "object": "variant_review",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "fingerprint": "3b2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f",
  "agent_written_count": 1,
  "variants": [
    {
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "agent_written": {
        "keyId": "pcmcp_a1",
        "keyName": "Claude",
        "at": "2026-09-18T09:12:44.000Z",
        "sourceClass": "agent_asserted"
      }
    },
    {
      "id": "8d3f1c22-6b7e-4d1a-9e2f-5a6b7c8d9e0f",
      "gtin": "05012345678900",
      "size": "L",
      "colour": "Navy",
      "agent_written": null
    }
  ]
}

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