manicanldes-backend/docs/procurement-api.md

Phase 2A: suppliers and materials

This phase introduces private, organization-scoped supplier and material master data. It does not create purchase orders, receipts, invoices, stock movements, production batches, or documents.

Method	Route	Permission	Purpose
GET	/suppliers	procurement.read	Page through suppliers; filter with active and search
POST/PUT	/suppliers, /suppliers/:id	procurement.manage	Create or replace supplier records
GET	/materials	procurement.read	Page through materials; filter with active and search
POST/PUT	/materials, /materials/:id	procurement.manage	Create or replace materials
GET	/suppliers/:supplierId/materials	procurement.read	View the supplier's compatible materials
PUT	/suppliers/:supplierId/materials/:materialId	procurement.manage	Create or replace compatibility, commercial lead time and quote

Supplier and material codes are uppercase, organization-unique identifiers. Materials use a fixed kind and unit to avoid ambiguous procurement and BOM quantities. Compatibility records hold a supplier SKU, lead time, minimum quantity, price, currency, and active status. A future purchase order must snapshot these values rather than rely on a later edit.

All endpoints require a session and enforce a permission again inside write transactions. Missing suppliers and materials produce distinct scoped errors. Create, update, and compatibility actions are audit-recorded without arbitrary payloads. The migration is append-only and grants the new permissions only to existing system roles; custom roles require an explicit update.