API Reference

Creates a new manufacturer account. Sends a verification email via SendGrid.

Request body

Response 201

"message": "Registration successful. Please verify your email.",
"api_key": "b79e57f0e3d1..."

Response 200

"token": "eyJhbGciOiJIUzI1NiJ9...",
"api_key": "b79e57f0e3d1...",
"tenant": { "id": "uuid", "name": "Acme s.r.o.", "gcp": "0852345" }

Returns all products for the authenticated tenant, ordered by creation date descending.

Response 200

"products": [
  {
    "id": "uuid",
    "gtin": "08523456790018",
    "batch_lot": "LOT2026A",
    "product_name": { "en": "Smart Battery" },
    "sector": "battery",
    "status": "active",
    "created_at": "2026-03-15T10:00:00Z"
  }
]

Returns full product data including materials, substances, battery data, and link targets.

URL parameters

Response 200

Returns the full product object with nested materials, substances, battery, and link_targets arrays.

Creates a new Digital Product Passport. Automatically creates link targets and makes the DPP publicly accessible at https://dpp.gs/passport/{gtin}.

Minimal request

{
  "gtin": "08523456790018",
  "sector": "battery",
  "manufacturer_name": "Acme s.r.o.",
  "manufacturer_country": "SK"
}

Full request with materials and battery

{
  "gtin": "08523456790018",
  "batch_lot": "LOT2026A",
  "serial_number": "SN000001",
  "product_name": { "en": "EV Battery 75kWh", "sk": "EV Bateria 75kWh" },
  "sector": "battery",
  "carbon_footprint": { "total_kg_co2": 8700 },
  "recycled_content": 18.5,
  "ce_marking": true,
  "materials": [
    { "name": "Lithium", "percentage": 8.2, "origin_country": "CL", "is_critical": true }
  ],
  "substances": [
    { "name": "Cobalt", "cas_number": "7440-48-4", "concentration_ppm": 61000, "svhc": true }
  ],
  "battery": {
    "chemistry": "NMC",
    "capacity_kwh": 75.0,
    "nominal_voltage": 400,
    "cycle_life": 1500
  }
}

Response 201

{ "id": "uuid", "gtin": "08523456790018", "message": "Product created" }

Updates product fields. Only include fields you want to change — all other fields remain unchanged. The DPP viewer updates immediately with no QR code reprint needed.

Response 200

{ "message": "Product updated", "id": "uuid" }

Soft-deletes the product — sets status to deleted. The DPP is no longer publicly accessible.

Uploads a document file and attaches it to the product. Use multipart/form-data with the file in the file field.

Query parameters

Supported doc_type values

Example (curl)

curl -X POST "https://dpp.gs/api/v1/products/08523456790018/documents?doc_type=declaration_of_conformity" \
  -H "x-api-key: your-key" \
  -F "[email protected]"

Response 201

{
  "id": "uuid",
  "doc_type": "declaration_of_conformity",
  "filename": "declaration.pdf",
  "url": "https://dpp-documents.s3.eu-central-1.amazonaws.com/...",
  "message": "Document uploaded"
}

Deletes a document attachment from the product. Removes the file from storage.

URL parameters

Response 200

{ "message": "Document deleted" }

Upload a CSV file to create multiple products at once. Use multipart/form-data with the file in the file field.

Example (curl)

curl -X POST https://dpp.gs/api/v1/products/batch \
  -H "x-api-key: your-key" \
  -F "[email protected]"

Response 200

{ "created": 47, "skipped": 2, "errors": [] }

Download the CSV template to see all supported columns:

curl https://dpp.gs/api/v1/template.csv -o template.csv

Returns a QR code or DataMatrix image for the given GTIN. No authentication required — suitable for embedding in label templates.

Query parameters

Examples

GET /qr/08523456790018
→ PNG QR code encoding https://dpp.gs/01/08523456790018

GET /qr/08523456790018?batch=LOT2026A&format=datamatrix
→ PNG DataMatrix encoding (01)08523456790018(10)LOT2026A

GET /qr/08523456790018?format=svg
→ SVG QR code (for vector label templates)

Generates a ZIP archive with QR and DataMatrix codes for multiple GTINs.

