Supplier Module — ConformaESG Integration Service

Overview

The supplier module manages master data for all suppliers, including full address and geolocation, ESG compliance flags, certifications, contact information, and rich list filtering.

Entity: `Supplier`

Field	Type	DB Column	Description
`id`	`Long`	`id`	Auto-generated PK
`name`	`String`	`name`	Legal supplier name (required)
`category`	`String`	`category`	Business category (required)
`customCategory`	`String`	`custom_category`	Custom description for "Altro"
`address`	`String`	`address`	Street address
`city`	`String`	`city`	City
`zipCode`	`String`	`zip_code`	Postal code (CAP)
`province`	`String`	`province`	Province/Region
`country`	`String`	`country`	ISO 3166-1 alpha-2
`latitude`	`Double`	`latitude`	Geographic latitude
`longitude`	`Double`	`longitude`	Geographic longitude
`contactName`	`String`	`contact_name`	Contact person name
`contactEmail`	`String`	`contact_email`	Contact email
`contactPhone`	`String`	`contact_phone`	Contact phone
`reachCompliant`	`Boolean`	`reach_compliant`	REACH regulation compliant (default: `false`)
`svhcCompliant`	`Boolean`	`svhc_compliant`	SVHC substance compliant (default: `false`)
`userId`	`Long`	`user_id`	Owner/creator user ID
`companyId`	`Long`	`company_id`	Associated company ID
`activityType`	`String`	`activity_type`	Type of supplier activity
`metadata`	`Map<String, Object>`	`metadata`	Arbitrary JSON key-value pairs
`createdAt`	`LocalDateTime`	`created_at`	Set on `@PrePersist`
`updatedAt`	`LocalDateTime`	`updated_at`	Set on `@PreUpdate`

Entity: `SupplierCertification`

Each supplier can have multiple certifications. Certifications are cascaded from the parent supplier (deleting a supplier also deletes its certifications).

Field	Type	Description
`id`	`Long`	Auto PK
`supplier`	`Supplier`	Parent supplier (`@ManyToOne`)
`certificationType`	`String`	e.g. `GOTS`, `GRS`, `OEKO_TEX`, `ISO_14001` (required)
`certificateNumber`	`String`	Certificate reference number
`certificateExpiry`	`LocalDate`	Expiry date
`documentId`	`Long`	FK to uploaded document
`isDigitallySigned`	`Boolean`	Whether digitally signed
`signatureVerified`	`Boolean`	Whether signature was verified
`verificationStatus`	`String`	`PENDING`, `VERIFIED`, `REJECTED`
`verificationDetails`	`String`	Verification notes
`verifiedAt`	`LocalDateTime`	When verification occurred
`createdAt` / `updatedAt`	`LocalDateTime`	Timestamps

Entity Metadata

The metadata field is a free-form JSON column (stored as jsonb in PostgreSQL) that allows attaching arbitrary key-value pairs to any supplier without schema changes:

JSON
1{
2  "erp_code": "SUP-0042",
3  "internal_rating": "A",
4  "vat_number": "IT12345678901",
5  "custom_tags": ["priority", "eu-based"]
6}

`GET /api/v1/suppliers` Filter Parameters

The list endpoint supports rich filtering and sorting. Default page size is 50 (max 250).

Param	Type	Default	Description
`page`	integer	`0`	Zero-based page index
`size`	integer	`50`	Items per page (max 250)
`country`	string	—	ISO alpha-2 country filter
`category`	string	—	Category filter
`complianceStatus`	string	—	Compliance status filter
`search`	string	—	Free-text search across name/category
`sortBy`	string	`created_date`	Sort field
`sortOrder`	string	`desc`	`asc` or `desc`

Service Methods

create(SupplierDTO, userId) — persists, returns DTO
update(id, SupplierDTO) — partial update, returns DTO
findById(id) — throws 404 if not found
list(page, size, country, category, complianceStatus, search, sortBy, sortOrder) — paginated
delete(id) — hard delete, cascades to certifications
bulkUpsert(items) — upserts by name

Overview

Entity: Supplier

Entity: SupplierCertification

Entity Metadata

GET /api/v1/suppliers Filter Parameters

Service Methods

Entity: `Supplier`

Entity: `SupplierCertification`

`GET /api/v1/suppliers` Filter Parameters