API-dokumentation

GET /api/products

List the products of your account, most recent first. Paginated. Auth: API access.

Query parameters

Every response includes a next_cursor: an opaque string for the page after this one, or null at the end. Results are newest-first with a deterministic tie-break, in both modes.

Page mode

curl -s "https://dpp-tool.com/api/products?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "products": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "EcoCharge Pro 5000",
      "sector": "batteries",
      "gtin": "4006381333931",
      "model": "EC-5000",
      "product_slug": "ecocharge-pro-5000-x1y2",
      "passport_slug": "ecocharge-pro-5000-a1b2c3",
      "created_at": "2026-07-01 10:30:00",
      "updated_at": "2026-07-01 10:30:00",
      "passport_url": "https://dpp-tool.com/en/passport/ecocharge-pro-5000-a1b2c3/",
      "qr_code_url": "https://dpp-tool.com/api/qrcode?slug=ecocharge-pro-5000-a1b2c3"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "next_cursor": null
}

Two slugs, one of them routable. passport_slug is the one every other endpoint takes as ?slug= — /api/passport, /api/qrcode, /api/passport-versions, /api/export. product_slug is the product's own slug and is not routable; it is returned for reference only. passport_url and qr_code_url are given ready-made so you never have to build them. A product whose passport has been archived carries null in all three passport fields.

Page mode also returns an exact total and the page number. It suits a paged UI, but a deep page grows more expensive as the offset grows; for a full catalogue sweep, prefer cursor mode.

Cursor mode — iterate a large catalogue

Start with no cursor, then keep passing the previous next_cursor until it is null. Each page costs the same at any depth, so this scales to hundreds of thousands of products; cursor mode omits total so a full sweep does not run a count on every page. The cursor is opaque — echo it back, never parse or build it.

# First page (no cursor)
curl -s "https://dpp-tool.com/api/products?per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Each subsequent page: pass the previous next_cursor
curl -s "https://dpp-tool.com/api/products?per_page=100&cursor=NEXT_CURSOR_FROM_PREVIOUS_RESPONSE" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "products": [ "... up to per_page rows ..." ],
  "per_page": 100,
  "next_cursor": "MjAyNi0wNy0wMSAwOTowMDowMB8xZDBi"
}

GET /api/products/{id}

Fetch a single product with its full record — every field you can write, not the summary the list returns. Auth: API access. The {id} is the product_id; it may also be passed as ?id=.

curl -s "https://dpp-tool.com/api/products/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "product": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "EcoCharge Pro 5000",
    "sector": "batteries",
    "manufacturer_name": "ACME Industries",
    "carbon_footprint": "12.5",
    "external_ref": "ERP-4471",
    "product_slug": "ecocharge-pro-5000-x1y2",
    "passport_slug": "ecocharge-pro-5000-a1b2c3",
    "passport_url": "https://dpp-tool.com/en/passport/ecocharge-pro-5000-a1b2c3/",
    "qr_code_url": "https://dpp-tool.com/api/qrcode?slug=ecocharge-pro-5000-a1b2c3",
    "certifications": "ce_marking,iso_14001,NF EN 442-1",
    "certifications_list": [
      { "code": "ce_marking", "label": "CE marking", "group": "conformity", "standardised": true },
      { "code": "iso_14001", "label": "ISO 14001 (environmental management)", "group": "environment", "standardised": true },
      { "code": null, "label": "NF EN 442-1", "group": null, "standardised": false }
    ]
  }
}

A product that is not in your account returns 404, never 403 — the API never confirms the existence of another account's row.

POST /api/products

Create a product. On success a Digital Product Passport is generated automatically and the passport slug, public URL and QR-code URL are returned. Auth: API access + writer.

Body fields

A valid gtin (8/12/13/14 digits, mod-10 check digit) unlocks the product's GS1 Digital Link and its QR code. See GS1 Digital Link below. Creating past your plan's product quota returns 403 {"error":"Product limit reached for your plan"}.

Example

curl -s -X POST "https://dpp-tool.com/api/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EcoCharge Pro 5000",
    "sector": "batteries",
    "manufacturer_name": "GreenTech GmbH",
    "gtin": "4006381333931",
    "batch_number": "LOT42",
    "carbon_footprint": 12.5,
    "recycled_content": 65,
    "energy_class": "A+"
  }'

Response 201

