Vai al contenuto

Risorse

Varianti

Tutti gli endpoint Varianti, con l'ambito che impongono, il corpo che accettano, una risposta leggibile e i rifiuti che possono restituire.

Elencare le varianti di taglia e colore.

get/organizations/{organization}/passports/{id}/variants
Ambito
passports:read
Idempotency-Key
Non accettata
Restituisce
200

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Parametri di query

limitstringaFacoltativo

Quanti record restituire. Il server può restituirne meno.

cursorstringaFacoltativo

Il next_cursor della pagina precedente. Un cursore codifica i filtri con cui è stato emesso; inviarlo con filtri diversi viene rifiutato con cursor_invalid.

gtinstringaFacoltativo

Restituire solo la variante con questo GTIN. I GTIN validi di 8, 12, 13 o 14 cifre vengono normalizzati a 14 cifre.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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"
Risposta · 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

Creare varianti di taglia e colore.

post/organizations/{organization}/passports/{id}/variants
Ambito
passports:write
Idempotency-Key
Accettata
Restituisce
201

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Corpo della richiesta

variantselenco di oggettiObbligatorio

Invii da 1 a 1000 varianti per un passaporto tessile o generale, fino a 2000 per passaporto considerando tutte le richieste. Il lotto viene inserito o rifiutato per intero e restituito nell’ordine della richiesta. I GTIN devono essere univoci. Le coppie taglia/colore devono essere univoche. È consentito il GTIN principale dello stesso passaporto. Un GTIN principale o di variante di un altro passaporto della stessa organizzazione e modalità viene rifiutato, anche se il passaporto è nel cestino. Le richieste completate ripetute con la stessa Idempotency-Key restituiscono il risultato prima di nuovi controlli sui conflitti e sulla capacità. I rifiuti correggibili nella verifica preliminare non riservano la chiave. Le credenziali del connettore consentono di aggiungere varianti solo alle bozze, ma non di rimuoverle.

gtinstringaObbligatorio

Un GTIN valido di 8, 12, 13 o 14 cifre, inclusa la cifra di controllo. Memorizzato e restituito con 14 cifre.

sizestringaFacoltativo

Taglia da 1 a 70 caratteri Unicode dopo la rimozione degli spazi iniziali e finali. Indichi taglia, colore o entrambi.

colourstringaFacoltativo

Colore da 1 a 70 caratteri Unicode dopo la rimozione degli spazi iniziali e finali. Le coppie taglia/colore sono univoche senza distinzione tra maiuscole e minuscole.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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"
    }
  ]
}'
Risposta · 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

Eliminare una variante. Le credenziali del connettore non consentono di eliminare varianti.

Distruttiva
delete/organizations/{organization}/passports/{id}/variants/{variantId}
Ambito
passports:write
Idempotency-Key
Accettata
Restituisce
200

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

variantIdstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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)"
Risposta · 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

Rimuovere varianti tramite GTIN.

Distruttiva
post/organizations/{organization}/passports/{id}/variants/remove
Ambito
passports:write
Idempotency-Key
Accettata
Restituisce
200

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Corpo della richiesta

gtinsarray di stringheObbligatorio

Invii da 1 a 1000 GTIN validi, normalizzati a 14 cifre. Le voci presenti vengono rimosse; quelle mancanti compaiono in absent. Ripetere una richiesta riuscita con la stessa chiave restituisce il risultato originale; senza chiave, le voci già rimosse compaiono in absent. Ogni chiamata che rimuove varianti da un passaporto pubblicato o disattivato conta una volta nel limite delle operazioni distruttive. Le credenziali del connettore non consentono questa operazione. La rimozione avviene in lotti limitati. Se un lotto successivo fallisce, error.details.removed indica le rimozioni completate. Ripeta senza Idempotency-Key per riconciliare le voci restanti; la stessa chiave restituisce l’errore registrato.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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"
  ]
}'
Risposta · 200
{
  "removed": [
    "03453120000011"
  ],
  "absent": []
}

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

Legge le taglie e i colori che una persona verifica prima della pubblicazione, con la loro impronta.

get/organizations/{organization}/passports/{id}/variants/review
Ambito
passports:read
Idempotency-Key
Non accettata
Restituisce
200

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta
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"
Risposta · 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