EU Battery Passport API Documentation

🔐 Authentication Routes (/api/auth)

POST /api/auth/set-role

Set or update the role for an authenticated user

Requires Authentication

Request Body:

{ "role": "manufacturer" | "owner" | "repurposer" | "recycler" | "authority" | "admin" }

Response: { success: true, message: "Role set successfully" }

POST /api/auth/choose-role

Allow user to choose from available roles during onboarding

Requires Authentication

Response: Returns available roles and current selection

🌐 Public Routes (/api/public)

No authentication required. Public information about batteries, models, and companies.

GET /api/public/passport/:id

Get public battery passport information

Returns battery details including technical specs, compliance info, and environmental data without owner-specific data

GET /api/public/models/:companyId

List all models from a company visible to the public

Returns model specifications, carbon performance class, and durability compliance status

GET /api/public/batteries

List all publicly available batteries

Supports filtering by category, compliance status, and search parameters

📏 Compliance Routes (/api/compliance)

Public read access to regulatory thresholds; admin-only for mutations per EU Regulation 2023/1542 (Articles 7 and 10).

GET /api/compliance/durability-thresholds

List durability thresholds (public). Supports optional filters: battery_category, valid_from, valid_to.

GET /api/compliance/carbon-thresholds

List carbon performance thresholds (public). Supports optional filters: battery_category, valid_from, valid_to.

POST /api/compliance/durability-thresholds

Create durability threshold (admin)

Requires Authentication

Admin only

POST /api/compliance/carbon-thresholds

Create carbon threshold (admin)

Requires Authentication

Admin only

PUT /api/compliance/durability-thresholds/:id

Update durability threshold (admin)

Requires Authentication

Admin only

PUT /api/compliance/carbon-thresholds/:id

Update carbon threshold (admin)

Requires Authentication

Admin only

DELETE /api/compliance/durability-thresholds/:id

Soft delete durability threshold (admin)

Requires Authentication

Admin only

DELETE /api/compliance/carbon-thresholds/:id

Soft delete carbon threshold (admin)

Requires Authentication

Admin only

🏢 Company Routes (/api/companies)

Manage companies, dashboards, and thresholds

GET /api/companies

List all companies

POST /api/companies

Create a new company

Requires Authentication

Admin only

GET /api/companies/dashboard

Get comprehensive dashboard data for authenticated company

Requires Authentication

"Fat endpoint" providing aggregated company data: models, batches, batteries, and compliance information in a single request

GET /api/companies/company

Get current authenticated user's company details

Requires Authentication

PUT /api/companies/company/:id

Update company information

Requires Authentication

Company owner or admin

GET /api/companies/:id

Get company details by ID

GET /api/companies/:companyId/durability-thresholds

Get durability compliance thresholds for a company

Returns active thresholds where valid_from ≤ today ≤ valid_to

GET /api/companies/:companyId/carbon-thresholds

Get carbon footprint thresholds for a company

Returns active thresholds where valid_from ≤ today ≤ valid_to

POST /api/companies/:companyId/durability-thresholds

Create new durability threshold (EU Regulation 2023/1542)

Requires Authentication

Admin only

POST /api/companies/:companyId/carbon-thresholds

Create new carbon footprint threshold

Requires Authentication

Admin only

DELETE /api/companies/:id

Delete a company

Requires Authentication

Admin only

👨‍💼 Admin Routes (/api/admin)

Administrative operations for system management

All endpoints require authentication and admin role

Manage users, roles, and system-wide settings. Company-level user management will be implemented at /api/companies/:id/users for company admins.

🏭 Plant Routes (/api/plants)

Manage manufacturing plants

GET /api/plants/:companyId

List plants for a company

GET /api/plants/:id

Get plant details

POST /api/plants

Create new plant

Requires Authentication

Manufacturer or admin

Fields

Field	Type	Required	Description	Compliance
global_location_number	string	No	Global Location Number (GLN), 13-digit identifier. Validated by regex `^\d{13}$`.	EU Regulation 2023/1542 Article 13; Catena-X 6.0.0 Identification.Plant

Naming consistency: API uses global_location_number. Database column gln maps to this field in API responses and internal services.

🔧 Model Routes (/api/models)

Manage battery models and technical specifications

GET /api/models

List all models with optional filtering

Returns model specifications, durability compliance, and carbon performance class

GET /api/models/:id

Get detailed model information

Includes technical specifications, compliance data, and associated batches

POST /api/models

Create new battery model

Requires Authentication

Manufacturer or admin

Includes specifications, chemistry, and EU Annex VI compliance data

📦 Batch Routes (/api/batches)

Manage production batches and batch-specific data

GET /api/batches

List production batches

Includes inherited model properties: durability compliance, carbon performance class

GET /api/batches/:id

Get batch details

Shows batch specifications and inherited model compliance data

POST /api/batches

Create new production batch

Requires Authentication

Manufacturer or admin

🔋 Battery Routes (/api/batteries)

Consolidated endpoint for all battery operations following resource-based REST architecture

GET /api/batteries

List batteries with RBAC-filtered sections

Returns different data based on user role (manufacturer, recycler, repurposer, owner, authority)

GET /api/batteries/:id

Get detailed battery information

Includes technical specs, compliance status, lifecycle history, usage data, and environmental impact

GET /api/batteries/:id/json-ld

Get battery data in JSON-LD format

Structured data for semantic web and interoperability (EU Battery Regulation Annex VI)