{
  "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "passport_slug": "ecocharge-pro-5000-a1b2c3",
  "passport_url": "https://dpp-tool.com/en/passport/ecocharge-pro-5000-a1b2c3/",
  "qr_code_url": "https://dpp-tool.com/api/qrcode?slug=ecocharge-pro-5000-a1b2c3"
}

Emits the product.created webhook on plans that have webhooks enabled.

PUT /api/products/{id}

Update a product. This is a partial update: only the fields present in the body are changed; everything else is left untouched. The product's passport is regenerated in place — its slug and public URL do not change, its version number is incremented, its previous payload is archived to the version history, and its QR cache is purged. Auth: API access + writer. The {id} is the product_id; it may also be passed as ?id=.

Accepts every POST field, plus the extended passport fields manufacturer_id, carbon_scope, recycled_materials, energy_consumption, energy_unit, spare_parts_available, repair_instructions_url, contains_svhc, hazardous_substances, due_diligence. The three boolean fields (spare_parts_available, contains_svhc, due_diligence) accept true/false, 1/0 or "1"/"0". Validation runs on the merged row, so the result must still have a valid name, sector and manufacturer_name.

Example

curl -s -X PUT "https://dpp-tool.com/api/products/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recycled_content": 72, "energy_class": "A++" }'

Response 200

{
  "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "passport_slug": "ecocharge-pro-5000-a1b2c3",
  "passport_url": "https://dpp-tool.com/en/passport/ecocharge-pro-5000-a1b2c3/",
  "qr_code_url": "https://dpp-tool.com/api/qrcode?slug=ecocharge-pro-5000-a1b2c3",
  "version": 2
}

Missing id → 400. Id not in your account → 404. Emits the product.updated webhook.

DELETE /api/products/{id}

Delete a product. The product row is removed, its passports are archived, not destroyed (a printed QR that points at a passport URL would otherwise break; archived passports return 404 on their public URL while the record is retained), and any uploaded documents attached to the product are purged along with their files. Auth: API access + writer. The {id} may also be passed as ?id=.

Example

curl -s -X DELETE "https://dpp-tool.com/api/products/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "deleted": true,
  "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "passports_archived": 1,
  "documents_deleted": 2
}

Missing id → 400. Id not in your account → 404.

GET /api/passport

Fetch a published passport by slug. Public, no key required.

Query parameters

Example

curl -s "https://dpp-tool.com/api/passport?slug=ecocharge-pro-5000-a1b2c3&format=jsonld"

Missing slug/id → 400. Unknown slug → 404. Unknown format → 400 {"error":"Invalid format. Use: json, jsonld, html"}.

GET /api/export

Three modes on one endpoint, selected by the parameters present:

• CSV import template — ?template=csv, public. Returns the blank column template used by the dashboard bulk importer; ignores every other parameter.
• Single passport — ?slug=…, public. Exports one published passport as a file.
• Bulk account export — no slug, authenticated (API access). Streams every product of your account for ERP round-trips.

Query parameters

Bulk columns: id, name, sku, gtin, batch, sector, manufacturer, country_of_origin, materials, certifications, recycled_content, carbon_footprint, created_at, updated_at, passport_slug, passport_url, qr_url (sku is sourced from the product's model).

Examples

# Single passport (public)
curl -s "https://dpp-tool.com/api/export?slug=ecocharge-pro-5000-a1b2c3&format=csv" -o passport.csv

# Blank import template (public)
curl -s "https://dpp-tool.com/api/export?template=csv" -o dpp-tool-template.csv

# Whole account, delta since a date (authenticated)
curl -s "https://dpp-tool.com/api/export?format=json&since=2026-07-01" \
  -H "Authorization: Bearer YOUR_API_KEY" -o account-export.json

Single-passport mode: missing/unknown slug → 404, unknown format → 400. Bulk mode: unknown format → 400 {"error":"Invalid format. Use: csv, json, xlsx"}; without a key → 401; on a non-API plan → 403. XLSX depends on the server's ZipArchive; where it is unavailable, bulk format=xlsx returns 501 — use format=csv.

GET /api/qrcode

Return the passport's QR code as a PNG image (image/png). Public. The QR encodes the product's GS1 Digital Link URI when it has a valid GTIN, otherwise the passport page URL.

Query parameters

Example

curl -s "https://dpp-tool.com/api/qrcode?slug=ecocharge-pro-5000-a1b2c3&size=600" -o qr.png

Missing slug → 400. Unknown slug → 404.

GET POST DELETE /api/documents

Attach files — certificates, test reports, declarations of conformity, safety data sheets — to a product. Auth: API access; writer for POST/DELETE. Files are stored server-side and reached through the url field (see /api/document-file). A per-product document quota comes from the plan.

GET — list a product's documents

curl -s "https://dpp-tool.com/api/documents?product_id=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "documents": [
    {
      "id": "d0c0ffee-0000-4a00-8b00-000000000001",
      "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "certificate",
      "title": "CE Declaration",
      "issuer": "TUV",
      "reference": "CE-2026-001",
      "issued_at": "2026-01-15",
      "expires_at": "2029-01-15",
      "original_name": "ce-declaration.pdf",
      "mime": "application/pdf",
      "size_bytes": 148213,
      "sha256": "9f2c...e1",
      "is_public": true,
      "created_at": "2026-07-01 10:32:00",
      "url": "https://dpp-tool.com/api/document-file?id=d0c0ffee-0000-4a00-8b00-000000000001"
    }
  ],
  "quota_left": 19
}