Request body

{
  "gtins": ["08523456790018", "08523456790025"],
  "format": "both"
}

format accepts: qr · datamatrix · both

Response

Returns a ZIP file containing PNG files named {gtin}_qr.png and {gtin}_datamatrix.png.

Generates a ZIP archive with QR + DataMatrix codes for a range of serial numbers. Each code encodes a GS1 Digital Link with AI (01) GTIN + AI (10) batch + AI (21) serial.

Request body

{
  "gtin": "08523456790018",
  "batch": "LOT2026A",
  "prefix": "SN",
  "start": 1,
  "count": 100,
  "format": "both"
}

prefix — serial number prefix (default: "SN"). start — first serial number (default: 1). count — number of codes to generate (max 10,000).

Response

ZIP file with qr/ and datamatrix/ folders + manifest.csv listing all serial numbers, GS1 Digital Link URIs, and GS1 AI strings.

Creates a new serial number batch for the product. Supports two modes: sequential (auto-generate a range) or upload (provide your own serial numbers via CSV).

Request body (sequential mode)

{
  "mode": "sequential",
  "batch_lot": "LOT2026A",
  "prefix": "SN",
  "start": 1,
  "count": 500
}

Request body (upload mode)

Use multipart/form-data with a CSV file in the file field. The CSV must contain a serial_number column.

curl -X POST "https://dpp.gs/api/v1/products/08523456790018/serial-batches" \
  -H "x-api-key: your-key" \
  -F "mode=upload" \
  -F "batch_lot=LOT2026A" \
  -F "[email protected]"

Response 201

{
  "id": "uuid",
  "gtin": "08523456790018",
  "batch_lot": "LOT2026A",
  "count": 500,
  "mode": "sequential",
  "message": "Serial batch created"
}

Returns all serial number batches for the given product, ordered by creation date descending.

Response 200

"batches": [
  {
    "id": "uuid",
    "batch_lot": "LOT2026A",
    "count": 500,
    "mode": "sequential",
    "created_at": "2026-03-15T10:00:00Z"
  }
]

Returns full detail of a serial batch, including all serial numbers in the batch.

Response 200

{
  "id": "uuid",
  "gtin": "08523456790018",
  "batch_lot": "LOT2026A",
  "count": 500,
  "mode": "sequential",
  "prefix": "SN",
  "start": 1,
  "serials": ["SN000001", "SN000002", "..."],
  "created_at": "2026-03-15T10:00:00Z"
}

Downloads a CSV manifest of all serial numbers in the batch, including GS1 Digital Link URIs and GS1 AI strings.

Response

Returns a CSV file with columns: serial_number, gtin, batch_lot, digital_link, gs1_ai_string.

Downloads a ZIP archive containing QR and/or DataMatrix code images for every serial number in the batch.

Query parameters

Response

ZIP file with qr/ and/or datamatrix/ folders + manifest.csv.

Deletes a serial number batch and all associated serial number records.

Response 200

{ "message": "Serial batch deleted" }

GS1 Digital Link resolver with full content negotiation.

Query parameters

?linkType=gs1:epil — redirect to specific link type. ?linkType=linkset — return full linkset (RFC 9264). All other query params are passed through on redirects.

JSON response

{
  "gtin": "08523456790018",
  "batchLot": "LOT2026A",
  "linkTargets": [
    {
      "linkType": "gs1:epil",
      "title": "Digital Product Passport",
      "targetUrl": "https://dpp.gs/passport/08523456790018"
    },
    {
      "linkType": "gs1:pip",
      "title": "Product Information",
      "targetUrl": "https://dpp.gs/product/08523456790018"
    }
  ]
}

HTTP Link headers

All responses include a Link header pointing to the linkset: Link: <...?linkType=linkset>; rel="linkset"; type="application/linkset+json"

GS1 Resolver Description File per GS1-Conformant Resolver Standard. Returns supported primary keys, link types, and resolver root URL.

Returns the public HTML Digital Product Passport page. This is what consumers see when they scan the QR code.

Query parameters

Examples

GET /passport/08523456790018?batch=LOT2026A
→ Live demo — EV Battery Pack 75kWh

