PassportCraft API'siyle başlangıç

Başlangıç

Boş bir hesaptan herkese açık bağlantısı olan yayımlanmış bir pasaporta kadar beş istek.

1.API anahtarı oluşturma
Anahtarlar ayarlar bölümünde üretilir. Bir anahtar yalnızca oluşturulduğu anda bir kez gösterilir; sonrasında yalnızca tanımlayıcısı görünür kalır.
Yalnızca entegrasyonun gerçekten ihtiyaç duyduğu kapsamları verin. Pasaportları okuyabilen ama yayımlayamayan bir anahtar, bir kataloğu yanlışlıkla canlıya alamaz.
Ayarlarda API anahtarlarını açın
shell
```
export PASSPORTCRAFT_API_KEY=pc_sk_test_…
```

2.Anahtarı denetleme

Yapılmaya değer ilk çağrı. Anahtarın çalıştığını doğrular, canlı mı yoksa test kimlik bilgisi mi olduğunu bildirir ve adına işlem yapabileceği kuruluşları, sonraki her isteğin gerektirdiği kuruluş kimliğiyle birlikte listeler.

İstek

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

Yanıt

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

Bu uç noktanın tam referansı

3.Pasaport oluşturma

Bir pasaport taslak olarak doğar. Yalnızca kategori zorunludur; belge daha sonra alan alan doldurulabilir, tıpkı düzenleyicideki gibi.

İstek

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

Yanıt

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

Bu uç noktanın tam referansı

4.Yayımlamadan önce denetleme

Denetleme hiçbir şey yazmaz. Yayımlamayı neyin engelleyeceğini ve neyin yalnızca uyarı olduğunu bildirir; böylece entegrasyon asıl önemli çağrıdan önce durumu öğrenir.

İstek

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

Yanıt

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

Bu uç noktanın tam referansı

5.Yayımlama

Yayımlandığında pasaport, kodu okutan herkes tarafından görüntülenebilir hâle gelir. Zorunlu bir alan eksikse, GTIN yoksa ya da planda boş yayımlama hakkı kalmadıysa çağrı reddedilir.

İstek

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

Yanıt

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

Bu uç noktanın tam referansı

6.Herkese açık bağlantıyı alma

Herkese açık sayfayı, GS1 Digital Link adresini ve basılı bir QR kodun kodladığı tam hedefi döndürür: etiket matbaasına verilecek değer. Yanıt ayrıca preview_url alanını içerir: kuruluşunuzun oturum açmış bir üyesinin açabileceği bir adres. Pasaport herkese açık olarak çözümlenmediği sürece bu alan doludur — bir test pasaportu hiçbir zaman çözümlenmez — ve pasaport çözümlenir çözümlenmez boşalır. Test anahtarıyla bu adres, ürün sayfasını bir alıcının göreceği biçimde, sayfayı test pasaportu olarak işaretleyen bir şeridin altında açar.

İstek

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"

Yanıt

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

Bu uç noktanın tam referansı

Bundan sonrası

Kurallar — yeniden denemeler, sayfalama ve koşullu yazma işlemleri.
Hatalar — bir çağrı reddedildiğinde dallanılacak kod.
Uyumluluk — haber verilmeden neyin değişebileceği, neyin değişemeyeceği.

1.API anahtarı oluşturma

2.Anahtarı denetleme

3.Pasaport oluşturma

4.Yayımlamadan önce denetleme

5.Yayımlama

6.Herkese açık bağlantıyı alma

Bundan sonrası