Primi passi con l'API di PassportCraft

Primi passi

Cinque richieste, da un account vuoto fino a un passaporto pubblicato con il suo link pubblico.

1.Creare una chiave API
Le chiavi si creano nelle impostazioni. Una chiave viene mostrata una sola volta, nel momento in cui viene creata; poi resta visibile soltanto il suo identificativo.
Conceda solo gli ambiti di cui l’integrazione ha davvero bisogno. Una chiave che può leggere i passaporti ma non pubblicarli non manderà mai un catalogo online per errore.
Aprire le chiavi API nelle impostazioni
shell
```
export PASSPORTCRAFT_API_KEY=pc_sk_test_…
```

2.Verificare la chiave

La prima chiamata da fare. Conferma che la chiave funziona, dice se si tratta di una credenziale reale o di prova ed elenca le organizzazioni per cui può agire, con l'identificativo di organizzazione che ogni richiesta successiva richiede.

Richiesta

curl "https://passportcraft.com/api/v1/whoami" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Risposta

{
  "object": "credential",
  "key_id": "K3n9Qw2P",
  "livemode": true,
  "owner_organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "expires_at": null,
  "last_used_at": "2026-08-02T07:41:03.220Z",
  "organizations": [
    {
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "scopes": [
        "passports:read",
        "passports:write",
        "units:read",
        "units:write"
      ],
      "granted_at": "2026-07-14T11:02:19.004Z"
    }
  ]
}

Riferimento completo di questo endpoint

3.Creare un passaporto

Un passaporto nasce come bozza. Solo la categoria è obbligatoria; il documento si compila poi campo per campo, esattamente come nell'editor.

Richiesta

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"
  }
}'

Risposta

{
  "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"
    ]
  }
}

Riferimento completo di questo endpoint

4.Verificarlo prima di pubblicare

La verifica non scrive nulla. Segnala che cosa bloccherebbe una pubblicazione e che cosa è solo un avviso, così l'integrazione lo scopre prima della chiamata che conta.

Richiesta

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
  }
}'

Risposta

{
  "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
    }
  ]
}

Riferimento completo di questo endpoint

5.Pubblicarlo

Con la pubblicazione il passaporto diventa leggibile da chiunque lo scansioni. La chiamata viene rifiutata se manca un campo obbligatorio, se manca il GTIN o se il piano non ha più posti di pubblicazione.

Richiesta

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)"

Risposta

{
  "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"
    }
  ]
}

Riferimento completo di questo endpoint

6.Ottenere il link pubblico

Restituisce la pagina pubblica, il GS1 Digital Link e la destinazione esatta che un codice QR stampato codifica: il valore da consegnare alla tipografia delle etichette. La risposta include anche preview_url, un indirizzo che un membro della propria organizzazione può aprire con l'accesso a PassportCraft effettuato. È valorizzato finché il passaporto non si risolve pubblicamente — cosa che un passaporto di prova non fa mai — ed è vuoto non appena si risolve. Con una chiave di prova apre la pagina prodotto come la vede chi acquista, sotto una barra che la contrassegna come passaporto di prova.

Richiesta

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"

Risposta

{
  "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
}

Riferimento completo di questo endpoint

Come proseguire

Convenzioni — ritentativi, impaginazione e scritture condizionali.
Errori — il codice su cui ramificare quando una chiamata viene rifiutata.
Compatibilità — che cosa può cambiare senza preavviso e che cosa no.

1.Creare una chiave API

2.Verificare la chiave

3.Creare un passaporto

4.Verificarlo prima di pubblicare

5.Pubblicarlo

6.Ottenere il link pubblico

Come proseguire