Overview
The chemical module manages chemical products, their compliance status, associated suppliers, and purchase records. It supports REACH, ZDHC, GOTS, GRS, and PFAS tracking with full CAS number search capabilities.
Entities
ChemicalProduct
| Field | Type | Description |
|---|---|---|
id | Long | Auto PK |
chemicalName | String | Chemical name (required) |
commercialName | String | Commercial/trade name |
internalCode | String | Internal product code |
casNumbers | List<String> | CAS Registry Numbers (element collection) |
ecNumber | String | EC number |
chemicalFormula | String | Chemical formula |
chemicalCategory | String | Category |
subcategory | String | Subcategory |
userId | Long | Creator user ID |
companyId | Long | Company ID |
archived | Boolean | Soft-delete flag |
archivedAt | LocalDateTime | When archived |
metadata | Map<String, Object> | Custom JSON metadata |
compliance | ChemicalCompliance | Compliance data (@OneToOne) |
supplier | ChemicalSupplier | Supplier data (@OneToOne) |
purchaseRecords | List<ChemicalPurchaseRecord> | Purchase history (@OneToMany) |
createdAt / updatedAt | LocalDateTime | Timestamps |
ChemicalCompliance
Each chemical product has a one-to-one compliance record tracking regulatory status:
| Field | Type | Description |
|---|---|---|
reachCompliant | Boolean | REACH regulation compliant |
reachRegistrationNumber | String | REACH registration number |
zdhcLevel | ZdhcLevel | ZDHC MRSL conformance level |
zdhcGatewayId | String | ZDHC Gateway identifier |
gotsCompliant | Boolean | GOTS compliant |
grsCompliant | Boolean | GRS compliant |
svhcSubstance | Boolean | Is SVHC substance |
pfasContent | Boolean | Contains PFAS |
ChemicalSupplier
Supplier information specific to the chemical product:
| Field | Type | Description |
|---|---|---|
supplierName | String | Chemical supplier name |
supplierCode | String | Supplier code |
contactEmail | String | Contact email |
country | String | Supplier country |
ChemicalPurchaseRecord
Purchase records for chemical products. See Chemical Purchases API → for the full API reference.
| Field | Type | Description |
|---|---|---|
chemicalProductId | Long | FK to ChemicalProduct |
supplierId | Long | FK to supplier |
companyId | Long | Company ID |
purchaseDate | LocalDateTime | Purchase datetime |
quantityKg | Double | Quantity in kg |
costPerKg | BigDecimal | Cost per kg |
totalCost | BigDecimal | Total cost |
currency | String | ISO 4217 (3 letters) |
deliveryDate | LocalDate | Delivery date |
batchNumber | String | Batch/lot ID |
batchExpiryDate | LocalDate | Batch expiry |
warehouseLocation | String | Storage location |
qualityCertificateNumber | String | Quality cert number |
msdsReceived | Boolean | MSDS document received |
reachCompliant | Boolean | Batch-level REACH compliance |
ZdhcLevel Enum
| Value | Meaning |
|---|---|
LEVEL_1 | Conformant |
LEVEL_2 | Conformant Enhanced |
LEVEL_3 | Conformant Gold |
NOT_LISTED | Not in ZDHC MRSL |
CAS Number Search
The service supports both exact and partial CAS number search:
Shell
GET /api/v1/chemicals/search?casNumber=2580-78-1GET /api/v1/chemicals/search?casNumber=2580&partial=true
Soft Delete (Archive)
Chemical products are not permanently deleted. DELETE /api/v1/chemicals/{id} sets archived = true and records the archivedAt timestamp. Archived products are excluded from list queries by default.