デジタル製品パスポート API：開発者向けドキュメント

概要

顧客向け API は、JSON を使用する REST インターフェースです。組織のデータ、つまり Web アプリケーションで表示されるのと同じ製品とパスポートを対象に動作します。代表的な用途は、ERP や PLM システムとの連携、マスターデータの夜間同期、印刷用の QR コードを取得するスクリプトなどです。

ベース URL は https://dpp.com2u.selfhost.eu/api/v1/integration です。QR コードと PDF のダウンロードを除き、すべてのレスポンスは JSON です。

仕様のダウンロード

すべてのエンドポイント、項目、例、エラーレスポンスを網羅した機械可読のリファレンスは、セキュリティスキーム ApiKeyAuth を備えた OpenAPI 3.1 仕様です。

• openapi.json をダウンロード
• openapi.yaml をダウンロード

同じファイルは API 自体からも GET /api/v1/integration/openapi.json でキーなしで取得できます。Swagger UI、Postman、またはお好みのコードジェネレーターにインポートしてください。ファイル内の説明はドイツ語で記載されています。

クイックスタート

1. 登録するか、ログインします。API は有料プランに含まれます。料金をご覧ください。
2. プラットフォームの「組織」エリアを開き、API キーを発行します。キーは一度しか表示されないため、すぐにコピーしてください。
3. 接続をテストします。

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

レスポンスには、組織、キーのスコープ、プラン、API 呼び出しの使用量が含まれます。

認証

すべての呼び出しで、キーを X-API-Key ヘッダーに含めて送信します。Authorization: Bearer dpp_key_… も同様に使用できます。組織は常にキーから判別され、パラメーターとして渡された組織 ID は評価されません。Web アプリケーションのセッショントークンは API では受け付けません。

キーは、それを発行した人に属します。操作はその人のオーナーまたは管理者としての権限で実行されます。その人がこのロールを失うと、新しいキーが発行されるまで API は 403 を返します。キーを再発行すると、以前のキーは直ちに無効になります。プラットフォームはキーの SHA-256 ハッシュのみを保存します。

エンドポイント

すべてのパスは /api/v1/integration の下にあります。各エンドポイントにはスコープが必要で、新しいキーには 4 つすべてが付与されます。

製品の作成

name は必須です。schema_key を指定しない場合は、組織の標準スキーマが適用されます。使用可能なキーは GET /schemas で取得できます。データ項目は直接渡すことができます。field_status で値のステータスを指定し、approved の値だけがパスポートに反映されます。

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":"Battery module X1","category":"Industrial batteries",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

ステータス 201 のレスポンスには、製品の id が含まれます。これは QR コードに埋め込まれる一意の製品識別子でもあります。プランの製品上限は Web アプリケーションと同様に適用されます。

パスポートの公開、QR コードと PDF のダウンロード

パスポートは、承認済みのデータ項目を新しいバージョンとして固定します。必須項目が不足している場合、API は 422 を返し、missing_fields に不足項目を示します。

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

ベクター形式の QR コードには format=svg を使用します。PDF は公開後にのみ取得でき、公開前は API が 404 を返します。QR コードは公開パスポートページを指します。詳しくはExcel からデジタル製品パスポートを作成するをご覧ください。

エラーコード

401 と 403 の場合、detail には code と message を持つオブジェクトが含まれます（例：insufficient_scope、api_not_in_plan）。402 の場合、detail にはリソース、上限、これまでの使用量が示されます。

制限事項

API で設定できるのは製品レベルのデータ項目です。ロットや個別品目の項目は Web アプリケーションで管理します。レート制限はありませんが、プランごとに呼び出し上限があり、認証されたすべての呼び出しが数えられます。仕様の取得は数えられません。最新のプランと上限は料金ページでご確認いただけます。API を使わない一括インポートには、データテンプレートをご利用ください。