DPP Agent docs

Quickstart — from API key to a scannable passport

Five requests: create a passport as a draft, publish it, get its QR code, read it the way a scanner does, and check it. The examples use curl and GS1's example GTIN 09506000134352; use your own.

1. Get an API key

A tenant admin creates one in the dashboard under Settings → API. Copy it when it is shown; it is not shown again.

export DPP_KEY=dpp_live_…

Before you publish, the tenant needs its economic operator identifier (an LEI, a GS1 company prefix or a PEPPOL identifier) under the brand settings. Drafts can be created without it.

2. Create a draft

curl -s https://dppagent.com/api/v1/dpps \
  -H "Authorization: Bearer $DPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "09506000134352",
    "category": "textile",
    "granularity": "model",
    "dpp_status": "draft",
    "dpp_data": {
      "espr.pid.product_name": "Example Wool Sweater",
      "espr.mfr.name": "Example Knitwear AB",
      "espr.mfr.country": "SE"
    }
  }'

The answer is 201 with the stored passport in dpp, and its public address in public_url. Keep dpp.id:

{
  "dpp": { "id": "3f2a9b1c-e0d8-4f8e-b308-d2541886e331", "dpp_status": "draft", "…": "…" },
  "public_url": "https://example.dpp.dppagent.com/01/09506000134352",
  "tier": "light",
  "blippa": null
}

Leave out "dpp_status": "draft" and the passport is published straight away.

3. Publish it

curl -s -X PATCH https://dppagent.com/api/v1/dpps/3f2a9b1c-e0d8-4f8e-b308-d2541886e331 \
  -H "Authorization: Bearer $DPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dpp_status": "active" }'

From now on the public address answers. To change the product data later, PATCH dpp_data with the whole map: it replaces what is stored.

4. Get the QR code

curl -s -o sweater-qr.png \
  "https://dppagent.com/api/v1/qr?dppid=3f2a9b1c-e0d8-4f8e-b308-d2541886e331&format=png&size=600&src=tag"

No key is needed. The code encodes the passport's public address, in the tenant's saved QR design. src=tag records scans as coming from a hang tag; use src=label for a sewn-in label. See QR & Labels.

5. Read it like a scanner

A phone gets the passport page. A program asks for JSON at the same address, with no key:

curl -s -H "Accept: application/json" https://example.dpp.dppagent.com/01/09506000134352
curl -s "https://example.dpp.dppagent.com/01/09506000134352?linkType=all"

The first returns the passport (productIdentification, dppMetadata, productData); the second its links as a GS1 linkset. See Resolver.

6. Check it

curl -s "https://dppagent.com/api/v1/validate?url=https%3A%2F%2Fexample.dpp.dppagent.com%2F01%2F09506000134352" \
  -H "Authorization: Bearer $DPP_KEY"

The report scores how the passport is served and how many ESPR fields it covers, and with the key it lists every missing field. See Validate.

Next