Traceability Records
| Method | Path | Description |
|---|---|---|
GET | /api/v1/traceability | List traceability records (paginated) |
GET | /api/v1/traceability/{id} | Get a traceability record by ID |
GET | /api/v1/traceability/product/{productId} | Find records by product ID |
GET | /api/v1/traceability/batch/{batchNumber} | Find records by batch number |
POST | /api/v1/traceability | Create a traceability record |
PATCH | /api/v1/traceability/{id} | Update a traceability record |
DELETE | /api/v1/traceability/{id} | Delete a traceability record |
GET /api/v1/traceability
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 0 | Zero-based page index |
size | integer | 20 | Items per page |
productId | string | — | Filter by product ID |
batchNumber | string | — | Filter by batch number |
Shell
curl "http://localhost:8080/api/v1/traceability?productId=3&page=0&size=10"
POST /api/v1/traceability
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | ❌ | Associated product ID |
batch_number | string | ❌ | Batch number |
origin | string | ❌ | Origin location |
destination | string | ❌ | Destination location |
supplier_id | integer | ❌ | FK to Supplier.id |
processing_facility | string | ❌ | Name of processing facility |
certifications | string | ❌ | Certifications held |
is_compliant | boolean | ❌ | Compliance flag |
notes | string | ❌ | Notes |
metadata | object | ❌ | Arbitrary JSON key-value pairs |
Shell
curl -X POST "http://localhost:8080/api/v1/traceability?userId=1" \-H "Content-Type: application/json" \-d '{"product_id": "3","batch_number": "BATCH-2025-001","origin": "Mumbai, India","destination": "Milano, Italy","supplier_id": 1,"is_compliant": true}'
JavaScript
const resp = await fetch('/api/v1/traceability?userId=1', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({product_id: '3',batch_number: 'BATCH-2025-001',origin: 'Mumbai, India',destination: 'Milano, Italy',supplier_id: 1,is_compliant: true})});
Processing Stages
Processing stages are managed under the ProductTraceability aggregate. The base path is /api/v1/product/traceability.
| Method | Path | Description |
|---|---|---|
POST | /api/v1/product/traceability/{traceability_id}/stages | Create a processing stage |
PATCH | /api/v1/product/traceability/stages/{id} | Update a processing stage |
GET | /api/v1/product/traceability/{traceability_id}/stages | List stages for a traceability record |
DELETE | /api/v1/product/traceability/stages/{id} | Delete a processing stage |
POST | /api/v1/product/traceability/{traceability_id}/stages/bulk | Bulk upsert stages |
POST /api/v1/product/traceability/{traceability_id}/stages
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
sequence_order | integer | ✅ | Position in the processing chain |
stage_name | string | ✅ | e.g. Spinning, Dyeing, Cutting |
company_type | string | ❌ | Type of company performing the stage |
supplier_id | integer | ❌ | Supplier performing this stage |
company_id | integer | ❌ | Company performing this stage |
internal_process | boolean | ❌ | Whether this is an internal process |
transport_mode | string | ❌ | Transport mode to this stage |
starts_from_company | boolean | ❌ | Whether transport starts from company |
distance_km | number | ❌ | Transport distance from previous stage |
co2_emissions | number | ❌ | CO₂ emissions for this stage |
certifications_snapshot | string | ❌ | Certifications at this stage |
Shell
curl -X POST http://localhost:8080/api/v1/product/traceability/10/stages \-H "Content-Type: application/json" \-d '{"sequence_order": 1,"stage_name": "Spinning","supplier_id": 5,"distance_km": 0,"co2_emissions": 0}'
POST /api/v1/product/traceability/{traceability_id}/stages/bulk
Creates or updates multiple stages in one request. After bulk insert, the parent ProductTraceability.total_distance_km and total_co2_per_kg are automatically recalculated.
JSON
{"stages": [{"sequence_order": 1,"stage_name": "Spinning","supplier_id": 5,"distance_km": 0,"co2_emissions": 0},{"sequence_order": 2,"stage_name": "Dyeing","supplier_id": 8,"transport_mode": "ROAD","distance_km": 2200,"co2_emissions": 0.18},{"sequence_order": 3,"stage_name": "Cutting","supplier_id": 12,"transport_mode": "SEA","distance_km": 8500,"co2_emissions": 0.42}]}
Response 200 OK
JSON
{"created": 2,"updated": 1,"failed": 0,"errors": []}
Note
After any stage is created, updated, or deleted, the parent ProductTraceability record's total_distance_km and total_co2_per_kg fields are automatically recalculated by summing all child stages.