GET /api/batteries/owned

List batteries owned by current user/company

Requires Authentication

GET /api/batteries/manufactured

List batteries manufactured by current company

Requires Authentication

Manufacturer or admin

GET /api/batteries/repurposed

List batteries repurposed using models from this company

Requires Authentication

Repurposer or admin

POST /api/batteries

Create new battery

Requires Authentication

Manufacturer or admin

POST /api/batteries/complete

Create complete battery hierarchy in one transaction

Requires Authentication

Manufacturer or admin

Creates company (optional), plant, model, batch, battery, and technical documents with Firestore/Storage rollback on failure

PATCH /api/batteries/:id/recycle

Mark battery as recycled (Article 13 - Lifecycle)

Requires Authentication

Recycler, authority, or admin

Updates lifecycle status to "recycled" and records recovered materials

PATCH /api/batteries/:id/repurpose

Mark battery for repurposing (Article 13 - Lifecycle)

Requires Authentication

Repurposer or admin

PATCH /api/batteries/:id/soh

Update battery state of health (SoH) and residual lifetime

Requires Authentication

BMS devices and owners can report usage data; calculates remaining useful life

⚗️ Materials Routes (/api/materials)

Manage battery composition and material information

GET /api/materials

Get available materials and units

Returns standardized materials for composition data (EU Annex VI)

📄 Technical Documents Routes (/api/tech-docs)

Manage technical documentation for models

GET /api/tech-docs/:modelId

Get technical documents for a model

Returns Firestore references, QR codes, and document metadata

POST /api/tech-docs/:modelId

Upload/save technical documents

Requires Authentication

Manufacturer or admin

🛒 Marketplace Routes (/api/marketplace)

Battery marketplace for buying and selling used batteries

GET /api/marketplace

List batteries available for sale on marketplace

Public listing with filtering by category, condition, price

POST /api/marketplace/list

List battery for sale

Requires Authentication

Owner or admin

POST /api/marketplace/purchase

Purchase battery from marketplace

Requires Authentication

Transfers ownership and updates lifecycle history

✅ Compliance Features

Phase 1 Complete: Backend-calculated compliance values displayed without frontend validation

durability_compliant: Boolean from backend (compliant with EU Regulation 2023/1542 Article 10)
carbon_performance_class: Class A-G from backend calculations (Article 7)
carbon_class: Carbon footprint classification on batteries
All values displayed in EntityTable, PublicBatteryPassportOrganism, and EntityDetailPage
No frontend validation triggered during render

Durability Compliance (Article 10)

Backend service calculates durability_compliant based on:

Round-trip efficiency ≥ threshold for battery category
Capacity fade < threshold per 1000 cycles
Thresholds vary by category (EV, LMT, SLI, industrial, portable, incorporated)
Active thresholds returned via GET /api/companies/:id/durability-thresholds

Carbon Performance Class (Article 7)

Backend calculates carbon_performance_class (A-G) based on:

Carbon intensity (kg CO₂eq/kWh) vs. class boundaries
Weighted average across production batches
Thresholds vary by category and year
Active thresholds returned via GET /api/companies/:id/carbon-thresholds

⚠️ Error Handling

Status Code	Meaning	Example
200 OK	Request successful	GET /api/batteries/123 returns battery details
400 Bad Request	Invalid request data	Missing required field in POST request
401 Unauthorized	Missing or invalid authentication	Missing Bearer token or expired JWT
403 Forbidden	Authenticated but insufficient permissions	Non-admin attempting to create company
404 Not Found	Resource does not exist	GET /api/batteries/nonexistent
500 Internal Server Error	Server-side error	Database connection failure

🔒 Authentication & Authorization

Firebase JWT Authentication

All protected endpoints require a valid Firebase JWT token in the request header:

Authorization: Bearer <firebase_id_token>

Available Roles

Role	Permissions
manufacturer	Create/edit models, batches, batteries; view manufacturing data
owner	View owned batteries; update usage data; manage ownership transfer
repurposer	Access technical docs; update lifecycle to "repurposed"; view composition data
recycler	Access composition data; update lifecycle to "recycled"; record recovered materials
authority	Read-only access to all data for regulatory compliance audits
admin	Unrestricted access to all endpoints and management functions
public	Access public endpoints (no authentication required)
bms_device	Write usage data for assigned battery; read battery specs

📊 Data Flow Architecture

Firestore & PostgreSQL Integration

Entities stored in both databases for audit and user management:

Firestore: User authentication, technical documents, usage data
PostgreSQL: Relational data, audit trails, compliance calculations
Firebase Storage: Binary files (QR codes, technical docs, usage logs)

SQL vs. Firestore ID References

When both sqlId and firestoreUid exist:

// SQL-generated UUID has precedence for audit purposes sqlId: "550e8400-e29b-41d4-a716-446655440000" firestoreUid: "firebase-uid-12345" // Query uses sqlId in WHERE clauses SELECT * FROM batteries WHERE sql_id = sqlId

📞 Support & Documentation

Backend Repository: BackEnd/ directory
Route Files: BackEnd/routes/
Services: BackEnd/services/
Database: BackEnd/database_schema.sql
Compliance Details: BackEnd/services/complianceService.js

Version: Phase 1 (Backend compliance display)
Last Updated: January 2026
EU Compliance: Regulation 2023/1542, Directive 2024/1861 (NIS2)