Démarrer avec l'API PassportCraft

Démarrage

Cinq requêtes, d'un compte vide jusqu'à un passeport publié portant son lien public.

1.Créer une clé API
Les clés se créent dans les paramètres. Une clé ne s'affiche qu'une seule fois, au moment de sa création ; ensuite, seul son identifiant reste visible.
N'accordez que les portées dont l'intégration a réellement besoin. Une clé qui peut lire les passeports sans les publier ne mettra jamais un catalogue en ligne par accident.
Ouvrir les clés API dans les paramètres
shell
```
export PASSPORTCRAFT_API_KEY=pc_sk_test_…
```

2.Vérifier la clé

Le premier appel à faire. Il confirme que la clé fonctionne, indique s'il s'agit d'un accès en direct ou de test, et énumère les organisations pour lesquelles elle peut agir — avec l'identifiant d'organisation dont toute requête ultérieure a besoin.

Requête

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

Réponse

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

Référence complète de ce point de terminaison

3.Créer un passeport

Un passeport naît à l'état de brouillon. Seule la catégorie est obligatoire ; le document se remplit ensuite champ par champ, exactement comme dans l'éditeur.

Requête

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

Réponse

{
  "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": [
      {
        "name": "None declared",
        "present": false
      }
    ]
  }
}

Référence complète de ce point de terminaison

4.Vérifier avant de publier

La validation n'écrit rien. Elle indique ce qui bloquerait une publication et ce qui n'est qu'un avertissement : l'intégration l'apprend donc avant l'appel qui compte.

Requête

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

Réponse

{
  "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.",
      "writable_via_api": true
    }
  ]
}

Référence complète de ce point de terminaison

5.Publier

La publication rend le passeport lisible par quiconque le scanne. L'appel est refusé si un champ obligatoire manque, si le GTIN est absent, ou si le forfait n'a plus de place de publication.

Requête

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

Réponse

{
  "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": "03453120000011",
  "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": [
      {
        "name": "None declared",
        "present": false
      }
    ],
    "gtin": "03453120000011"
  },
  "warnings": [
    {
      "code": "environmental_claim_detected",
      "message": "This passport contains environmental claim language (carbon neutral). 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"
    }
  ]
}

Référence complète de ce point de terminaison

6.Récupérer le lien public

Renvoie la page publique, le GS1 Digital Link et la cible exacte qu'encode un QR code imprimé — la valeur à transmettre à l'imprimeur d'étiquettes.

Requête

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"

Réponse

{
  "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": "03453120000011",
  "serial_number": null,
  "public_url": "https://passportcraft.com/passport/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "qr_target": "https://passportcraft.com/01/03453120000011",
  "gs1_digital_link": {
    "uri": "https://passportcraft.com/01/03453120000011",
    "gtin14": "03453120000011",
    "serial": null,
    "linkset_url": "https://passportcraft.com/01/03453120000011?linkType=linkset",
    "unavailable_reason": null
  },
  "resolves_publicly": true,
  "not_resolvable_reason": null
}

Référence complète de ce point de terminaison

Pour aller plus loin

Conventions — les reprises, la pagination et les écritures conditionnelles.
Erreurs — le code sur lequel s'aiguiller lorsqu'un appel est refusé.
Compatibilité — ce qui peut changer sans préavis, et ce qui ne le peut pas.

1.Créer une clé API

2.Vérifier la clé

3.Créer un passeport

4.Vérifier avant de publier

5.Publier

6.Récupérer le lien public

Pour aller plus loin