Dijital Ürün Pasaportu API’si: Geliştiriciler için belgeler

Genel bakış

Müşteri API’si, JSON kullanan bir REST arayüzüdür. Kuruluşunuzun verileri üzerinde, yani web arayüzünde gördüğünüz ürünler ve pasaportlar üzerinde çalışır. Tipik kullanım alanları bir ERP veya PLM sistemine bağlantı, ana verilerin gece senkronizasyonu ya da baskı için QR kodlarını getiren bir betiktir.

Temel URL: https://dpp.com2u.selfhost.eu/api/v1/integration. QR kodu ve PDF indirmeleri dışında tüm yanıtlar JSON biçimindedir.

Spesifikasyonu indirin

Tüm uç noktaların, alanların, örneklerin ve hata yanıtlarının makine tarafından okunabilir referansı, ApiKeyAuth güvenlik şemasına sahip bir OpenAPI 3.1 spesifikasyonudur:

• openapi.json dosyasını indirin
• openapi.yaml dosyasını indirin

API, aynı dosyayı anahtar gerektirmeden GET /api/v1/integration/openapi.json adresinde de sunar. Dosyayı Swagger UI’a, Postman’e veya tercih ettiğiniz bir kod üreticisine aktarın. Dosyadaki açıklamalar Almancadır.

Hızlı başlangıç

1. Kaydolun veya giriş yapın. API ücretli planlara dahildir; bkz. Fiyatlar.
2. Platformda Kuruluş bölümünü açın ve API anahtarını oluşturun. Anahtarı hemen kopyalayın, çünkü yalnızca bir kez gösterilir.
3. Bağlantıyı test edin:

curl -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/me

Yanıt; kuruluşunuzu, anahtarın kapsamlarını (scopes), planınızı ve API çağrısı kullanımınızı gösterir.

Kimlik doğrulama

Anahtarı her çağrıda X-API-Key başlığında gönderin. Authorization: Bearer dpp_key_… de aynı şekilde çalışır. Kuruluş her zaman anahtardan belirlenir; parametre olarak gönderilen bir kuruluş kimliği dikkate alınmaz. API, web arayüzünün oturum belirteçlerini kabul etmez.

Anahtar, onu oluşturan kişiye aittir. İşlemler bu kişinin sahip (Owner) veya yönetici (Admin) yetkileriyle yürütülür. Kişi bu rolü kaybederse, yeni bir anahtar oluşturulana kadar API 403 ile yanıt verir. Yeni bir anahtar oluşturmak önceki anahtarı hemen iptal eder. Platform, anahtarın yalnızca SHA-256 karma değerini saklar.

Uç noktalar

Tüm yollar /api/v1/integration altındadır. Her uç nokta bir kapsam gerektirir; yeni bir anahtar dört kapsamın tamamına sahiptir.

Ürün oluşturma

name zorunludur. schema_key belirtilmezse kuruluşunuzun varsayılan şeması kullanılır; kullanılabilir anahtarları GET /schemas döndürür. Veri alanlarını doğrudan birlikte gönderebilirsiniz. field_status ile değerlerin durumunu belirlersiniz; bir pasaporta yalnızca approved durumundaki değerler aktarılır.

curl -X POST https://dpp.com2u.selfhost.eu/api/v1/integration/products \
  -H "X-API-Key: $DPP_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Pil modülü X1","category":"Endüstriyel piller",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

201 durum kodlu yanıt, ürünün id değerini içerir. Bu değer aynı zamanda QR kodunda yer alan benzersiz ürün tanımlayıcısıdır. Planınızın ürün kotası web arayüzünde olduğu gibi geçerlidir.

Pasaportu yayımlama, QR kodu ve PDF indirme

Bir pasaport, onaylanmış veri alanlarını yeni bir sürüm olarak sabitler. Zorunlu alanlar eksikse API 422 ile yanıt verir ve bu alanları missing_fields içinde listeler.

curl -X POST -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passports

curl -o qr.png -H "X-API-Key: $DPP_API_KEY" \
  "https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/qr?format=png&size=600"

curl -o passport.pdf -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/pdf

Vektör biçimindeki QR kodu için format=svg kullanın. PDF yalnızca yayımlamadan sonra kullanılabilir; öncesinde API 404 ile yanıt verir. QR kodu herkese açık pasaport sayfasına yönlendirir; ayrıntılar için bkz. Excel’den Dijital Ürün Pasaportu oluşturma.

Hata kodları

401 ve 403 durumlarında detail, code ve message içeren bir nesnedir; örneğin insufficient_scope veya api_not_in_plan. 402 durumunda detail kaynağı, sınırı ve mevcut kullanımı belirtir.

Sınırlar

API üzerinden ürün düzeyindeki veri alanlarını ayarlarsınız. Partiler veya tekil ürünler için alanları web arayüzünde yönetirsiniz. İstek sınırı yoktur, ancak plan başına bir çağrı kotası vardır; kimliği doğrulanmış her çağrı sayılır. Spesifikasyonun indirilmesi sayılmaz. Güncel planları ve kotaları Fiyatlar sayfasında bulabilirsiniz. API olmadan toplu içe aktarma için bir şablonu veri şablonu sayfası sunar.