Traceability

Traceability in the ConformaESG API comes in two flavors that solve different problems:

Product traceability (full journey)

A product traceability describes the complete path a company product follows, from raw material to finished good. It is composed of:

• A header record with traceabilityName, productId, optional pfcrCalculationId (link to a product footprint calculation), and aggregated totalCo2PerKg / totalDistanceKm.
• An ordered list of processing stages — each captures one link in the chain.

Processing stages

Each stage (ProcessingStageDto) has:

• sequenceOrder — position in the chain (1, 2, 3…).
• stageName — e.g. Spinning, Weaving, Dyeing, Shipping.
• companyType — SUPPLIER or COMPANY, identifying whether the stage is handled by an external supplier or by you.
• supplierId / companyId — the party performing the stage (set according to companyType).
• internalProcess — free-form description of what happens at this stage.
• transportMode — TRUCK, SHIP, TRAIN or PLANE, used to estimate emissions.
• startsFromCompany — true if this stage's transport leg originates from your company.
• distanceKm — distance to the next stage.
• co2Emissions — CO₂ for this stage's transport leg (kg CO₂eq).
• certificationsSnapshot — free-form capture of the certifications that applied at this stage.

Managing stages

You manage the journey in two steps:

1. Create the header: POST /api/v1/product/traceability with productId and traceabilityName.
2. Append stages: POST /api/v1/product/traceability/{id}/stages — one call per stage.

Individual stages can later be updated via PATCH /api/v1/product/traceability/stages/{stageId} and removed via DELETE …/stages/{stageId}. Removing a stage recomputes the aggregated totalCo2PerKg and totalDistanceKm on the parent journey.

Deleting the traceability header cascades to all its stages.

Reading the full journey

GET /api/v1/product/traceability/{id} returns the header together with all processing stages, sorted by sequenceOrder. Perfect for rendering a timeline or an exportable report.

Traceability records (batch level)

A traceability record is a lighter-weight entity that captures a single batch shipment. It does not model processing stages; instead it answers the question: "Where does this batch come from, and is it compliant?"

Fields:

• productId — free-form product identifier (string, not a UUID — this allows integrating batches against legacy product IDs).
• batchNumber — your batch reference.
• origin (required), destination, supplierId, processingFacility.
• certifications — free-form string listing relevant certifications.
• isCompliant — boolean flag you set when the batch passes your QA.
• notes, metadata — anything else you need.

Use traceability records when:

• You need a per-batch audit trail without modeling the full product journey.
• You want to document the origin of a one-off shipment.
• You are building scan-and-log tooling for warehouse operators.

Which one should I use?

• You want lifecycle emissions, stages, distances, CO₂ → Product traceability.
• You want a single certified provenance record per batch → Traceability records.

Both models can coexist in the same tenant; they are not mutually exclusive.

Related reading

• Product traceability API →
• Traceability records API →
• Example: Product traceability journey →