Product Materials API

Product materials provide a unified API over the textile material kinds FIBER, YARN and FABRIC. Path parameter {kind} accepts only FIBER, YARN or FABRIC.

Endpoints

Materials

Material documents

Purchases and purchase documents

GET /api/v1/product/materials

200 OK returns ProductMaterialListResponseDto with data, meta and facets.

POST /api/v1/product/materials

Request body (CreateProductMaterialDto)

201 Created returns ProductMaterialDto. 400 indicates validation errors; 404 indicates a linked supplier was not found.

Material detail and activity

GET /api/v1/product/materials/{kind}/{id} returns ProductMaterialDto.

GET /api/v1/product/materials/{kind}/{id}/detail returns MaterialDetailDto, including overview metrics and the latest document.

GET /api/v1/product/materials/{kind}/{id}/activities?page=1&pageSize=20 returns MaterialActivityListResponseDto.

Material documents

GET /api/v1/product/materials/{kind}/{id}/documents accepts page, pageSize, includeDeleted and category. It returns ProductMaterialDocumentListResponseDto.

Direct document upload accepts one or more files as multipart form data and returns UploadProductMaterialDocumentsResponseDto.

Presigned material documents

POST /api/v1/product/materials/{kind}/{id}/documents/presign accepts PresignProductMaterialDocumentsRequestDto:

The response contains one documentId, presignedUrl, objectKey and expiresAt per file. Upload each file to its URL, then call POST /api/v1/product/materials/{kind}/{id}/documents/{documentId}/complete with checksumSha256.

Purchases

GET /api/v1/product/materials/{kind}/{id}/purchases?page=1&pageSize=20 returns MaterialPurchaseListResponseDto.

POST /api/v1/product/materials/{kind}/{id}/purchases creates a purchase and requires the idempotency-key header.

Request body (CreateMaterialPurchaseDto)

1curl -X POST {{BASE_URL}}/api/v1/product/materials/FABRIC/{id}/purchases \
2  -H "Authorization: Bearer $CONFORMA_PAT" \
3  -H "Content-Type: application/json" \
4  -H "idempotency-key: po-2026-0001-line-1" \
5  -d '{
6    "lotNumber": "LOT-2026-0001",
7    "purchaseDate": "2026-06-16T00:00:00.000Z",
8    "quantity": "120",
9    "unitOfMeasure": "M",
10    "ddtNumber": "DDT-2026-0001",
11    "invoiceNumber": "INV-2026-0001"
12  }'

PATCH /api/v1/product/materials/{kind}/{id}/purchases/{purchaseId} updates an existing material purchase.

Purchase estimate

POST /api/v1/product/materials/{kind}/{id}/purchases/estimate accepts EstimateMaterialPurchaseTransportDto and returns EstimateMaterialPurchaseTransportResponseDto.

Purchase with documents

POST /api/v1/product/materials/{kind}/{id}/purchases/with-documents creates a material purchase with documents in a single multipart request. It requires the idempotency-key header and returns MaterialPurchaseCreatedResponseDto.

The multipart implementation expects:

Each attachment manifest entry contains clientId, fileName, contentType, sizeBytes and category. Supported categories are DDT, INVOICE, TRANSACTION_CERTIFICATE, TEST_REPORT and OTHER.

Purchase documents

GET /api/v1/product/materials/{kind}/{id}/purchases/{purchaseId}/documents lists documents for an existing material purchase.

POST /api/v1/product/materials/{kind}/{id}/purchases/{purchaseId}/documents uploads documents for that purchase and returns 201 Created.

DELETE /api/v1/product/materials/{kind}/{id}/purchases/{purchaseId}/documents/{documentId} removes a document and returns 204 No Content.