Products API — ConformaESG Integration Service

Supplier Products

Endpoints

Method	Path	Description
`POST`	`/api/v1/supplier/products`	Create a supplier product
`PATCH`	`/api/v1/supplier/products/{id}`	Update a supplier product
`POST`	`/api/v1/supplier/products/bulk`	Bulk upsert supplier products

POST /api/v1/supplier/products

Request Body

Field	Type	Required	Description
`name`	string	✅	Product name
`code`	string	❌	Product code
`category`	string	❌	Product category
`subcategory`	string	❌	Product subcategory
`supplier_id`	integer	✅	FK to `Supplier.id`
`description`	string	❌	Product description
`composition`	string	❌	Material composition
`technical_specs`	string	❌	Technical specifications
`unit_of_measure`	string	❌	`METERS`, `KG`, `PIECES`, `ROLLS`. Default: `KG`
`product_origin_country`	string	❌	ISO 3166-1 alpha-2 where product is made
`raw_material_origin_country`	string	❌	ISO 3166-1 alpha-2 where raw material originates
`quantity_available`	number	❌	Current stock quantity (≥ 0)
`lead_time_days`	integer	❌	Procurement lead time in days (≥ 0)
`price_per_unit`	number	❌	Purchase price per unit
`currency`	string	❌	ISO 4217 currency code
`product_weight_kg`	number	❌	Product weight in kg (must be positive)
`minimum_order`	number	❌	Minimum order quantity
`gots_certified`	boolean	❌	GOTS certification
`grs_certified`	boolean	❌	GRS certification
`oeko_tex_certified`	boolean	❌	OEKO-TEX certification
`cradle_to_cradle_certified`	boolean	❌	Cradle to Cradle certification
`better_cotton_certified`	boolean	❌	Better Cotton certification
`other_certifications`	string	❌	Other certifications
`recycled_content_percent`	number	❌	Percentage of recycled content
`organic_content_percent`	number	❌	Percentage of organic content
`sustainability_notes`	string	❌	Sustainability notes
`available`	boolean	❌	Whether the product is available. Default: `true`
`metadata`	object	❌	Arbitrary JSON key-value pairs

Note

product_origin_country and raw_material_origin_country are validated against the full ISO 3166-1 alpha-2 country list. Invalid codes return 400 Bad Request.

Shell
1curl -X POST "http://localhost:8080/api/v1/supplier/products?userId=1" \
-H "Content-Type: application/json" \
-d '{
  "name": "Cotton Fabric 200gsm",
  "code": "FAB-CN-200",
  "supplier_id": 1,
  "unit_of_measure": "METERS",
  "price_per_unit": 3.50,
  "currency": "EUR",
  "product_origin_country": "IN",
  "raw_material_origin_country": "IN",
  "quantity_available": 2500.0,
  "lead_time_days": 45,
  "gots_certified": true
}'

JavaScript
1const resp = await fetch('/api/v1/supplier/products?userId=1', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
  name: 'Cotton Fabric 200gsm',
  code: 'FAB-CN-200',
  supplier_id: 1,
  unit_of_measure: 'METERS',
  product_origin_country: 'IN',
  raw_material_origin_country: 'IN',
  quantity_available: 2500.0,
  lead_time_days: 45
})
14});

POST /api/v1/supplier/products/bulk

Upserts by (code, supplier_id) combination.

JSON
1{
"items": [
  {
    "name": "Cotton Fabric 200gsm",
    "code": "FAB-001",
    "supplier_id": 1,
    "unit_of_measure": "METERS",
    "product_origin_country": "IN",
    "quantity_available": 2500.0,
    "lead_time_days": 45
  },
  {
    "name": "Polyester Lining",
    "code": "FAB-002",
    "supplier_id": 1,
    "unit_of_measure": "METERS",
    "product_origin_country": "CN"
  }
]
20}

UnitOfMeasure Enum

Value	Meaning	Typical Use
`KG`	Kilograms — default	Raw materials sold by weight
`METERS`	Linear metres	Fabric, ribbon, tape
`PIECES`	Individual items	Buttons, zippers, accessories
`ROLLS`	Full rolls	Fabric reels, paper

Company Products

Endpoints

Method	Path	Description
`POST`	`/api/v1/company/products`	Create a company product
`PATCH`	`/api/v1/company/products/{id}`	Update a company product
`POST`	`/api/v1/company/products/bulk`	Bulk upsert company products

POST /api/v1/company/products

All fields from BaseProduct apply here as well. Company products include additional fields for retail and sustainability scoring.

Additional Fields

Field	Type	Required	Description
`name`	string	✅	Product name
`code`	string	❌	Product code
`unit_of_measure`	string	❌	`METERS`, `KG`, `PIECES`, `ROLLS`. Default: `KG`
`product_origin_country`	string	❌	ISO 3166-1 alpha-2
`raw_material_origin_country`	string	❌	ISO 3166-1 alpha-2
`quantity_available`	number	❌	Current stock quantity (≥ 0)
`lead_time_days`	integer	❌	Lead time in days (≥ 0)
`available`	boolean	❌	Whether the product is available. Default: `true`
`metadata`	object	❌	Arbitrary JSON key-value pairs

Shell
1curl -X POST "http://localhost:8080/api/v1/company/products?userId=1" \
-H "Content-Type: application/json" \
-d '{
  "name": "Eco Tote Bag",
  "code": "TOTE-ECO-001",
  "unit_of_measure": "PIECES",
  "product_origin_country": "TR",
  "raw_material_origin_country": "IN",
  "quantity_available": 1500.0,
  "lead_time_days": 30,
  "recycled_content_percent": 40.0,
  "sustainability_notes": "Made from recycled PET bottles"
}'

JavaScript
1const resp = await fetch('/api/v1/company/products?userId=1', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
  name: 'Eco Tote Bag',
  code: 'TOTE-ECO-001',
  unit_of_measure: 'PIECES',
  product_origin_country: 'TR',
  raw_material_origin_country: 'IN',
  quantity_available: 1500.0,
  lead_time_days: 30
})
13});