POST — upload (multipart/form-data)

curl -s -X POST "https://dpp-tool.com/api/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "product_id=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -F "type=certificate" \
  -F "title=CE Declaration" \
  -F "is_public=true" \
  -F "[email protected]"

Returns 201 { "document": { … } } with the same row shape as GET. Over quota → 400 {"error":"Document limit reached for your plan (… per product)"}. Wrong type → 400 {"error":"Unsupported file type. Allowed: PDF, JPG, PNG, WebP"}.

DELETE — remove a document

curl -s -X DELETE "https://dpp-tool.com/api/documents?id=d0c0ffee-0000-4a00-8b00-000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns { "deleted": true, "id": "…" }. Unknown id → 404.

GET /api/document-file

Stream a stored document file (this is the url returned by /api/documents). A public document (is_public = true) is served to anyone; a private one only to a member of the owning account (session or API key). Anything else — wrong account, missing id, missing file — is a 404, so a private id's existence never leaks.

curl -s "https://dpp-tool.com/api/document-file?id=d0c0ffee-0000-4a00-8b00-000000000001" -o ce-declaration.pdf

The response carries the file's own content type and a Content-Disposition (inline for PDF/images, otherwise attachment).

GET POST PUT DELETE /api/suppliers

Supply-chain actors scoped to your account, and their links to products. Auth: API access; supplier management additionally requires the Pro plan or higher (a suppliers entitlement, enforced for both key and dashboard callers); writer role for POST/PUT/DELETE.

GET

• No parameter → { "suppliers": […], "total": N } (whole account).
• ?id=<supplier_id> → { "supplier": { … } }, or 404.
• ?product_id=<product_id> → { "suppliers": […], "carbon_footprint_supply_chain": { … } } — the actors linked to that product, each with its stage and its link_carbon_footprint_per_unit, plus the aggregate described below.

POST — create a supplier

curl -s -X POST "https://dpp-tool.com/api/suppliers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "GreenTech GmbH", "role": "manufacturer", "country": "DE", "gln": "4006381333931" }'

Returns 201 { "supplier": { … }, "id": "…" }. A duplicate (name, role) → 400.

PUT — update

PUT /api/suppliers?id=<supplier_id>, partial update, validated on the merged row. Returns { "supplier": { … }, "id": "…" }. Unknown id → 404.

DELETE

DELETE /api/suppliers?id=<supplier_id> removes the supplier and its product links. Returns { "deleted": true, "id": "…" }. Unknown id → 404.

Carbon footprint per unit

A supplier carries a default per-unit figure (carbon_footprint_per_unit, kg CO₂e per unit of finished product). A product link can carry its own figure, which overrides that default for that product only — the same mill does not emit the same amount for a hoodie and for a denim jacket.

The product total is the sum of the figures declared along its chain, served by GET /api/products/{id} and by GET /api/suppliers?product_id=:

"carbon_footprint_supply_chain": {
  "value": 6.75,                       // null when nobody reported
  "unit": "kg CO2e",
  "basis": "per unit",
  "suppliers_total": 3,
  "suppliers_reporting": 2,            // actors that actually declared a figure
  "complete": false,                   // true only when every linked actor reported
  "aggregation": "sum of declared supplier values",
  "breakdown": [
    { "supplier_id": "...", "supplier_name": "...", "role": "dyeing", "stage": "dyeing",
      "value": 2.5, "unit": "kg CO2e", "source": "supplier_default",
      "method": "estimate", "reference_date": "2026-01-31" }
  ]
}

