{ "openapi": "3.1.0", "info": { "title": "DPP Hero API", "description": "REST API for creating, managing, and exporting Digital Product Passports. Data attributes follow DIN SPEC 99100; all JSON exports use the Battery Passport Data Model v2.0 (GEFEG category schemas, validated before delivery). Battery condition data (BMS) uses a separate endpoint (PATCH /products/{id}/condition). The DPP lookup endpoints (/dpps, /dppsByProductId, /dppsByProductIds) are aligned with the methods and REST conventions of EN 18222:2026; a complete conformity assessment including dependent standards is still open.", "version": "1.0.0", "contact": { "name": "DPP Hero Support", "url": "https://app.dpphero.com", "email": "support@dpphero.com" } }, "servers": [ { "url": "https://app.dpphero.com/api/v1", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/products": { "get": { "operationId": "listProducts", "summary": "List products", "description": "Returns a paginated list of all products in your organization.", "tags": [ "Products" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "batteries", "batteries_light" ] } }, { "name": "battery_category", "in": "query", "schema": { "type": "string", "enum": [ "lmt", "ev", "industrial", "stationary", "industrial_without_bms" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by product name, serial_number or gtin (partial match)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "status" ], "default": "created_at" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Paginated product list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/LightProduct" } ] } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createProduct", "summary": "Create product", "description": "Creates a new product as draft. Send \"status\": \"published\" to publish immediately with full validation. Accepts all 7 DIN SPEC 99100 steps in a single request. Alternatively accepts a GEFEG Battery Passport Data Model v1.3 tree (top-level key Battery_Passport): all scalar fields are mapped from the same registry paths the export writes; aggregate-only sections (BatteryMaterialsAndComposition, SymbolsLabelsAndDocumentationOfConformity) are rejected with a clear error — use the flat API fields for those. Input stays v1.3-only: v2.0 trees (top-level keys dppHeader/batteryPassportData) are rejected with a clear error, the v2.0 shape exists as EXPORT format only. Provide name and warranty_period as flat fields alongside the tree (no v1.3 data points). Manufacturer fields (mfr_*) are auto-filled from your organization profile when omitted. The serial number must be unique within your organization, and the GTIN + serial number combination must be globally unique — returns 409 on conflict. Battery models without passport ('batteries_light'): send category 'batteries_light' with the LightProductCreate fields; they are created as draft (publishing this class via API v1 is not supported yet) and are not accepted by the bulk endpoint.", "tags": [ "Products" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProductCreateDraft" }, { "$ref": "#/components/schemas/LightProductCreate" } ] } } } }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/LightProduct" } ] }, "meta": { "$ref": "#/components/schemas/CreateMeta" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/products/bulk": { "post": { "operationId": "bulkCreateProducts", "summary": "Bulk create products", "description": "Creates up to 500 products in a single request. Each product is validated individually — invalid entries are skipped. Auto-fill applies per product. Duplicates are skipped with reason duplicate_in_request or duplicate_in_database: a serial number already used in your organization, or a GTIN + serial number combination already in use. Rows with category 'batteries_light' are rejected per row: create battery models without passport one by one via POST /products or via CSV import.", "tags": [ "Products" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCreateDraft" }, "maxItems": 500 } } } } } }, "responses": { "201": { "description": "Bulk creation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "imported": { "type": "integer" }, "skipped": { "type": "integer" }, "skipped_serials": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "serial_number": { "type": [ "string", "null" ] }, "reason": { "type": "string", "enum": [ "validation_failed", "duplicate_in_request", "duplicate_in_database" ] }, "errors": { "type": "object", "description": "Validation errors (only for validation_failed)" } } } }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "meta": { "type": "object", "description": "Present when warnings or unrecognized fields exist", "properties": { "unrecognized_fields": { "type": "array", "items": { "type": "string" } }, "field_warnings": { "type": "object" } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get product", "description": "Returns a single product with all step data (materials, carbon footprint, circularity, performance, labeling, etc.).", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/LightProduct" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateProduct", "summary": "Update product", "description": "Partially updates a product. Only send the fields you want to change. Set status to \"published\" to publish. Publishing requires complete organization profile and all 7 steps at 100%. The GTIN + serial number combination must remain globally unique — returns 409 on conflict. After pre-print QR lock or publication, gtin and serial_number are immutable because QR codes use these identifiers — attempts to change them return 409. Changing battery_category on a published product requires ?confirm=true — without it, returns HTTP 409.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "name": "confirm", "in": "query", "schema": { "type": "boolean" }, "description": "Required for changing battery_category on published products" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProductUpdate" }, { "$ref": "#/components/schemas/LightProductUpdate" } ] } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/LightProduct" } ] }, "meta": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteProduct", "summary": "Delete product", "description": "Permanently deletes a product. For published products, append ?confirm=true — without it, returns HTTP 409.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "name": "confirm", "in": "query", "schema": { "type": "boolean" }, "description": "Required for deleting published products" } ], "responses": { "200": { "description": "Product deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Confirmation required for published product" } } } }, "/products/{id}/image": { "post": { "operationId": "uploadProductImage", "summary": "Upload product image", "description": "Uploads a product image (JPEG, PNG, or WebP, max 10 MB). Automatically resized to max 1600px and quality-optimized. Replaces any existing image.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Image uploaded" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "operationId": "deleteProductImage", "summary": "Remove product image", "description": "Removes the product image and deletes the file from storage.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "Image removed" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/products/{id}/files": { "post": { "operationId": "uploadFile", "summary": "Upload document/file", "description": "Uploads a document or image (PDF, JPEG, PNG, WebP, max 10 MB). Returns a public URL. Assign the URL to the desired product field via PATCH /products/{id}.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "fileName": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/products/{id}/condition": { "get": { "operationId": "getCondition", "summary": "Read battery condition", "description": "Returns current battery condition data (state of charge, capacity fade, cycle count, temperature history, etc.). Fields and constraints are derived from the Registry and feed the Annex XIII / GEFEG Battery Passport Data Model v2.0 export. Returns null if no data has been submitted yet.", "tags": [ "Battery Condition" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "Battery condition data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "serial_number": { "type": "string" }, "battery_status": { "type": [ "string", "null" ] }, "battery_condition": { "oneOf": [ { "$ref": "#/components/schemas/BatteryCondition" }, { "type": "null" } ] }, "has_condition_data": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "upsertCondition", "summary": "Create or update battery condition", "description": "Creates or updates BMS data for a product (upsert). On first call, data is created; on subsequent calls, only sent fields are updated — existing fields remain unchanged. Unknown fields are rejected at all nesting levels (HTTP 400). lastUpdate = timestamp of measurement, not API submission time. Future timestamps are rejected.", "tags": [ "Battery Condition" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatteryCondition" } } } }, "responses": { "200": { "description": "Condition updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "serial_number": { "type": "string" }, "battery_condition": { "$ref": "#/components/schemas/BatteryCondition" }, "updated_fields": { "type": "array", "items": { "type": "string" }, "description": "List of top-level keys that were updated in this request" } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products/{id}/export/json": { "get": { "operationId": "exportJson", "summary": "Export battery passport v2.0 JSON", "description": "Returns the battery passport in Battery Passport Data Model v2.0 format, identical to /products/{id}/export/gefeg-json (canonical address), validated against the GEFEG category schema of the battery type. Published products with a battery type only. Owner-only export: contains fields that are not public on the passport (battery condition values, test report, facility GLN).", "tags": [ "Export" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "Battery Passport v2.0 JSON file", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Product is draft — export requires published status", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Export blocked — product data failed the data model validation; errors listed in details", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "export_validation_failed" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } } }, "deprecated": true } }, "/products/{id}/export/gefeg-json": { "get": { "operationId": "exportProductGefegJson", "summary": "Export battery passport v2.0 JSON (GEFEG)", "description": "Returns the battery passport in Battery Passport Data Model v2.0 format, validated against the GEFEG category schema of the battery type (BatteryPass-Ready). Published products with a battery_category only. Requires API key.", "tags": [ "Export" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "DIN SPEC 99100 JSON file", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Product is draft — export requires published status", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Export blocked — product data failed the data model validation; errors listed in details", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "export_validation_failed" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } } } } }, "/products/{id}/export/pdf": { "get": { "operationId": "exportPdf", "summary": "Export battery passport PDF", "description": "Downloads the battery passport as a formatted PDF. Published products only. Owner-only export: contains fields that are not public on the passport (battery condition values, test report, facility GLN); those rows carry an \"Authorities only\" tag.", "tags": [ "Export" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Product is draft — export requires published status. Also returned when a custom domain is configured but not active yet (code forbidden)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products/{id}/preprint-qr": { "post": { "operationId": "preparePreprintQr", "summary": "Prepare pre-print QR", "description": "Locks GTIN and serial_number for a draft product so a QR code can be printed or exported before publication. Publishing a product does not require this endpoint; publication locks identifiers as part of the normal publish flow.", "tags": [ "Export" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "de", "en", "zh" ], "default": "de" } } } } } }, "responses": { "200": { "description": "Identifiers locked and QR export URLs returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "public_url": { "type": "string" }, "qr_svg_url": { "type": "string" }, "qr_png_url": { "type": "string" }, "identifiers_locked_at": { "type": "string", "format": "date-time" }, "identifiers_locked_reason": { "type": "string", "enum": [ "preprint_qr", "published" ] } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Custom domain is configured but not active yet — activate it before generating pre-print QR codes so printed codes carry your domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products/{id}/export/qr": { "get": { "operationId": "exportQr", "summary": "Export QR code", "description": "Downloads the QR code as SVG (default) or PNG (1024x1024). Published and pre-print locked products are accessible without an API key. A draft that is not yet locked must first be locked via POST /products/{id}/preprint-qr.", "tags": [ "Export" ], "security": [ {}, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "svg", "png" ], "default": "svg" } } ], "responses": { "200": { "description": "QR code image", "content": { "image/svg+xml": { "schema": { "type": "string" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Product is draft and has no pre-print QR lock, or a custom domain is configured but not active yet (code forbidden, custom_domain_pending)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/organization": { "get": { "operationId": "getOrganization", "summary": "Get organization", "description": "Returns your organization profile, public address, GLN/EORI identifiers, and current plan. This is the operator data that appears on every published battery passport.", "tags": [ "Organization" ], "responses": { "200": { "description": "Organization profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/facilities": { "get": { "operationId": "listFacilities", "summary": "List manufacturing facilities", "description": "Returns all manufacturing facilities of your organization. Use the facility ID when creating products.", "tags": [ "Organization" ], "responses": { "200": { "description": "Facility list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Facility" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/audit-log": { "get": { "operationId": "getAuditLog", "summary": "Query audit log", "description": "Returns all logged actions of your organization (newest first).", "tags": [ "Organization" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "action", "in": "query", "schema": { "type": "string" }, "description": "e.g. product.published" }, { "name": "resource_type", "in": "query", "schema": { "type": "string", "enum": [ "product", "api_key", "facility" ] } }, { "name": "resource_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/dppsByProductId/{productId}": { "get": { "operationId": "readDppByProductId", "summary": "Read active battery passport by unique product ID (EN 18222 ReadDPPByProductId)", "description": "Returns the current active (published) battery passport for a unique product identifier as Battery Passport Data Model v2.0 JSON, validated against the GEFEG category schema. productId format: \":\" (DPP Hero convention until the official EN 18219 identifier schema is published; same unit identity as the GS1 Digital Link 01/{gtin14}/21/{serial}). Aligned with EN 18222:2026 method ReadDPPByProductId (mandatory). Requires API key.", "tags": [ "DPP (EN 18222)" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Unique product identifier: \":\", URL-encoded (e.g. 04012345123456:SN-2026-001)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active battery passport (Battery Passport Data Model v2.0 JSON)", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed productId (expected \":\")", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_error" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Export blocked — product data failed the data model validation; errors listed in details", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "export_validation_failed" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } } } } }, "/dppsByProductIds": { "post": { "operationId": "readDppIdsByProductIds", "summary": "Read DPP IDs for multiple product IDs (EN 18222 ReadDPPIdsByProductIds)", "description": "Returns a flat, deduplicated, deterministically sorted list of passport IDs for the submitted unique product identifiers. Body: non-empty JSON array of product IDs in \":\" format (max 500 per request, DPP Hero convention until the official EN 18219 identifier schema is published). Pagination via query parameters limit (1-1000, default 100) and cursor (opaque, from the Link rel=\"next\" header of the previous response; must not be empty). Only published passports of your own organization match. Aligned with EN 18222:2026 method ReadDPPIdsByProductIds (mandatory). Requires API key.", "tags": [ "DPP (EN 18222)" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size 1-1000 (default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous Link rel=\"next\" header; must not be empty", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string", "description": "\":\"" } } } } }, "responses": { "200": { "description": "Flat list of matching passport IDs (possibly empty); next page via Link rel=\"next\" response header", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } }, "400": { "description": "Malformed body, product ID, limit or cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_error" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/dpps/{dppId}": { "get": { "operationId": "readDppById", "summary": "Read battery passport by DPP ID (EN 18222 ReadDPPById)", "description": "Returns the published battery passport for the given passport ID (the product UUID used across this API, e.g. from /dppsByProductIds) as Battery Passport Data Model v2.0 JSON, validated against the GEFEG category schema. Aligned with EN 18222:2026 method ReadDPPById (mandatory). Requires API key. With the optional date query parameter, the historical version valid at that timestamp is returned instead.", "tags": [ "DPP (EN 18222)" ], "parameters": [ { "name": "dppId", "in": "path", "required": true, "description": "Passport ID (product UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": false, "description": "Optional ISO 8601 timestamp (UTC). Returns the passport version that was publicly valid at that moment (EN 18222 ReadDPPVersionByIdAndDate). Versions are recorded from 2026-07-23 onward; 404 if no version covers the timestamp. Without this parameter the current passport is returned.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Battery passport (Battery Passport Data Model v2.0 JSON)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Passport is draft — the DPP API serves published passports only", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Export blocked — product data failed the data model validation; errors listed in details", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "export_validation_failed" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from Settings → API Keys (Scale plan required)" } }, "parameters": { "ProductId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Product UUID" } }, "responses": { "Unauthorized": { "description": "401 — Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "403 — Plan required (code plan_required), account locked (account_locked), draft product limit reached (product_limit_reached, fair-use cap counting drafts only), or published passport monthly limit reached (published_limit_reached). Limit errors include details { current, max }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "404 — Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "400 — Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_error" }, "message": { "type": "string" }, "details": { "type": "object", "description": "Field name mapped to an array of error messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "unrecognized_fields": { "type": "array", "description": "Present when the request contained unknown fields.", "items": { "type": "string" } } } } } } } } }, "Conflict": { "description": "409 — A product with this GTIN + serial number already exists, or the serial number already exists within your organization. The GTIN + serial number combination must be globally unique. Also returned as code custom_domain_pending when a custom domain is configured but not active yet: publishing is blocked until the domain is active, so new codes carry your domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "description": "Optional structured context. Limit errors (product_limit_reached, published_limit_reached) return { current, max }.", "additionalProperties": true }, "correlation_id": { "type": "string", "format": "uuid", "description": "Support correlation ID, also returned as X-Correlation-Id response header. Include it in support requests so we can find the incident in our logs." } } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "ProductCreate": { "type": "object", "description": "Base payload shape for product write operations. For draft creation, use ProductCreateDraft. For publish readiness, also satisfy ProductPublishRequirements.", "required": [ "name", "battery_category", "serial_number" ], "properties": { "name": { "type": "string", "description": "Product name (trimmed)", "minLength": 3, "maxLength": 120 }, "status": { "type": "string", "description": "draft = save partial data; published = triggers full readiness validation", "enum": [ "draft", "published" ], "default": "draft" }, "serial_number": { "type": "string", "description": "Unique within your organization. The combination of gtin + serial_number must be globally unique (one physical battery = one GTIN + serial).", "minLength": 3, "maxLength": 50, "pattern": "^[A-Za-z0-9\\-\\/]+$" }, "category": { "type": "string", "enum": [ "batteries", "batteries_light" ], "default": "batteries" }, "battery_category": { "type": "string", "enum": [ "lmt", "ev", "industrial", "stationary", "industrial_without_bms" ] }, "manufacturing_date": { "type": [ "string", "null" ], "description": "ISO 8601 date-time (e.g. 2026-01-15T00:00:00Z) or date-only (2026-01-15), must not be in the future", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$", "format": "date-time" }, "battery_mass": { "type": [ "number", "null" ], "description": "Mass in kg (max 100,000)", "exclusiveMinimum": 0, "maximum": 100000 }, "battery_status": { "type": [ "string", "null" ], "enum": [ "Original", "Repurposed", "Reused", "Remanufactured", "Waste", null ], "default": "Original" }, "warranty_period": { "type": [ "integer", "null" ], "description": "Warranty period as calendar months (1–12); the v2.0 export emits it as an ISO 8601 duration (warrantyPeriod, e.g. P96M)", "minimum": 1, "maximum": 240 }, "putting_into_service": { "type": [ "string", "null" ], "description": "ISO 8601 date-time or date-only. Required only for battery_category=lmt or stationary; must not be in the future and not before manufacturing_date", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$", "format": "date-time" }, "gtin": { "type": [ "string", "null" ], "description": "GTIN with valid check digit", "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "facility_id": { "type": [ "string", "null" ], "description": "Manufacturing facility UUID (from GET /facilities). Facility must have complete address (street, postal code, city, country)", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "format": "uuid" }, "ghsPictogram": { "type": [ "string", "null" ], "description": "Auto-fills HazardousMaterial label on POST when labels are empty", "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental", null ] }, "mfr_name": { "type": [ "string", "null" ], "description": "Auto-filled from org profile when empty", "minLength": 3 }, "mfr_identifier": { "type": [ "string", "null" ], "description": "GLN:... or EORI:... — auto-filled when empty", "pattern": "^$|^(?:GLN:\\d{13}|EORI:[A-Za-z]{2}[A-Za-z0-9]{8,15})$" }, "mfr_street": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_street2": { "type": [ "string", "null" ] }, "mfr_postal_code": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_city": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2", "minLength": 2, "maxLength": 2 }, "mfr_email": { "type": [ "string", "null" ], "description": "Manufacturer email (optional)", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "format": "email" }, "mfr_website": { "type": [ "string", "null" ], "description": "Manufacturer website URL (optional)", "format": "uri" }, "materials": { "anyOf": [ { "$ref": "#/components/schemas/Materials" }, { "type": "null" } ] }, "hazardous": { "anyOf": [ { "$ref": "#/components/schemas/Hazardous" }, { "type": "null" } ] }, "carbon_footprint": { "anyOf": [ { "$ref": "#/components/schemas/CarbonFootprint" }, { "type": "null" } ] }, "due_diligence": { "anyOf": [ { "$ref": "#/components/schemas/DueDiligence" }, { "type": "null" } ] }, "circularity": { "anyOf": [ { "$ref": "#/components/schemas/Circularity" }, { "type": "null" } ] }, "performance": { "anyOf": [ { "$ref": "#/components/schemas/Performance" }, { "type": "null" } ] }, "labeling": { "anyOf": [ { "$ref": "#/components/schemas/Labeling" }, { "type": "null" } ] }, "_manufacturingPlace": { "type": "object", "description": "Manufacturing facility as an inline address. Complete or omitted entirely: street, postal_code, city, country required together; matching existing facility is reused, otherwise one is created. gln is the 13-digit GS1 facility identifier (required to publish; the DPP endpoints need it as UniqueFacilityIdentifier).", "properties": { "gln": { "type": [ "string", "null" ], "description": "GS1 Global Location Number (13 digits, valid check digit). Required for publishing. Not public on the passport: visible to authorities, notified bodies and the Commission only.", "minLength": 13, "maxLength": 13, "pattern": "^\\d{13}$" }, "street": { "type": "string", "minLength": 3 }, "street2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string", "minLength": 3 }, "city": { "type": "string", "minLength": 3 }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2", "minLength": 2, "maxLength": 2 } }, "required": [ "street", "postal_code", "city", "country" ] } } }, "ProductCreateDraft": { "allOf": [ { "$ref": "#/components/schemas/ProductCreate" } ], "description": "Draft creation schema (minimal required fields). Additional fields can be provided incrementally." }, "ProductPublishRequirements": { "type": "object", "description": "Additional fields and constraints that must be satisfied before a product can be published. Publish validation is enforced server-side via readiness checks.", "required": [ "name", "battery_category", "serial_number", "manufacturing_date", "battery_mass", "battery_status", "warranty_period", "gtin", "facility_id", "mfr_name", "mfr_identifier", "mfr_street", "mfr_postal_code", "mfr_city", "mfr_country" ], "properties": { "name": { "type": "string", "minLength": 3 }, "battery_category": { "type": "string", "enum": [ "lmt", "ev", "industrial", "stationary", "industrial_without_bms" ] }, "serial_number": { "type": "string", "minLength": 3, "maxLength": 50 }, "manufacturing_date": { "type": "string", "format": "date-time" }, "battery_mass": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "battery_status": { "type": "string", "enum": [ "Original", "Repurposed", "Reused", "Remanufactured", "Waste" ] }, "warranty_period": { "type": "integer", "minimum": 1, "maximum": 12 }, "putting_into_service": { "description": "Required only for battery_category=lmt or stationary", "type": "string", "format": "date-time" }, "gtin": { "type": "string", "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, "facility_id": { "type": "string", "format": "uuid" }, "mfr_name": { "type": "string", "minLength": 3 }, "mfr_identifier": { "type": "string", "minLength": 1 }, "mfr_street": { "type": "string", "minLength": 3 }, "mfr_postal_code": { "type": "string", "minLength": 3 }, "mfr_city": { "type": "string", "minLength": 3 }, "mfr_country": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "ProductUpdate": { "type": "object", "description": "Partial update — only send fields you want to change", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "published" ], "default": "draft" }, "serial_number": { "type": "string", "description": "The combination of gtin + serial_number must be globally unique. Immutable after pre-print QR lock or publication.", "minLength": 3, "maxLength": 50, "pattern": "^[A-Za-z0-9\\-\\/]+$" }, "battery_category": { "type": "string", "enum": [ "lmt", "ev", "industrial", "stationary", "industrial_without_bms" ] }, "manufacturing_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$", "format": "date-time" }, "battery_mass": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "maximum": 100000 }, "battery_status": { "type": [ "string", "null" ], "enum": [ "Original", "Repurposed", "Reused", "Remanufactured", "Waste", null ] }, "warranty_period": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 240 }, "putting_into_service": { "description": "Required only for battery_category=lmt or stationary", "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$", "format": "date-time" }, "gtin": { "type": [ "string", "null" ], "description": "GTIN with 8, 12, 13 or 14 digits. Immutable after pre-print QR lock or publication.", "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "facility_id": { "type": [ "string", "null" ], "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "format": "uuid" }, "mfr_name": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_identifier": { "type": [ "string", "null" ], "pattern": "^$|^(?:GLN:\\d{13}|EORI:[A-Za-z]{2}[A-Za-z0-9]{8,15})$" }, "mfr_street": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_street2": { "type": [ "string", "null" ] }, "mfr_postal_code": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_city": { "type": [ "string", "null" ], "minLength": 3 }, "mfr_country": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "mfr_email": { "type": [ "string", "null" ], "description": "Manufacturer email (optional)", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "format": "email" }, "mfr_website": { "type": [ "string", "null" ], "description": "Manufacturer website URL (optional)", "format": "uri" }, "materials": { "anyOf": [ { "$ref": "#/components/schemas/Materials" }, { "type": "null" } ] }, "hazardous": { "anyOf": [ { "$ref": "#/components/schemas/Hazardous" }, { "type": "null" } ] }, "carbon_footprint": { "anyOf": [ { "$ref": "#/components/schemas/CarbonFootprint" }, { "type": "null" } ] }, "due_diligence": { "anyOf": [ { "$ref": "#/components/schemas/DueDiligence" }, { "type": "null" } ] }, "circularity": { "anyOf": [ { "$ref": "#/components/schemas/Circularity" }, { "type": "null" } ] }, "performance": { "anyOf": [ { "$ref": "#/components/schemas/Performance" }, { "type": "null" } ] }, "labeling": { "anyOf": [ { "$ref": "#/components/schemas/Labeling" }, { "type": "null" } ] }, "ghsPictogram": { "anyOf": [ { "type": "string", "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental" ] }, { "type": "null" } ], "type": [ "string", "null" ], "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental", null ] }, "_manufacturingPlace": { "type": "object", "description": "Manufacturing facility as an inline address. Complete or omitted entirely: street, postal_code, city, country required together; matching existing facility is reused, otherwise one is created. gln is the 13-digit GS1 facility identifier (required to publish; the DPP endpoints need it as UniqueFacilityIdentifier).", "properties": { "gln": { "type": [ "string", "null" ], "description": "GS1 Global Location Number (13 digits, valid check digit). Required for publishing. Not public on the passport: visible to authorities, notified bodies and the Commission only.", "minLength": 13, "maxLength": 13, "pattern": "^\\d{13}$" }, "street": { "type": "string", "minLength": 3 }, "street2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string", "minLength": 3 }, "city": { "type": "string", "minLength": 3 }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2", "minLength": 2, "maxLength": 2 } }, "required": [ "street", "postal_code", "city", "country" ] } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "published" ], "default": "draft" }, "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "category": { "type": "string", "enum": [ "batteries", "batteries_light" ], "default": "batteries" }, "battery_category": { "type": "string", "enum": [ "lmt", "ev", "industrial", "stationary", "industrial_without_bms" ] }, "serial_number": { "type": "string" }, "manufacturing_date": { "type": [ "string", "null" ], "format": "date-time" }, "battery_mass": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "maximum": 100000 }, "battery_status": { "type": [ "string", "null" ], "enum": [ "Original", "Repurposed", "Reused", "Remanufactured", "Waste" ], "default": "Original" }, "warranty_period": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 240 }, "putting_into_service": { "description": "Required only for battery_category=lmt or stationary", "type": [ "string", "null" ], "format": "date-time" }, "gtin": { "type": [ "string", "null" ], "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, "passport_identifier": { "type": [ "string", "null" ], "description": "Auto-generated URN on publish" }, "public_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public GS1 Digital Link (/01/{gtin}/21/{serial}) of the published product; resolves to the public product page. Falls back to the product page URL when the product has no GTIN. null for drafts." }, "exports": { "oneOf": [ { "type": "object", "properties": { "pdf_url": { "type": "string", "format": "uri" }, "qr_svg_url": { "type": "string", "format": "uri" }, "qr_png_url": { "type": "string", "format": "uri" } } }, { "type": "null" } ] }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "facility_id": { "type": [ "string", "null" ], "format": "uuid" }, "manufacturer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "identifier": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "street2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "materials": { "oneOf": [ { "$ref": "#/components/schemas/Materials" }, { "type": "null" } ] }, "hazardous": { "oneOf": [ { "$ref": "#/components/schemas/Hazardous" }, { "type": "null" } ] }, "carbon_footprint": { "oneOf": [ { "$ref": "#/components/schemas/CarbonFootprint" }, { "type": "null" } ] }, "due_diligence": { "oneOf": [ { "$ref": "#/components/schemas/DueDiligence" }, { "type": "null" } ] }, "circularity": { "oneOf": [ { "$ref": "#/components/schemas/Circularity" }, { "type": "null" } ] }, "performance": { "oneOf": [ { "$ref": "#/components/schemas/Performance" }, { "type": "null" } ] }, "labeling": { "oneOf": [ { "$ref": "#/components/schemas/Labeling" }, { "type": "null" } ] }, "battery_condition": { "oneOf": [ { "$ref": "#/components/schemas/BatteryCondition" }, { "type": "null" } ] }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Materials": { "type": "object", "properties": { "batteryChemistry": { "type": "object", "properties": { "shortName": { "type": "string" }, "clearName": { "type": "string", "minLength": 3 } } }, "batteryMaterials": { "type": "array", "items": { "type": "object", "required": [ "batteryMaterialName" ], "properties": { "batteryMaterialName": { "type": "string" }, "batteryMaterialIdentifier": { "type": "string", "description": "CAS number (e.g. 7439-93-2)", "pattern": "^\\d{2,7}-\\d{2}-\\d$" }, "batteryMaterialMass": { "type": "number", "description": "Mass in kg", "exclusiveMinimum": 0 }, "batteryMaterialLocation": { "type": "object", "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } }, "isCriticalRawMaterial": { "type": "boolean" } } }, "maxItems": 200 } } }, "Hazardous": { "type": "object", "description": "Hazardous substance data. Public on the battery passport (Annex XIII); the API returns it to the owner in the same form.", "properties": { "contains": { "type": "boolean" }, "hazardousSubstances": { "type": "array", "description": "Required when contains = true", "items": { "type": "object", "required": [ "hazardousSubstanceName" ], "properties": { "hazardousSubstanceName": { "type": "string" }, "hazardousSubstanceIdentifier": { "type": "string", "description": "CAS number", "pattern": "^\\d{2,7}-\\d{2}-\\d$" }, "hazardousSubstanceClass": { "type": "string", "enum": [ "AcuteToxicity", "SkinCorrosionOrIrritation", "EyeDamageOrIrritation" ] }, "hazardousSubstanceConcentration": { "type": "number", "description": "Concentration in %", "exclusiveMinimum": 0, "maximum": 100 }, "hazardousSubstanceImpact": { "type": "array", "items": { "type": "string" }, "description": "Impact statements on human health and environment" }, "hazardousSubstanceLocation": { "type": "object", "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } } } }, "maxItems": 200 } } }, "CarbonFootprint": { "type": "object", "properties": { "batteryCarbonFootprint": { "type": "number", "description": "kg CO₂e/kWh", "minimum": 0 }, "performanceClass": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ] }, "studyLink": { "type": "string", "description": "URL to LCA study", "format": "uri" }, "absoluteCarbonFootprint": { "type": "number", "description": "kg CO₂e", "minimum": 0 }, "lifecycleStages": { "type": "array", "items": { "type": "object", "required": [ "stage", "value" ], "properties": { "stage": { "type": "string", "enum": [ "RawMaterialExtraction", "MainProduction", "Distribution", "Recycling" ] }, "value": { "type": "number", "description": "kg CO₂e/kWh", "minimum": 0 } } }, "maxItems": 200 } } }, "DueDiligence": { "type": "object", "properties": { "dueDiligenceReport": { "type": "string", "format": "uri" }, "thirdPartyAssurances": { "type": "string", "format": "uri" }, "supplyChainIndices": { "type": "number", "minimum": 0, "maximum": 100 } } }, "Circularity": { "type": "object", "properties": { "dismantlingDocuments": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "DismantlingManual", "RemovalManual", "BillOfMaterial", "Model3D", "Drawing", "OtherManual" ] }, "documentURL": { "type": "string", "format": "uri" }, "mimeType": { "type": "string", "minLength": 1 } } }, "maxItems": 200 }, "sparePartSources": { "type": "array", "items": { "type": "object", "required": [ "nameOfSupplier", "supplierWebAddress" ], "properties": { "nameOfSupplier": { "type": "string", "minLength": 3 }, "emailAddressOfSupplier": { "type": "string", "format": "email" }, "supplierWebAddress": { "type": "string", "minLength": 1, "format": "uri" }, "addressOfSupplier": { "type": "object", "properties": { "streetAddress": { "type": "string", "minLength": 3 }, "street2": { "type": "string" }, "postalCode": { "type": "string", "minLength": 3 }, "city": { "type": "string", "minLength": 3 }, "addressCountry": { "type": "string", "description": "ISO 3166-1 alpha-2" } } }, "components": { "type": "array", "items": { "type": "object", "required": [ "partName", "partNumber" ], "properties": { "partName": { "type": "string", "minLength": 2 }, "partNumber": { "type": "string", "minLength": 2 } } }, "maxItems": 200 } } }, "maxItems": 200 }, "recycledContent": { "type": "array", "items": { "type": "object", "required": [ "recycledMaterial" ], "properties": { "recycledMaterial": { "type": "string", "enum": [ "Cobalt", "Nickel", "Lithium", "Lead" ] }, "preConsumerShare": { "type": "number", "minimum": 0, "maximum": 100 }, "postConsumerShare": { "type": "number", "minimum": 0, "maximum": 100 } } }, "maxItems": 200 }, "safetyMeasures": { "type": "object", "properties": { "safetyInstructions": { "type": "string", "format": "uri" }, "extinguishingAgent": { "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "K" ] }, "maxItems": 200 } } }, "endOfLifeInformation": { "type": "object", "properties": { "wastePrevention": { "type": "string", "format": "uri" }, "separateCollection": { "type": "string", "format": "uri" }, "informationOnCollection": { "type": "string", "format": "uri" } } }, "renewableContent": { "type": "number", "description": "%", "minimum": 0, "maximum": 100 } } }, "Performance": { "type": "object", "properties": { "ratedEnergy": { "type": "number", "description": "Wh. Required only for battery_category=ev", "minimum": 0 }, "ratedCapacity": { "type": "number", "description": "Ah", "minimum": 0 }, "nominalVoltage": { "type": "number", "description": "V", "minimum": 0 }, "minimumVoltage": { "type": "number", "description": "V", "minimum": 0 }, "maximumVoltage": { "type": "number", "description": "V (must be ≥ minimumVoltage)", "minimum": 0 }, "ratedMaximumPower": { "type": "number", "description": "W", "minimum": 0 }, "expectedLifetime": { "type": "number", "description": "Years", "minimum": 0 }, "expectedNumberOfCycles": { "type": "number", "minimum": 0 }, "capacityThresholdForExhaustion": { "type": "number", "description": "%. Required only for battery_category=ev", "minimum": 0, "maximum": 100 }, "roundtripEfficiency": { "type": "number", "description": "%", "minimum": 0, "maximum": 100 }, "temperatureRangeIdleStateMin": { "type": "number", "description": "°C", "minimum": -20, "maximum": 60 }, "temperatureRangeIdleStateMax": { "type": "number", "description": "°C (must be > min)", "minimum": -20, "maximum": 60 }, "lifetimeReferenceTest": { "type": "string", "format": "uri" }, "powerCapabilityRatio": { "type": "number", "minimum": 0 }, "originalPowerCapability": { "type": "array", "items": { "type": "object", "properties": { "atSoC": { "type": "number", "description": "State of charge level (%)", "minimum": 0, "maximum": 100, "enum": [ 80, 20 ] }, "powerCapabilityAt": { "type": "number", "description": "Power capability at this SoC (W)", "minimum": 0 } }, "required": [ "atSoC", "powerCapabilityAt" ] }, "description": "Power capability measurements at different SoC levels (80% and 20% per Annex IV Part B, point 4)", "maxItems": 200 }, "initialSelfDischarge": { "type": "number", "description": "% per month. Required only for battery_category=lmt or stationary", "minimum": 0 }, "cRateLifeCycleTest": { "type": "number", "minimum": 0 }, "initialInternalResistancePack": { "type": "number", "description": "Initial internal resistance pack (Ω)", "minimum": 0 }, "initialInternalResistanceModule": { "type": "number", "description": "Initial internal resistance module (Ω, optional)", "minimum": 0 }, "initialInternalResistanceCell": { "type": "number", "description": "Initial internal resistance cell (Ω). Required only for battery_category=lmt, ev, industrial or stationary", "minimum": 0 }, "voltageTemperatureRangeMin": { "type": "number", "description": "Lower temperature limit in °C for which the voltage values apply (optional, Annex XIII 1(h))", "minimum": -20, "maximum": 60 }, "voltageTemperatureRangeMax": { "type": "number", "description": "Upper temperature limit in °C for which the voltage values apply (optional, Annex XIII 1(h))", "minimum": -20, "maximum": 60 }, "powerTemperatureRangeMin": { "type": "number", "description": "Lower temperature limit in °C for which the power values apply (optional, Annex XIII 1(i))", "minimum": -20, "maximum": 60 }, "powerTemperatureRangeMax": { "type": "number", "description": "Upper temperature limit in °C for which the power values apply (optional, Annex XIII 1(i))", "minimum": -20, "maximum": 60 } } }, "Labeling": { "type": "object", "properties": { "declarationOfConformity": { "type": [ "string", "null" ], "description": "URL to EU declaration of conformity", "format": "uri" }, "resultOfTestReport": { "type": [ "string", "null" ], "description": "URL to test report (e.g. UN 38.3)", "format": "uri" }, "labels": { "type": "array", "description": "Auto-filled with default symbols when empty on POST", "items": { "type": "object", "required": [ "labelingSubject" ], "properties": { "labelingSubject": { "type": "string", "enum": [ "SeparateCollection", "HazardousMaterial", "CarbonFootPrint", "ExtinguishingAgent" ] }, "labelingSymbol": { "type": "string", "description": "URL to symbol SVG", "format": "uri" }, "carbonFootprintClass": { "type": "string", "description": "Required for CarbonFootPrint subject" }, "labelingMeaning": { "type": "object", "required": [ "de", "en" ], "properties": { "de": { "type": "string" }, "en": { "type": "string" } } }, "labelingSymbolFileName": { "type": [ "string", "null" ], "description": "Filename of the symbol SVG" }, "ghsPictogram": { "type": [ "string", "null" ], "description": "GHS pictogram type (only for HazardousMaterial)", "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental" ] } } }, "maxItems": 200 } } }, "BatteryCondition": { "type": "object", "description": "Dynamic BMS data — use PATCH /products/{id}/condition (upsert). All fields optional per request; required for a publishable passport depending on battery_category (see per-field notes). Fields and constraints are derived from the Registry and feed the Annex XIII / GEFEG Battery Passport Data Model v2.0 export.", "additionalProperties": false, "properties": { "stateOfCharge": { "type": "object", "description": "Required only for battery_category=lmt, ev, industrial or stationary", "required": [ "stateOfChargeValue", "lastUpdate" ], "additionalProperties": false, "properties": { "stateOfChargeValue": { "type": "number", "description": "State of charge in %", "minimum": 0, "maximum": 100 }, "lastUpdate": { "type": "string", "description": "Measurement timestamp (must not be in the future)", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "remainingCapacity": { "description": "Required only for battery_category=lmt or stationary", "type": "object", "required": [ "remainingCapacityValue", "lastUpdate" ], "additionalProperties": false, "properties": { "remainingCapacityValue": { "type": "number", "description": "Capacity in Ah", "minimum": 0 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "capacityFade": { "type": "object", "required": [ "capacityFadeValue", "lastUpdate" ], "additionalProperties": false, "properties": { "capacityFadeValue": { "type": "number", "description": "Loss in %", "minimum": 0, "maximum": 100 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "numberOfFullCycles": { "description": "Required only for battery_category=lmt, ev, industrial or stationary", "type": "object", "required": [ "numberOfFullCyclesValue", "lastUpdate" ], "additionalProperties": false, "properties": { "numberOfFullCyclesValue": { "type": "number", "minimum": 0 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "remainingEnergy": { "type": "object", "required": [ "remainingEnergyalue", "lastUpdate" ], "additionalProperties": false, "properties": { "remainingEnergyalue": { "type": "number", "description": "Energy in kWh (stored API compatibility key: remainingEnergyalue)", "minimum": 0 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "stateOfCertifiedEnergy": { "description": "Required only for battery_category=ev", "type": "object", "required": [ "stateOfCertifiedEnergyValue", "lastUpdate" ], "additionalProperties": false, "properties": { "stateOfCertifiedEnergyValue": { "type": "number", "description": "%", "minimum": 0, "maximum": 100 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "capacityThroughput": { "description": "Required only for battery_category=lmt or stationary", "type": "object", "required": [ "capacityThroughputValue", "lastUpdate" ], "additionalProperties": false, "properties": { "capacityThroughputValue": { "type": "number", "description": "Throughput in Ah", "minimum": 0 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "remainingPowerCapability": { "type": "array", "description": "Exactly 2 entries: atSoC 80 and atSoC 20. Power at 80% SoC must be ≥ power at 20% SoC. Required only for battery_category=lmt or stationary", "items": { "type": "object", "required": [ "remainingPowerCapabilityValue", "lastUpdate" ], "additionalProperties": false, "properties": { "remainingPowerCapabilityValue": { "type": "object", "required": [ "atSoC", "powerCapabilityAt", "rPCLastUpdated" ], "additionalProperties": false, "properties": { "atSoC": { "type": "number", "enum": [ 80, 20 ] }, "powerCapabilityAt": { "type": "number", "description": "Power in W (max 1 GW)", "minimum": 0, "maximum": 1000000000 }, "rPCLastUpdated": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "minItems": 2, "maxItems": 2 }, "remainingRoundTripEnergyEfficiency": { "description": "Required only for battery_category=lmt or stationary", "type": "object", "required": [ "remainingRoundTripEnergyEfficiencyValue", "lastUpdate" ], "additionalProperties": false, "properties": { "remainingRoundTripEnergyEfficiencyValue": { "type": "number", "description": "%", "minimum": 0, "maximum": 100 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "currentSelfDischargingRate": { "type": "object", "required": [ "currentSelfDischargingRateEntity", "lastUpdate" ], "additionalProperties": false, "properties": { "currentSelfDischargingRateEntity": { "type": "number", "description": "%", "minimum": 0 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "internalResistanceIncrease": { "description": "Required only for battery_category=lmt, ev, industrial or stationary", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "internalResistanceIncreaseValue": { "type": "number", "description": "%", "minimum": 0 }, "batteryComponent": { "type": "string", "enum": [ "pack", "module", "cell" ] }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } }, "required": [ "internalResistanceIncreaseValue", "batteryComponent", "lastUpdate" ] }, "maxItems": 200 }, "temperatureInformation": { "type": "object", "required": [ "timeExtremeHighTemp", "timeExtremeLowTemp", "timeExtremeHighTempCharging", "timeExtremeLowTempCharging", "lastUpdate" ], "additionalProperties": false, "description": "Charging time must not exceed total time for the same extreme. Required only for battery_category=lmt or stationary", "properties": { "timeExtremeHighTemp": { "type": "number", "description": "Hours above upper limit", "minimum": 0 }, "timeExtremeLowTemp": { "type": "number", "description": "Hours below lower limit", "minimum": 0 }, "timeExtremeHighTempCharging": { "type": "number", "description": "Of which while charging (hours)", "minimum": 0 }, "timeExtremeLowTempCharging": { "type": "number", "description": "Of which while charging (hours)", "minimum": 0 }, "lastUpdate": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "negativeEvents": { "type": "array", "description": "Recorded harmful incidents. Empty array [] = explicitly no incidents; omit field = not yet answered.", "items": { "type": "object", "required": [ "negativeEvent", "lastUpdate" ], "additionalProperties": false, "properties": { "negativeEvent": { "type": "string", "description": "Free-text description of incident", "minLength": 1 }, "lastUpdate": { "type": "string", "description": "Timestamp of incident", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "format": "date-time" } } }, "maxItems": 200 }, "powerFade": { "type": "number", "description": "Power capability loss since new in %", "minimum": 0, "maximum": 100 }, "energyThroughput": { "type": "number", "description": "Cumulative energy throughput in kWh. Required only for battery_category=lmt or stationary", "minimum": 0 }, "measuredOperatingTemperature": { "type": "number", "description": "Measured operating temperature in degrees Celsius. Required only for battery_category=lmt, ev, industrial or stationary", "minimum": -273 }, "numberOfDeepDischargeEvents": { "type": "number", "description": "Cumulative number of deep discharge events. Required only for battery_category=lmt or stationary", "minimum": 0 }, "roundTripEfficiencyat50PerCentCycleLife": { "type": "number", "description": "Round-trip efficiency at 50% cycle life in % (type test)", "minimum": 0, "maximum": 100 }, "roundTripEfficiencyFade": { "type": "number", "description": "Round-trip efficiency loss since new in %", "minimum": 0, "maximum": 100 }, "evolutionOfSelfDischarge": { "description": "Required only for battery_category=lmt or stationary", "type": "object", "required": [ "evolutionOfSelfDischargeEntityValue" ], "additionalProperties": false, "properties": { "evolutionOfSelfDischargeEntityValue": { "type": "number", "description": "%", "minimum": 0 } } }, "numberOfOverchargeEvents": { "type": "number", "description": "Cumulative number of overcharge events. Required only for battery_category=lmt or stationary", "minimum": 0 } } }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "street2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] } } }, "identifiers": { "type": "object", "properties": { "gln": { "type": [ "string", "null" ] }, "eori": { "type": [ "string", "null" ] } } }, "plan": { "type": "string" }, "public_profile": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "street2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "support_email": { "type": [ "string", "null" ] }, "contact_person": { "type": [ "string", "null" ] }, "spare_parts_email": { "type": [ "string", "null" ] }, "spare_parts_website": { "type": [ "string", "null" ] } } } } }, "Facility": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "street": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "gln": { "type": [ "string", "null" ] }, "street2": { "type": [ "string", "null" ] } } }, "AuditLogEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "description": "e.g. product.created, product.published, api_key.created" }, "resource_type": { "type": "string", "enum": [ "product", "api_key", "facility" ] }, "resource_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "actor_type": { "type": "string", "description": "e.g. api_key, user" }, "actor_id": { "type": "string", "description": "Key prefix or user ID" }, "metadata": { "type": "object", "description": "Additional context (name, serial_number, etc.)" } } }, "CreateMeta": { "type": "object", "description": "Optional metadata about auto-fill, warnings, and publish validation", "properties": { "auto_filled_from_org": { "type": "array", "items": { "type": "string" }, "description": "List of manufacturer fields auto-filled from organization profile" }, "auto_filled_labels": { "type": "array", "items": { "type": "string" }, "description": "List of label subjects auto-generated (e.g. SeparateCollection, ExtinguishingAgent)" }, "unrecognized_fields": { "type": "array", "items": { "type": "string" }, "description": "Fields sent in request that are not part of the schema" }, "field_warnings": { "type": "object", "description": "Warnings about specific fields (e.g. invalid GTIN check digit)" }, "publish_blocked": { "type": "object", "description": "Present when status=published but data is incomplete. Product saved as draft.", "properties": { "message": { "type": "string" }, "missing_org_fields": { "type": "array", "items": { "type": "string" } }, "incomplete_steps": { "type": "object", "description": "Per step: percent plus 'missing' (API field paths, e.g. manufacturer.name — use this) and 'missing_keys' (internal dashboard label keys)." } } } } }, "ValidationError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_error" }, "message": { "type": "string" }, "details": { "type": "object", "description": "Field → error messages mapping" }, "unrecognized_fields": { "type": "array", "items": { "type": "string" }, "description": "Fields not in schema (warning, not blocking)" } } } } }, "LightProductCreate": { "type": "object", "description": "Create payload for the class 'batteries_light' (battery models without passport, up to 2 kWh). Shares the base fields with ProductCreate but has no serial_number, no battery_category and no passport sections; the class-specific values live in the 'light' object. Publishing via API v1 is not supported yet: create as draft and publish in the dashboard.", "properties": { "light": { "type": [ "object", "null" ], "description": "Class-specific values of 'batteries_light'.", "properties": { "light_category": { "type": [ "string", "null" ], "description": "Battery type: portable, sli, industrial_below_2kwh", "enum": [ "portable", "sli", "industrial_below_2kwh", null ] }, "light_chemistry": { "type": [ "string", "null" ], "description": "Battery chemistry, e.g. alkaline or LFP", "enum": [ "NMC", "LFP", "NCA", "LCO", "LMO", "LTO", "NaIon", "Pb", "other", "NiMH", "NiCd", "LiMetal", "alkaline", null ] }, "light_non_rechargeable": { "type": [ "boolean", "null" ], "description": "true = non-rechargeable" }, "light_minimum_duration": { "type": [ "string", "null" ], "description": "Average minimum operating time per application (Art. 13(3))", "maxLength": 500 } } }, "materials": { "type": [ "object", "null" ], "description": "Class subset: material composition of the model.", "properties": { "batteryMaterials": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "batteryMaterialName" ], "properties": { "batteryMaterialName": { "type": "string" }, "batteryMaterialIdentifier": { "type": [ "string", "null" ], "description": "CAS number (e.g. 7439-93-2)" }, "batteryMaterialMass": { "type": [ "number", "null" ], "description": "Mass in kg", "exclusiveMinimum": 0 }, "batteryMaterialLocation": { "type": [ "object", "null" ], "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } }, "isCriticalRawMaterial": { "type": [ "boolean", "null" ] } } }, "maxItems": 200 } } }, "hazardous": { "type": [ "object", "null" ], "description": "Class subset: substances of concern.", "properties": { "contains": { "type": [ "boolean", "null" ] }, "hazardousSubstances": { "type": [ "array", "null" ], "description": "Required when contains = true", "items": { "type": "object", "required": [ "hazardousSubstanceName" ], "properties": { "hazardousSubstanceName": { "type": "string" }, "hazardousSubstanceIdentifier": { "type": [ "string", "null" ], "description": "CAS number" }, "hazardousSubstanceClass": { "type": [ "string", "null" ], "enum": [ "AcuteToxicity", "SkinCorrosionOrIrritation", "EyeDamageOrIrritation", null ] }, "hazardousSubstanceConcentration": { "type": [ "number", "null" ], "description": "Concentration in %", "maximum": 100, "exclusiveMinimum": 0 }, "hazardousSubstanceImpact": { "type": "array", "items": { "type": "string" }, "description": "Impact statements on human health and environment" }, "hazardousSubstanceLocation": { "type": [ "object", "null" ], "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } } } }, "maxItems": 200 } } }, "performance": { "type": [ "object", "null" ], "description": "Class subset: rated capacity and energy.", "properties": { "ratedCapacity": { "type": [ "number", "null" ], "description": "Ah", "minimum": 0 }, "ratedEnergy": { "type": [ "number", "null" ], "description": "Wh", "minimum": 0 } } }, "circularity": { "type": [ "object", "null" ], "description": "Class subset: safety and end-of-life information.", "properties": { "safetyMeasures": { "type": [ "object", "null" ], "properties": { "safetyInstructions": { "type": [ "string", "null" ] }, "extinguishingAgent": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "A", "B", "C", "D", "K" ] }, "maxItems": 200 } } }, "endOfLifeInformation": { "type": [ "object", "null" ], "properties": { "wastePrevention": { "type": [ "string", "null" ] }, "separateCollection": { "type": [ "string", "null" ] }, "informationOnCollection": { "type": [ "string", "null" ] } } } } }, "labeling": { "type": [ "object", "null" ], "description": "Class subset: declaration of conformity and labels.", "properties": { "declarationOfConformity": { "type": [ "string", "null" ], "description": "URL to EU declaration of conformity" }, "labels": { "type": [ "array", "null" ], "description": "Auto-filled with default symbols when empty on POST", "items": { "type": "object", "required": [ "labelingSubject" ], "properties": { "labelingSubject": { "type": "string", "enum": [ "SeparateCollection", "HazardousMaterial", "CarbonFootPrint", "ExtinguishingAgent" ] }, "labelingSymbol": { "type": [ "string", "null" ], "description": "URL to symbol SVG" }, "carbonFootprintClass": { "type": [ "string", "null" ], "description": "Required for CarbonFootPrint subject" }, "labelingMeaning": { "type": [ "object", "null" ], "required": [ "de", "en" ], "properties": { "de": { "type": "string" }, "en": { "type": "string" } } }, "labelingSymbolFileName": { "type": [ "string", "null" ], "description": "Filename of the symbol SVG" }, "ghsPictogram": { "type": [ "string", "null" ], "description": "GHS pictogram type (only for HazardousMaterial)", "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental", null ] } } }, "maxItems": 200 } } }, "due_diligence": { "type": [ "object", "null" ], "description": "Class subset: due diligence report.", "properties": { "dueDiligenceReport": { "type": [ "string", "null" ] } } }, "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "published" ], "default": "draft" }, "category": { "type": "string", "const": "batteries_light", "enum": [ "batteries_light" ] }, "sku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "type": [ "string", "null" ], "maxLength": 100 }, "gtin": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, "manufacturing_date": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$" }, "battery_mass": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, { "type": "null" } ], "type": [ "number", "null" ], "maximum": 100000, "exclusiveMinimum": 0 }, "facility_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "format": "uuid" }, "mfr_name": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_identifier": { "anyOf": [ { "type": "string", "pattern": "^$|^(?:GLN:\\d{13}|EORI:[A-Za-z]{2}[A-Za-z0-9]{8,15})$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^$|^(?:GLN:\\d{13}|EORI:[A-Za-z]{2}[A-Za-z0-9]{8,15})$" }, "mfr_street": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "type": [ "string", "null" ] }, "mfr_postal_code": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_city": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "mfr_email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "format": "email" }, "mfr_website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "type": [ "string", "null" ] } }, "required": [ "name", "category" ] }, "LightProductUpdate": { "type": "object", "description": "Partial update payload for the class 'batteries_light'. Same fields as LightProductCreate (all optional, category cannot be changed).", "properties": { "light": { "type": [ "object", "null" ], "description": "Class-specific values of 'batteries_light'.", "properties": { "light_category": { "type": [ "string", "null" ], "description": "Battery type: portable, sli, industrial_below_2kwh", "enum": [ "portable", "sli", "industrial_below_2kwh", null ] }, "light_chemistry": { "type": [ "string", "null" ], "description": "Battery chemistry, e.g. alkaline or LFP", "enum": [ "NMC", "LFP", "NCA", "LCO", "LMO", "LTO", "NaIon", "Pb", "other", "NiMH", "NiCd", "LiMetal", "alkaline", null ] }, "light_non_rechargeable": { "type": [ "boolean", "null" ], "description": "true = non-rechargeable" }, "light_minimum_duration": { "type": [ "string", "null" ], "description": "Average minimum operating time per application (Art. 13(3))", "maxLength": 500 } } }, "materials": { "type": [ "object", "null" ], "description": "Class subset: material composition of the model.", "properties": { "batteryMaterials": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "batteryMaterialName" ], "properties": { "batteryMaterialName": { "type": "string" }, "batteryMaterialIdentifier": { "type": [ "string", "null" ], "description": "CAS number (e.g. 7439-93-2)" }, "batteryMaterialMass": { "type": [ "number", "null" ], "description": "Mass in kg", "exclusiveMinimum": 0 }, "batteryMaterialLocation": { "type": [ "object", "null" ], "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } }, "isCriticalRawMaterial": { "type": [ "boolean", "null" ] } } }, "maxItems": 200 } } }, "hazardous": { "type": [ "object", "null" ], "description": "Class subset: substances of concern.", "properties": { "contains": { "type": [ "boolean", "null" ] }, "hazardousSubstances": { "type": [ "array", "null" ], "description": "Required when contains = true", "items": { "type": "object", "required": [ "hazardousSubstanceName" ], "properties": { "hazardousSubstanceName": { "type": "string" }, "hazardousSubstanceIdentifier": { "type": [ "string", "null" ], "description": "CAS number" }, "hazardousSubstanceClass": { "type": [ "string", "null" ], "enum": [ "AcuteToxicity", "SkinCorrosionOrIrritation", "EyeDamageOrIrritation", null ] }, "hazardousSubstanceConcentration": { "type": [ "number", "null" ], "description": "Concentration in %", "maximum": 100, "exclusiveMinimum": 0 }, "hazardousSubstanceImpact": { "type": "array", "items": { "type": "string" }, "description": "Impact statements on human health and environment" }, "hazardousSubstanceLocation": { "type": [ "object", "null" ], "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } } } }, "maxItems": 200 } } }, "performance": { "type": [ "object", "null" ], "description": "Class subset: rated capacity and energy.", "properties": { "ratedCapacity": { "type": [ "number", "null" ], "description": "Ah", "minimum": 0 }, "ratedEnergy": { "type": [ "number", "null" ], "description": "Wh", "minimum": 0 } } }, "circularity": { "type": [ "object", "null" ], "description": "Class subset: safety and end-of-life information.", "properties": { "safetyMeasures": { "type": [ "object", "null" ], "properties": { "safetyInstructions": { "type": [ "string", "null" ] }, "extinguishingAgent": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "A", "B", "C", "D", "K" ] }, "maxItems": 200 } } }, "endOfLifeInformation": { "type": [ "object", "null" ], "properties": { "wastePrevention": { "type": [ "string", "null" ] }, "separateCollection": { "type": [ "string", "null" ] }, "informationOnCollection": { "type": [ "string", "null" ] } } } } }, "labeling": { "type": [ "object", "null" ], "description": "Class subset: declaration of conformity and labels.", "properties": { "declarationOfConformity": { "type": [ "string", "null" ], "description": "URL to EU declaration of conformity" }, "labels": { "type": [ "array", "null" ], "description": "Auto-filled with default symbols when empty on POST", "items": { "type": "object", "required": [ "labelingSubject" ], "properties": { "labelingSubject": { "type": "string", "enum": [ "SeparateCollection", "HazardousMaterial", "CarbonFootPrint", "ExtinguishingAgent" ] }, "labelingSymbol": { "type": [ "string", "null" ], "description": "URL to symbol SVG" }, "carbonFootprintClass": { "type": [ "string", "null" ], "description": "Required for CarbonFootPrint subject" }, "labelingMeaning": { "type": [ "object", "null" ], "required": [ "de", "en" ], "properties": { "de": { "type": "string" }, "en": { "type": "string" } } }, "labelingSymbolFileName": { "type": [ "string", "null" ], "description": "Filename of the symbol SVG" }, "ghsPictogram": { "type": [ "string", "null" ], "description": "GHS pictogram type (only for HazardousMaterial)", "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental", null ] } } }, "maxItems": 200 } } }, "due_diligence": { "type": [ "object", "null" ], "description": "Class subset: due diligence report.", "properties": { "dueDiligenceReport": { "type": [ "string", "null" ] } } }, "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "published" ], "default": "draft" }, "sku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "type": [ "string", "null" ], "maxLength": 100 }, "gtin": { "anyOf": [ { "type": "string", "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$" }, "manufacturing_date": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$" }, "battery_mass": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, { "type": "null" } ], "type": [ "number", "null" ], "maximum": 100000, "exclusiveMinimum": 0 }, "facility_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "format": "uuid" }, "mfr_name": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_identifier": { "anyOf": [ { "type": "string", "pattern": "^$|^(?:GLN:\\d{13}|EORI:[A-Za-z]{2}[A-Za-z0-9]{8,15})$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^$|^(?:GLN:\\d{13}|EORI:[A-Za-z]{2}[A-Za-z0-9]{8,15})$" }, "mfr_street": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "type": [ "string", "null" ] }, "mfr_postal_code": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_city": { "anyOf": [ { "type": "string", "minLength": 3 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 3 }, "mfr_country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "mfr_email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ], "type": [ "string", "null" ], "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "format": "email" }, "mfr_website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "type": [ "string", "null" ] } } }, "LightProduct": { "type": "object", "description": "Response shape of the class 'batteries_light': only the class fields, no passport sections.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "batteries_light" ] }, "manufacturing_date": { "type": [ "string", "null" ] }, "battery_mass": { "type": [ "number", "null" ], "description": "Battery mass in kg" }, "gtin": { "type": [ "string", "null" ] }, "public_url": { "type": [ "string", "null" ], "description": "Public model page (set once the model is published)" }, "image_url": { "type": [ "string", "null" ] }, "facility_id": { "type": [ "string", "null" ] }, "manufacturer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "identifier": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "street2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } }, "light": { "type": [ "object", "null" ], "description": "Class-specific values (light_category, light_chemistry, light_non_rechargeable, light_minimum_duration)", "properties": { "light_category": { "type": [ "string", "null" ], "description": "Battery type: portable, sli, industrial_below_2kwh", "enum": [ "portable", "sli", "industrial_below_2kwh" ] }, "light_chemistry": { "type": [ "string", "null" ], "description": "Battery chemistry, e.g. alkaline or LFP", "enum": [ "NMC", "LFP", "NCA", "LCO", "LMO", "LTO", "NaIon", "Pb", "other", "NiMH", "NiCd", "LiMetal", "alkaline" ] }, "light_non_rechargeable": { "type": [ "boolean", "null" ], "description": "true = non-rechargeable" }, "light_minimum_duration": { "type": [ "string", "null" ], "description": "Average minimum operating time per application (Art. 13(3))", "maxLength": 500 } } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "materials": { "type": [ "object", "null" ], "description": "Class subset: material composition of the model.", "properties": { "batteryMaterials": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "batteryMaterialName", "batteryMaterialIdentifier", "batteryMaterialMass", "batteryMaterialLocation", "isCriticalRawMaterial" ], "properties": { "batteryMaterialName": { "type": "string" }, "batteryMaterialIdentifier": { "type": "string", "description": "CAS number (e.g. 7439-93-2)" }, "batteryMaterialMass": { "type": "number", "minimum": 0, "description": "Mass in kg" }, "batteryMaterialLocation": { "type": "object", "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } }, "isCriticalRawMaterial": { "type": "boolean" } } } } } }, "hazardous": { "type": [ "object", "null" ], "description": "Class subset: substances of concern.", "properties": { "contains": { "type": "boolean" }, "hazardousSubstances": { "type": "array", "description": "Required when contains = true", "items": { "type": "object", "required": [ "hazardousSubstanceName", "hazardousSubstanceIdentifier", "hazardousSubstanceClass", "hazardousSubstanceConcentration", "hazardousSubstanceImpact", "hazardousSubstanceLocation" ], "properties": { "hazardousSubstanceName": { "type": "string" }, "hazardousSubstanceIdentifier": { "type": "string", "description": "CAS number" }, "hazardousSubstanceClass": { "type": "string", "enum": [ "AcuteToxicity", "SkinCorrosionOrIrritation", "EyeDamageOrIrritation" ] }, "hazardousSubstanceConcentration": { "type": "number", "minimum": 0, "description": "Concentration in %" }, "hazardousSubstanceImpact": { "type": "array", "items": { "type": "string" }, "description": "Impact statements on human health and environment" }, "hazardousSubstanceLocation": { "type": "object", "required": [ "componentName" ], "properties": { "componentName": { "type": "string" } } } } } } } }, "performance": { "type": [ "object", "null" ], "description": "Class subset: rated capacity and energy.", "properties": { "ratedCapacity": { "type": "number", "minimum": 0, "description": "Ah" }, "ratedEnergy": { "type": "number", "minimum": 0, "description": "Wh" } } }, "circularity": { "type": [ "object", "null" ], "description": "Class subset: safety and end-of-life information.", "properties": { "safetyMeasures": { "type": "object", "required": [ "safetyInstructions", "extinguishingAgent" ], "properties": { "safetyInstructions": { "type": "string", "format": "uri" }, "extinguishingAgent": { "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "K" ] } } } }, "endOfLifeInformation": { "type": "object", "required": [ "wastePrevention", "separateCollection", "informationOnCollection" ], "properties": { "wastePrevention": { "type": "string", "format": "uri" }, "separateCollection": { "type": "string", "format": "uri" }, "informationOnCollection": { "type": "string", "format": "uri" } } } } }, "labeling": { "type": [ "object", "null" ], "description": "Class subset: declaration of conformity and labels.", "properties": { "declarationOfConformity": { "type": [ "string", "null" ], "format": "uri", "description": "URL to EU declaration of conformity" }, "labels": { "type": "array", "description": "Auto-filled with default symbols when empty on POST", "items": { "type": "object", "required": [ "labelingSubject", "labelingSymbol", "labelingMeaning" ], "properties": { "labelingSubject": { "type": "string", "enum": [ "SeparateCollection", "HazardousMaterial", "CarbonFootPrint", "ExtinguishingAgent" ] }, "labelingSymbol": { "type": "string", "format": "uri", "description": "URL to symbol SVG" }, "carbonFootprintClass": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Required for CarbonFootPrint subject" }, "labelingMeaning": { "type": "object", "required": [ "de", "en" ], "properties": { "de": { "type": "string" }, "en": { "type": "string" } } }, "labelingSymbolFileName": { "type": [ "string", "null" ], "description": "Filename of the symbol SVG" }, "ghsPictogram": { "type": [ "string", "null" ], "description": "GHS pictogram type (only for HazardousMaterial)", "enum": [ "explosive", "flammable", "oxidising", "gas_under_pressure", "corrosive", "acute_toxicity", "irritant", "health_hazard", "environmental", null ] } } } } } }, "due_diligence": { "type": [ "object", "null" ], "description": "Class subset: due diligence report.", "properties": { "dueDiligenceReport": { "type": "string", "format": "uri" } } } } } } }, "tags": [ { "name": "Products", "description": "CRUD operations for battery products" }, { "name": "Battery Condition", "description": "Dynamic BMS/condition data (separate from static product data)" }, { "name": "Export", "description": "DIN SPEC 99100 JSON, PDF, and QR code exports" }, { "name": "Organization", "description": "Organization profile, facilities, and audit log" } ], "x-en18222": { "statement": "Aligned with the methods and REST conventions of EN 18222:2026; a complete conformity assessment including dependent standards is still open. This is a vendor self-statement, not a certification.", "implemented": { "ReadDPPById": "GET /dpps/{dppId} (shall-level facade over the validated Battery Passport v2.0 build core)", "ReadDPPByProductId": "GET /dppsByProductId/{productId} (shall; productId convention: \":\", a documented DPP Hero decision)", "ReadDPPIdsByProductIds": "POST /dppsByProductIds (shall; pagination via limit/cursor query parameters and Link rel=\"next\", a documented DPP Hero decision)", "ReadDPPVersionByIdAndDate": "GET /dpps/{dppId}?date=... (should; versions recorded from 2026-07-23 onward)", "UpdateDPPById_CreateDPP_DeleteDPPById": "covered by the existing /products endpoints (PATCH/POST/DELETE) instead of separate norm paths, a documented DPP Hero decision", "errorModel": "error.correlation_id in every error body plus X-Correlation-Id header" }, "deferred": { "ReadDataElement_UpdateDataElement": "should-level element API deferred: EN 18223:2026 contains no machine-readable schema (its clause on missing schemas) and the EU semantic repository does not yet expose a battery data model; revisit when available", "RegisterProductDPP": "duty of the EU registry, client integration follows once battery registration opens" } } }