Exports battery product data in formats accepted by EPR collection schemes and national registries.

Query parameters

Example

GET /api/v1/epr-export/batteries?format=csv&from=2026-01-01&to=2026-03-31&country=SK

Response

Returns a file download in the requested format. CSV includes columns for GTIN, batch, weight, chemistry, category, and quantities placed on market.

Exports individual battery unit records with lifecycle status for EPR reporting.

Query parameters

Returns all EPR registrations for the tenant — producer registration numbers with national collection schemes.

Response 200

"registrations": [
  {
    "id": "uuid",
    "country": "SK",
    "scheme_name": "NATUR-PACK",
    "registration_number": "SK-BAT-2026-001",
    "valid_from": "2026-01-01",
    "valid_to": "2026-12-31"
  }
]

Registers a new EPR scheme membership for the tenant.

Request body

{
  "country": "SK",
  "scheme_name": "NATUR-PACK",
  "registration_number": "SK-BAT-2026-001",
  "valid_from": "2026-01-01",
  "valid_to": "2026-12-31"
}

Response 201

{ "id": "uuid", "message": "EPR registration created" }

Creates a per-unit record for an individual battery instance linked to the product GTIN.

Request body

{
  "unique_identifier": "BAT-2026-00001",
  "serial_number": "SN000001",
  "batch_lot": "LOT2026A",
  "manufacturing_date": "2026-03-15",
  "status": "active"
}

Response 201

{
  "uid": "BAT-2026-00001",
  "gtin": "08523456790018",
  "message": "Battery unit created"
}

Returns all battery unit records for the given product GTIN.

Response 200

"units": [
  {
    "uid": "BAT-2026-00001",
    "serial_number": "SN000001",
    "batch_lot": "LOT2026A",
    "status": "active",
    "manufacturing_date": "2026-03-15",
    "created_at": "2026-03-15T10:00:00Z"
  }
]

Returns full detail of a battery unit by its unique identifier, including lifecycle events and state of health history.

URL parameters

Updates the status or metadata of a battery unit.

Request body

{
  "status": "end_of_life",
  "end_of_life_date": "2026-04-10"
}

Response 200

{ "uid": "BAT-2026-00001", "message": "Battery unit updated" }

Returns the current and historical state of health (SoH) data for the battery unit. Authenticated via Bearer token (API key or JWT).

Response 200

{
  "uid": "BAT-2026-00001",
  "current_soh_pct": 94.2,
  "capacity_fade_pct": 5.8,
  "cycle_count": 312,
  "last_updated": "2026-04-01T08:30:00Z",
  "history": [
    { "date": "2026-04-01", "soh_pct": 94.2, "cycle_count": 312 }
  ]
}

Submits a new state of health reading from the Battery Management System (BMS). Typically called periodically by the BMS or telematics system.

Request body

{
  "soh_pct": 93.8,
  "capacity_fade_pct": 6.2,
  "cycle_count": 325,
  "internal_resistance_mohm": 2.4,
  "temperature_avg_c": 28,
  "measured_at": "2026-04-10T14:00:00Z"
}

Response 201

{ "message": "SoH reading recorded" }

Adds a lifecycle event to the battery unit's history — e.g. commissioning, maintenance, transfer, recall, or end-of-life processing.

Request body

{
  "event_type": "maintenance",
  "description": "Scheduled BMS firmware update and cell balancing",
  "performed_by": "ServiceCo GmbH",
  "event_date": "2026-04-10"
}

Response 201

{ "id": "uuid", "message": "Event recorded" }

Returns the EU Declaration of Conformity for the product, auto-generated from the product data and uploaded documents.

Query parameters

Example

GET /api/v1/products/08523456790018/declaration-of-conformity?format=html
→ Printable HTML EU Declaration of Conformity

Returns regulatory information for all DPP sections — which EU regulations require each data section, applicability per product sector, and compliance deadlines. Public endpoint, no authentication required.

Response 200

{
  "sections": [
    {
      "key": "battery",
      "title": "Battery Information",
      "regulation": "EU 2023/1542",
      "sectors": ["battery"],
      "mandatory": true,
      "effective_date": "2027-02-18"
    }
  ]
}