An actor that reported nothing is counted in suppliers_total but never guessed at, so a partial total cannot be read as a complete one. In the passport, the value declared on the product wins; when the product carries none, the supply-chain sum fills it and is labelled "source": "supply_chain_aggregate" under sustainability.carbon_footprint, together with the coverage. This is an arithmetic sum of declared values — not a life-cycle assessment, and not a verified product carbon footprint.

# Set (or clear, with null) the figure carried by ONE product-supplier link
curl -s -X POST "https://dpp-tool.com/api/suppliers?id=SUPPLIER_ID&action=carbon" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "stage": "dyeing", "carbon_footprint_per_unit": 2.5 }'

Returns { "updated": true, "carbon_footprint_per_unit": 2.5, "unit": "kg CO2e", … }. A pair that is not linked at that stage → 404.

Attach / detach a supplier to a product

Both share the POST verb, disambiguated by ?action= and the supplier ?id=; the product id and optional stage go in the JSON body. attach also accepts carbon_footprint_per_unit to set the link's figure in the same call; repeating an attach with a new figure updates it instead of failing.

# Attach
curl -s -X POST "https://dpp-tool.com/api/suppliers?id=SUPPLIER_ID&action=attach" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "stage": "cell-assembly" }'

# Detach
curl -s -X POST "https://dpp-tool.com/api/suppliers?id=SUPPLIER_ID&action=detach" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "stage": "cell-assembly" }'

{
  "attached": true,
  "link_id": "11112222-3333-4444-5555-666677778888",
  "duplicate": false,
  "product_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "supplier_id": "SUPPLIER_ID",
  "stage": "cell-assembly"
}

Attach is idempotent on (product, supplier, stage): a repeat returns 200 with "duplicate": true; a fresh link returns 201. A foreign or missing product/supplier → 404. Detach returns { "detached": true|false }.

GET /api/passport-versions

Read-only version history of a passport — the immutable audit trail kept for ESPR (Regulation (EU) 2024/1781). Auth: an authenticated caller (API key or dashboard session) that owns the passport; anything else is a 404. GET only (other methods → 405).

# Metadata listing
curl -s "https://dpp-tool.com/api/passport-versions?slug=ecocharge-pro-5000-a1b2c3" \
  -H "Authorization: Bearer YOUR_API_KEY"

# One snapshot
curl -s "https://dpp-tool.com/api/passport-versions?slug=ecocharge-pro-5000-a1b2c3&version=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "slug": "ecocharge-pro-5000-a1b2c3",
  "current_version": 2,
  "versions": [
    { "version": 2, "created_at": "2026-07-05 09:00:00", "changed_by": "user-uuid" },
    { "version": 1, "created_at": "2026-07-01 10:30:00", "changed_by": null }
  ]
}

Unknown slug, or one you do not own → 404. Unknown version → 404.

POST /api/import-run

Worker that advances a CSV/XLSX bulk-import job by one bounded batch (at most 25 rows, ~15 s) and returns the job's progress. The browser calls it repeatedly until done is true. Authenticates via the dashboard session only — there is no API-key path, so this endpoint is not part of the key-based integration surface; it backs the dashboard's Import screen (upload the file there to create the job). Writer role required.

{
  "job": "job-uuid",
  "status": "running",
  "processed": 25,
  "total": 120,
  "imported": 24,
  "failed": 1,
  "skipped": 0,
  "done": false
}

When the plan's product quota is hit mid-file, the remaining rows are reported as skipped (never silently dropped) and done becomes true. On completion, an import.completed webhook fires once. Not logged in → 401; missing job → 400.

GET /api/webhook-run

Drains due webhook retries for your account within a bounded batch. Authenticated (session or API key) callers drain only their own account's queue. Retries are also drained opportunistically when events are dispatched, so calling this is optional; it exists because the host has no guaranteed cron.

curl -s "https://dpp-tool.com/api/webhook-run" -H "Authorization: Bearer YOUR_API_KEY"

{ "ok": true, "scope": "account", "claimed": 2, "delivered": 2,
  "retried": 0, "failed": 0, "dead": 0, "skipped": 0, "elapsed_ms": 830 }