{ "openapi": "3.1.0", "info": { "title": "CatalogHub supplier catalogue API", "version": "1.0.0", "description": "Maintain supplier catalogues and propose selected products at buyer-specific net ordering-unit prices. Requires a verified supplier, email-verified key owner with manager/admin rights, and explicitly enabled API access. Keys default to 90 days, support narrow scopes and can be revoked. Rate limit 120 requests/minute; JSON body limit 2 MiB; maximum500products per atomic batch. Publication creates a review; it does not directly update live buyer products or publish to Hops." }, "servers": [ { "url": "https://cataloghub.hopshq.com" } ], "components": { "securitySchemes": { "supplierKey": { "type": "http", "scheme": "bearer", "bearerFormat": "chsup_ supplier key" } }, "schemas": { "SupplierProductInput": { "type": "object", "additionalProperties": false, "required": [ "sku", "productName", "category", "basePrice" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "type": "string", "minLength": 1, "maxLength": 80 }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999 }, { "type": "null" } ] }, "basePrice": { "type": "number", "minimum": 0, "maximum": 99999999.99, "multipleOf": 0.01 }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] } } }, "SupplierProduct": { "type": "object", "required": [ "id", "sku", "productName", "basePrice", "isPublic", "isActive" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "basePrice": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ProductSizing": { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, "SupplierAllergenEvidenceInput": { "type": "object", "additionalProperties": false, "required": [ "supplierAttested", "source", "completeness", "statements" ], "properties": { "supplierAttested": { "const": true }, "source": { "type": "object", "additionalProperties": false, "required": [ "reference", "description" ], "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "issuedOn": { "type": "string", "format": "date" } } }, "completeness": { "enum": [ "partial", "complete" ] }, "statements": { "type": "array", "minItems": 1, "maxItems": 28, "items": { "type": "object", "additionalProperties": false, "required": [ "allergenCode", "statementType", "exactText" ], "properties": { "allergenCode": { "enum": [ "celery", "cereals_containing_gluten", "crustaceans", "eggs", "fish", "lupin", "milk", "molluscs", "mustard", "peanuts", "sesame", "soybeans", "sulphur_dioxide_sulphites", "tree_nuts" ] }, "statementType": { "enum": [ "contains", "may_contain", "declared_not_present" ] }, "exactText": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Immutable supplier-attested evidence, not buyer approval. Duplicate code/type statements and conflicting Contains/absence are rejected. Complete requires explicit Contains or declared_not_present for all fourteen codes; may_contain is an independent precautionary warning. Omitted codes remain unknown. Reference and exactText are supplier-authored; CatalogHub does not fetch or independently validate an external specification." }, "SupplierAllergenEvidenceRevision": { "type": "object", "properties": { "revisionId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "revisionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "productSnapshot": { "type": "object" }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "supplierAttested", "source", "completeness", "statements" ], "properties": { "supplierAttested": { "const": true }, "source": { "type": "object", "additionalProperties": false, "required": [ "reference", "description" ], "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "issuedOn": { "type": "string", "format": "date" } } }, "completeness": { "enum": [ "partial", "complete" ] }, "statements": { "type": "array", "minItems": 1, "maxItems": 28, "items": { "type": "object", "additionalProperties": false, "required": [ "allergenCode", "statementType", "exactText" ], "properties": { "allergenCode": { "enum": [ "celery", "cereals_containing_gluten", "crustaceans", "eggs", "fish", "lupin", "milk", "molluscs", "mustard", "peanuts", "sesame", "soybeans", "sulphur_dioxide_sulphites", "tree_nuts" ] }, "statementType": { "enum": [ "contains", "may_contain", "declared_not_present" ] }, "exactText": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Immutable supplier-attested evidence, not buyer approval. Duplicate code/type statements and conflicting Contains/absence are rejected. Complete requires explicit Contains or declared_not_present for all fourteen codes; may_contain is an independent precautionary warning. Omitted codes remain unknown. Reference and exactText are supplier-authored; CatalogHub does not fetch or independently validate an external specification." }, "submittedByUserId": { "type": "string", "format": "uuid" }, "submittedAt": { "type": "string", "format": "date-time" }, "sourceAuthority": { "const": "authenticated_supplier" }, "status": { "const": "supplier_attested" }, "idempotent": { "type": "boolean" } } } } }, "paths": { "/api/supplier/v1/me": { "get": { "operationId": "getSupplierIdentity", "summary": "Read supplier identity and key scopes", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:read", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "enum": [ "catalog:read", "catalog:write", "relationships:read", "catalog:publish" ] } } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/products": { "get": { "operationId": "listSupplierProducts", "summary": "Read full/private or active public catalogue", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, { "name": "visibility", "in": "query", "schema": { "enum": [ "all", "public" ], "default": "all" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "products", "total", "limit", "offset" ], "properties": { "products": { "type": "array", "items": { "type": "object", "required": [ "id", "sku", "productName", "basePrice", "isPublic", "isActive" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "basePrice": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } }, "put": { "operationId": "upsertSupplierProducts", "summary": "Atomically upsert complete products by supplier SKU", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "products" ], "properties": { "products": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "sku", "productName", "category", "basePrice" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "type": "string", "minLength": 1, "maxLength": 80 }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999 }, { "type": "null" } ] }, "basePrice": { "type": "number", "minimum": 0, "maximum": 99999999.99, "multipleOf": 0.01 }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] } } }, "description": "Complete product replacements. Supplier-scoped SKUs are trimmed and case-insensitive; duplicate SKUs in one batch are rejected atomically." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "required": [ "id", "sku", "productName", "basePrice", "isPublic", "isActive" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "basePrice": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships": { "get": { "operationId": "listSupplierRelationships", "summary": "Read supplier buyer relationships", "security": [ { "supplierKey": [] } ], "x-required-scope": "relationships:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "relationships", "total", "limit", "offset" ], "properties": { "relationships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "supplierId": { "type": "string", "format": "uuid" }, "restaurantId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "buyerCompanyId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "scope": { "enum": [ "restaurant", "company" ] }, "buyerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "trustBasis": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalogueAccessStatus": { "type": "string" }, "offeredProductCount": { "type": "integer" }, "acceptedProductCount": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships/{relationshipId}/products": { "get": { "operationId": "getSupplierBuyerProducts", "summary": "Read proposed and accepted buyer prices separately", "security": [ { "supplierKey": [] } ], "x-required-scope": "relationships:read", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "isActive": { "type": "boolean" }, "proposedPrice": { "type": "string" }, "submissionId": { "type": "string", "format": "uuid" }, "reviewStatus": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "catalogRequestId": { "type": "string", "format": "uuid" } } } }, "acceptedProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "supplierSku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "currentPrice": { "type": "string" }, "unitOfMeasure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "catalogDisposition": { "type": "string" }, "lastProcurementSyncedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } }, "offersTotal": { "type": "integer" }, "acceptedTotal": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships/{relationshipId}/publications": { "post": { "operationId": "publishSupplierProducts", "summary": "Propose products and negotiated prices for buyer review", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:publish", "description": "Requires approved, terms_set, catalogue_enabled or ordering_enabled status; supplier_confirmed or admin_confirmed trust; restaurant scope and exactly one active supplier assignment. Product data is snapshotted. Exact retries return200with the same IDs; changed payloads conflict.", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Reuse for exact retries. Changed payloads return a conflict." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "price" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "price": { "type": "number", "minimum": 0, "maximum": 99999999.99, "multipleOf": 0.01 } } }, "description": "Active products owned by the supplier, at buyer-specific net ordering-unit prices. Duplicate product IDs are rejected." }, "notes": { "type": "string", "minLength": 0, "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "catalogRequestId", "submissionId", "status", "idempotent" ], "properties": { "publicationId": { "type": "string", "format": "uuid" }, "catalogRequestId": { "type": "string", "format": "uuid" }, "submissionId": { "type": "string", "format": "uuid" }, "status": { "const": "pending_review", "description": "Initial publication status; read relationship products for the current review state." }, "idempotent": { "type": "boolean" } } } } } }, "201": { "description": "New proposal created. Buyer approval and completion are required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "catalogRequestId", "submissionId", "status", "idempotent" ], "properties": { "publicationId": { "type": "string", "format": "uuid" }, "catalogRequestId": { "type": "string", "format": "uuid" }, "submissionId": { "type": "string", "format": "uuid" }, "status": { "const": "pending_review", "description": "Initial publication status; read relationship products for the current review state." }, "idempotent": { "type": "boolean" } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/products/{productId}/allergen-evidence": { "get": { "operationId": "listSupplierAllergenEvidence", "summary": "Read immutable supplier product allergen evidence revisions", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:read", "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "revisions", "total", "limit", "offset" ], "properties": { "revisions": { "type": "array", "items": { "type": "object", "properties": { "revisionId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "revisionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "productSnapshot": { "type": "object" }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "supplierAttested", "source", "completeness", "statements" ], "properties": { "supplierAttested": { "const": true }, "source": { "type": "object", "additionalProperties": false, "required": [ "reference", "description" ], "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "issuedOn": { "type": "string", "format": "date" } } }, "completeness": { "enum": [ "partial", "complete" ] }, "statements": { "type": "array", "minItems": 1, "maxItems": 28, "items": { "type": "object", "additionalProperties": false, "required": [ "allergenCode", "statementType", "exactText" ], "properties": { "allergenCode": { "enum": [ "celery", "cereals_containing_gluten", "crustaceans", "eggs", "fish", "lupin", "milk", "molluscs", "mustard", "peanuts", "sesame", "soybeans", "sulphur_dioxide_sulphites", "tree_nuts" ] }, "statementType": { "enum": [ "contains", "may_contain", "declared_not_present" ] }, "exactText": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Immutable supplier-attested evidence, not buyer approval. Duplicate code/type statements and conflicting Contains/absence are rejected. Complete requires explicit Contains or declared_not_present for all fourteen codes; may_contain is an independent precautionary warning. Omitted codes remain unknown. Reference and exactText are supplier-authored; CatalogHub does not fetch or independently validate an external specification." }, "submittedByUserId": { "type": "string", "format": "uuid" }, "submittedAt": { "type": "string", "format": "date-time" }, "sourceAuthority": { "const": "authenticated_supplier" }, "status": { "const": "supplier_attested" }, "idempotent": { "type": "boolean" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } }, "post": { "operationId": "submitSupplierAllergenEvidence", "summary": "Submit supplier-attested evidence without buyer sign-off", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:write", "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Reuse for exact retries. Changed payloads return a conflict." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "supplierAttested", "source", "completeness", "statements" ], "properties": { "supplierAttested": { "const": true }, "source": { "type": "object", "additionalProperties": false, "required": [ "reference", "description" ], "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "issuedOn": { "type": "string", "format": "date" } } }, "completeness": { "enum": [ "partial", "complete" ] }, "statements": { "type": "array", "minItems": 1, "maxItems": 28, "items": { "type": "object", "additionalProperties": false, "required": [ "allergenCode", "statementType", "exactText" ], "properties": { "allergenCode": { "enum": [ "celery", "cereals_containing_gluten", "crustaceans", "eggs", "fish", "lupin", "milk", "molluscs", "mustard", "peanuts", "sesame", "soybeans", "sulphur_dioxide_sulphites", "tree_nuts" ] }, "statementType": { "enum": [ "contains", "may_contain", "declared_not_present" ] }, "exactText": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Immutable supplier-attested evidence, not buyer approval. Duplicate code/type statements and conflicting Contains/absence are rejected. Complete requires explicit Contains or declared_not_present for all fourteen codes; may_contain is an independent precautionary warning. Omitted codes remain unknown. Reference and exactText are supplier-authored; CatalogHub does not fetch or independently validate an external specification." } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "revisionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "productSnapshot": { "type": "object" }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "supplierAttested", "source", "completeness", "statements" ], "properties": { "supplierAttested": { "const": true }, "source": { "type": "object", "additionalProperties": false, "required": [ "reference", "description" ], "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "issuedOn": { "type": "string", "format": "date" } } }, "completeness": { "enum": [ "partial", "complete" ] }, "statements": { "type": "array", "minItems": 1, "maxItems": 28, "items": { "type": "object", "additionalProperties": false, "required": [ "allergenCode", "statementType", "exactText" ], "properties": { "allergenCode": { "enum": [ "celery", "cereals_containing_gluten", "crustaceans", "eggs", "fish", "lupin", "milk", "molluscs", "mustard", "peanuts", "sesame", "soybeans", "sulphur_dioxide_sulphites", "tree_nuts" ] }, "statementType": { "enum": [ "contains", "may_contain", "declared_not_present" ] }, "exactText": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Immutable supplier-attested evidence, not buyer approval. Duplicate code/type statements and conflicting Contains/absence are rejected. Complete requires explicit Contains or declared_not_present for all fourteen codes; may_contain is an independent precautionary warning. Omitted codes remain unknown. Reference and exactText are supplier-authored; CatalogHub does not fetch or independently validate an external specification." }, "submittedByUserId": { "type": "string", "format": "uuid" }, "submittedAt": { "type": "string", "format": "date-time" }, "sourceAuthority": { "const": "authenticated_supplier" }, "status": { "const": "supplier_attested" }, "idempotent": { "type": "boolean" } } } } } }, "201": { "description": "Created; human buyer declaration and separate Hops approval remain required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisionId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "revisionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "productSnapshot": { "type": "object" }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "supplierAttested", "source", "completeness", "statements" ], "properties": { "supplierAttested": { "const": true }, "source": { "type": "object", "additionalProperties": false, "required": [ "reference", "description" ], "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "issuedOn": { "type": "string", "format": "date" } } }, "completeness": { "enum": [ "partial", "complete" ] }, "statements": { "type": "array", "minItems": 1, "maxItems": 28, "items": { "type": "object", "additionalProperties": false, "required": [ "allergenCode", "statementType", "exactText" ], "properties": { "allergenCode": { "enum": [ "celery", "cereals_containing_gluten", "crustaceans", "eggs", "fish", "lupin", "milk", "molluscs", "mustard", "peanuts", "sesame", "soybeans", "sulphur_dioxide_sulphites", "tree_nuts" ] }, "statementType": { "enum": [ "contains", "may_contain", "declared_not_present" ] }, "exactText": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Immutable supplier-attested evidence, not buyer approval. Duplicate code/type statements and conflicting Contains/absence are rejected. Complete requires explicit Contains or declared_not_present for all fourteen codes; may_contain is an independent precautionary warning. Omitted codes remain unknown. Reference and exactText are supplier-authored; CatalogHub does not fetch or independently validate an external specification." }, "submittedByUserId": { "type": "string", "format": "uuid" }, "submittedAt": { "type": "string", "format": "date-time" }, "sourceAuthority": { "const": "authenticated_supplier" }, "status": { "const": "supplier_attested" }, "idempotent": { "type": "boolean" } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships/{relationshipId}/allergen-publications": { "post": { "operationId": "publishSupplierAllergenEvidence", "summary": "Share immutable evidence for buyer declaration review", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:publish", "description": "Requires confirmed active restaurant relationship and one active assignment. Exact buyer item IDs and supplier SKUs must match; supplier product identity must match the evidence snapshot. New items must first complete catalogue acceptance. Never creates declarations or Hops writes.", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Reuse for exact retries. Changed payloads return a conflict." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "revisionId", "restaurantCatalogItemId" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "revisionId": { "type": "string", "format": "uuid" }, "restaurantCatalogItemId": { "type": "string", "format": "uuid" } } }, "description": "Exact supplier product and immutable revision mapped to an accepted buyer catalogue item. Duplicate supplier/buyer products rejected. Unaccepted or changed supplier product identities cannot be published." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicationId": { "type": "string", "format": "uuid" }, "evidenceRequestId": { "type": "string", "format": "uuid" }, "evidenceResponseId": { "type": "string", "format": "uuid" }, "status": { "const": "pending_buyer_declaration", "description": "Initial status; buyer reviews through the application." }, "idempotent": { "type": "boolean" }, "buyerNotified": { "type": "boolean", "description": "A buyer notification was delivered by this request. Exact retries do not send another notification." } } } } } }, "201": { "description": "Created; human buyer declaration and separate Hops approval remain required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicationId": { "type": "string", "format": "uuid" }, "evidenceRequestId": { "type": "string", "format": "uuid" }, "evidenceResponseId": { "type": "string", "format": "uuid" }, "status": { "const": "pending_buyer_declaration", "description": "Initial status; buyer reviews through the application." }, "idempotent": { "type": "boolean" }, "buyerNotified": { "type": "boolean", "description": "A buyer notification was delivered by this request. Exact retries do not send another notification." } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/public/suppliers/{supplierId}/catalog": { "get": { "operationId": "getPublicSupplierCatalogue", "summary": "Read verified supplier active public listings without any prices", "security": [], "parameters": [ { "name": "supplierId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "products", "total", "limit", "offset" ], "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/imports/file-preview": { "post": { "operationId": "previewSupplierSpreadsheet", "summary": "Parse CSV/XLS/XLSX for review without saving", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:write", "description": "Multipart file with optional JSON mapping of source header to supplier_sku, product_name, category, submitted_price, unit_of_measure or pack_size. Ambiguous headers return mappingRequired and recommendations. No writes.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "mapping": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/imports/preview": { "post": { "operationId": "previewSupplierImport", "summary": "Preview editable product rows without saving", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "additionalProperties": false, "properties": { "products": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "baseline": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "products": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": true } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "minimum": 1 }, "fields": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/imports/commit": { "post": { "operationId": "commitSupplierImport", "summary": "Save reviewed product rows atomically", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Reuse for exact retries. Changed payloads return a conflict." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "baseline", "products" ], "properties": { "baseline": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "products": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "sku", "productName", "category", "basePrice" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "type": "string", "minLength": 1, "maxLength": 80 }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999 }, { "type": "null" } ] }, "basePrice": { "type": "number", "minimum": 0, "maximum": 99999999.99, "multipleOf": 0.01 }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] } } }, "description": "Complete product replacements. Supplier-scoped SKUs are trimmed and case-insensitive; duplicate SKUs in one batch are rejected atomically." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "required": [ "id", "sku", "productName", "basePrice", "isPublic", "isActive" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 120 }, "productName": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "unitOfMeasure": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "packSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "basePrice": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$" }, "isPublic": { "type": "boolean", "default": false }, "isActive": { "type": "boolean", "default": true }, "sizing": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "baseUomType", "baseUom", "baseNumber", "baseContainer" ], "properties": { "baseUomType": { "enum": [ "Unit", "Weight", "Volume" ] }, "baseUom": { "enum": [ "Units", "Grams", "Millilitres" ] }, "baseNumber": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, "baseContainer": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Container": { "enum": [ "Bag", "Block", "Bottle", "Box", "Case", "Container", "Crate", "Each", "Keg", "Pack", "Punnet", "Roll", "Tin", "Tot", "Tray", "Tub" ] }, "multipleL1Number": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "dependentRequired": { "multipleL1Container": [ "multipleL1Number" ], "multipleL1Number": [ "multipleL1Container" ] }, "allOf": [ { "oneOf": [ { "properties": { "baseUomType": { "const": "Unit" }, "baseUom": { "const": "Units" } } }, { "properties": { "baseUomType": { "const": "Weight" }, "baseUom": { "const": "Grams" } } }, { "properties": { "baseUomType": { "const": "Volume" }, "baseUom": { "const": "Millilitres" } } } ] } ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "idempotent": { "type": "boolean" } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships/{relationshipId}/catalogue": { "get": { "operationId": "getSupplierCustomerCatalogue", "summary": "Read saved customer selection and tier", "security": [ { "supplierKey": [] } ], "x-required-scope": "relationships:read", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "name", "productIds", "discountPercent", "discountedProductIds" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "name": { "type": "string", "maxLength": 120 }, "productIds": { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "discountPercent": { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01 }, "discountedProductIds": { "anyOf": [ { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ] }, "relationshipId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } }, "put": { "operationId": "saveSupplierCustomerCatalogue", "summary": "Save shared items and percentage-off-RRP tier", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:write", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "name", "productIds", "discountPercent", "discountedProductIds" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "name": { "type": "string", "minLength": 0, "maxLength": 120 }, "productIds": { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "discountPercent": { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01 }, "discountedProductIds": { "anyOf": [ { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "name", "productIds", "discountPercent", "discountedProductIds" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "name": { "type": "string", "maxLength": 120 }, "productIds": { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "discountPercent": { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01 }, "discountedProductIds": { "anyOf": [ { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ] }, "relationshipId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships/{relationshipId}/catalogue/preview": { "get": { "operationId": "previewSupplierCustomerCatalogue", "summary": "Calculate RRP, discount and buyer prices", "security": [ { "supplierKey": [] } ], "x-required-scope": "relationships:read", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog": { "type": "object", "additionalProperties": false, "required": [ "revision", "name", "productIds", "discountPercent", "discountedProductIds" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "name": { "type": "string", "maxLength": 120 }, "productIds": { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "discountPercent": { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01 }, "discountedProductIds": { "anyOf": [ { "type": "array", "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ] }, "relationshipId": { "type": "string", "format": "uuid" } } }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "previewHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "productName": { "type": "string" }, "rrp": { "type": "number", "minimum": 0, "maximum": 99999999.99, "multipleOf": 0.01 }, "discountPercent": { "type": "number" }, "price": { "type": "number", "minimum": 0, "maximum": 99999999.99, "multipleOf": 0.01 } } } } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } }, "/api/supplier/v1/trade-relationships/{relationshipId}/catalogue/publications": { "post": { "operationId": "publishSupplierCustomerCatalogue", "summary": "Propose exactly previewed customer catalogue for buyer review", "security": [ { "supplierKey": [] } ], "x-required-scope": "catalog:publish", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,120}$", "description": "Reuse for exact retries. Changed payloads return a conflict." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "previewHash" ], "properties": { "previewHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "notes": { "type": "string", "minLength": 0, "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "catalogRequestId", "submissionId", "status", "idempotent" ], "properties": { "publicationId": { "type": "string", "format": "uuid" }, "catalogRequestId": { "type": "string", "format": "uuid" }, "submissionId": { "type": "string", "format": "uuid" }, "status": { "const": "pending_review", "description": "Initial publication status; read relationship products for the current review state." }, "idempotent": { "type": "boolean" } } } } } }, "201": { "description": "New proposal created. Buyer approval and completion are required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "catalogRequestId", "submissionId", "status", "idempotent" ], "properties": { "publicationId": { "type": "string", "format": "uuid" }, "catalogRequestId": { "type": "string", "format": "uuid" }, "submissionId": { "type": "string", "format": "uuid" }, "status": { "const": "pending_review", "description": "Initial publication status; read relationship products for the current review state." }, "idempotent": { "type": "boolean" } } } } } }, "400": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "401": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "403": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "404": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "409": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "413": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } }, "429": { "description": "Stable error code with English fallback and localisation messageKey.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "messageKey": { "type": "string" } } } } } } } } } } }