{ "openapi": "3.0.0", "paths": { "/api/health/live": { "get": { "description": "Lightweight check used by orchestrators to detect dead processes. Always succeeds while the event loop is responsive.", "operationId": "ServerHealthController_live", "parameters": [], "responses": { "200": { "description": "The Health Check is successful\n\nProcess is alive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": {}, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } }, "503": { "description": "The Health Check is not successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": { "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" }, "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } } }, "summary": "Liveness probe", "tags": [ "health" ] } }, "/api/health/ready": { "get": { "description": "Checks the process is fully started, not draining, and downstream dependencies (MongoDB, Redis, Kafka) are reachable.", "operationId": "ServerHealthController_ready", "parameters": [], "responses": { "200": { "description": "The Health Check is successful\n\nProcess is ready to accept traffic.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": {}, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } }, "503": { "description": "The Health Check is not successful\n\nProcess is shutting down or a downstream dependency is unreachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": { "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" }, "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } } }, "summary": "Readiness probe", "tags": [ "health" ] } }, "/api/v1/carriers": { "get": { "description": "Returns a paginated list of carriers scoped to the caller account.", "operationId": "CarriersController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of carriers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List carriers", "tags": [ "carriers" ] }, "post": { "description": "Creates a new carrier within the caller account.", "operationId": "CarriersController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierCreate" } } } }, "responses": { "201": { "description": "Carrier created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A carrier with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CARRIER_CODE_ALREADY_EXISTS": { "summary": "Duplicate carrier code", "value": { "error": { "code": "CARRIER_CODE_ALREADY_EXISTS", "message": "Carrier with code \"EXPRESS\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CARRIER_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "CARRIER_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "CARRIER_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "CARRIER_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create carrier", "tags": [ "carriers" ] } }, "/api/v1/carriers/{id}": { "get": { "description": "Returns a carrier by its identifier.", "operationId": "CarriersController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Carrier identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Carrier found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Carrier not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CARRIER_NOT_FOUND": { "summary": "Carrier not found", "value": { "error": { "code": "CARRIER_NOT_FOUND", "message": "Carrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch carrier", "tags": [ "carriers" ] }, "patch": { "description": "Partially updates a carrier by its identifier. The code is immutable.", "operationId": "CarriersController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Carrier identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierUpdate" } } } }, "responses": { "200": { "description": "Carrier updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Carrier not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CARRIER_NOT_FOUND": { "summary": "Carrier not found", "value": { "error": { "code": "CARRIER_NOT_FOUND", "message": "Carrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CARRIER_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "CARRIER_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update carrier", "tags": [ "carriers" ] }, "delete": { "description": "Soft-deletes a carrier by its identifier.", "operationId": "CarriersController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Carrier identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Carrier deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Carrier not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CARRIER_NOT_FOUND": { "summary": "Carrier not found", "value": { "error": { "code": "CARRIER_NOT_FOUND", "message": "Carrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete carrier", "tags": [ "carriers" ] } }, "/api/v1/channels": { "get": { "description": "Returns a paginated list of channels scoped to the caller account.", "operationId": "ChannelsController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "types", "in": "query", "schema": { "uniqueItems": true, "type": "array", "items": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] } } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of channels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List channels", "tags": [ "channels" ] }, "post": { "description": "Creates a new channel within the caller account.", "operationId": "ChannelsController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCreate" } } } }, "responses": { "201": { "description": "Channel created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A channel with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_CODE_ALREADY_EXISTS": { "summary": "Duplicate channel code", "value": { "error": { "code": "CHANNEL_CODE_ALREADY_EXISTS", "message": "Channel with code \"WEBSITE\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "CHANNEL_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "CHANNEL_INVALID_TYPE": { "summary": "Type is outside the supported enum", "value": { "error": { "code": "CHANNEL_INVALID_TYPE", "message": "type must be one of MARKETPLACE, WEBSITE, RETAIL, B2B" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create channel", "tags": [ "channels" ] } }, "/api/v1/channels/{id}": { "get": { "description": "Returns a channel by its identifier.", "operationId": "ChannelsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Channel identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Channel found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Channel not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_NOT_FOUND": { "summary": "Channel not found", "value": { "error": { "code": "CHANNEL_NOT_FOUND", "message": "Channel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch channel", "tags": [ "channels" ] }, "patch": { "description": "Partially updates a channel by its identifier. The code is immutable.", "operationId": "ChannelsController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Channel identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelUpdate" } } } }, "responses": { "200": { "description": "Channel updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Channel not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_NOT_FOUND": { "summary": "Channel not found", "value": { "error": { "code": "CHANNEL_NOT_FOUND", "message": "Channel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "CHANNEL_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update channel", "tags": [ "channels" ] }, "delete": { "description": "Soft-deletes a channel by its identifier. The delete is rejected when an active strategy carrier or strategy channel still references this channel code.", "operationId": "ChannelsController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Channel identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Channel deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Channel not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_NOT_FOUND": { "summary": "Channel not found", "value": { "error": { "code": "CHANNEL_NOT_FOUND", "message": "Channel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "The channel is referenced by one or more active strategy carriers or strategy channels and cannot be soft-deleted. The `details` array lists every dependency type with its count; entries with zero references are omitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CHANNEL_IN_USE": { "summary": "Channel is still referenced by strategy carriers and strategy channels", "value": { "error": { "code": "CHANNEL_IN_USE", "message": "Channel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a cannot be deleted because it is in use", "details": [ { "entity": "StrategyCarrier", "count": 3 }, { "entity": "StrategyChannel", "count": 2 } ] } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete channel", "tags": [ "channels" ] } }, "/api/v1/strategies/{strategyId}/carriers": { "get": { "description": "Returns a paginated list of strategy carriers scoped to the caller account and parent strategy.", "operationId": "StrategyCarriersController_list_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "carrier_id", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "delivery_type_code", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "capability", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "returns", "same_day", "tracking" ] } } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of strategy carriers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Strategy not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List strategy carriers", "tags": [ "strategy-carriers" ] }, "post": { "description": "Creates a new strategy carrier within the caller account and parent strategy. The parent Strategy, the referenced Carrier and the referenced DeliveryType must already exist in the same account, and the DeliveryType must be active.", "operationId": "StrategyCarriersController_create_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierCreate" } } } }, "responses": { "201": { "description": "Strategy carrier created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, Carrier, DeliveryType) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "CARRIER_NOT_FOUND": { "summary": "Carrier not found", "value": { "error": { "code": "CARRIER_NOT_FOUND", "message": "Carrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A strategy carrier with the same (strategy, carrier) composite key already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_CARRIER_COMPOSITE_KEY_ALREADY_EXISTS": { "summary": "Composite key already in use", "value": { "error": { "code": "STRATEGY_CARRIER_COMPOSITE_KEY_ALREADY_EXISTS", "message": "StrategyCarrier with composite_key \":\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant — typically an inactive delivery type or an invalid coverage definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_INACTIVE": { "summary": "Referenced delivery type is inactive", "value": { "error": { "code": "DELIVERY_TYPE_INACTIVE", "message": "delivery type STANDARD is inactive" } } }, "STRATEGY_CARRIER_COVERAGE_AREA_INVALID_ZIP_RANGE": { "summary": "ZIP range coverage is malformed (start > end)", "value": { "error": { "code": "STRATEGY_CARRIER_COVERAGE_AREA_INVALID_ZIP_RANGE", "message": "zip range start must be <= zip range end" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create strategy carrier", "tags": [ "strategy-carriers" ] } }, "/api/v1/strategies/{strategyId}/carriers/{id}": { "get": { "description": "Returns a strategy carrier by its identifier.", "operationId": "StrategyCarriersController_find_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy carrier identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Strategy carrier found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyCarrier) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_CARRIER_NOT_FOUND": { "summary": "StrategyCarrier not found", "value": { "error": { "code": "STRATEGY_CARRIER_NOT_FOUND", "message": "StrategyCarrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch strategy carrier", "tags": [ "strategy-carriers" ] }, "patch": { "description": "Partially updates a strategy carrier by its identifier. The composite key (strategy, carrier) is immutable; delivery_type_codes may be replaced as long as each referenced delivery type exists and is active.", "operationId": "StrategyCarriersController_update_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy carrier identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierUpdate" } } } }, "responses": { "200": { "description": "Strategy carrier updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyCarrier, DeliveryType) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_CARRIER_NOT_FOUND": { "summary": "StrategyCarrier not found", "value": { "error": { "code": "STRATEGY_CARRIER_NOT_FOUND", "message": "StrategyCarrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant — typically an inactive delivery type or an invalid coverage definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_INACTIVE": { "summary": "Referenced delivery type is inactive", "value": { "error": { "code": "DELIVERY_TYPE_INACTIVE", "message": "delivery type STANDARD is inactive" } } }, "STRATEGY_CARRIER_COVERAGE_AREA_INVALID_ZIP_RANGE": { "summary": "ZIP range coverage is malformed (start > end)", "value": { "error": { "code": "STRATEGY_CARRIER_COVERAGE_AREA_INVALID_ZIP_RANGE", "message": "zip range start must be <= zip range end" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update strategy carrier", "tags": [ "strategy-carriers" ] }, "delete": { "description": "Soft-deletes a strategy carrier by its identifier.", "operationId": "StrategyCarriersController_remove_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy carrier identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Strategy carrier deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyCarrier) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_CARRIER_NOT_FOUND": { "summary": "StrategyCarrier not found", "value": { "error": { "code": "STRATEGY_CARRIER_NOT_FOUND", "message": "StrategyCarrier 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete strategy carrier", "tags": [ "strategy-carriers" ] } }, "/api/v1/delivery-types": { "get": { "description": "Returns a paginated list of delivery types scoped to the caller account.", "operationId": "DeliveryTypesController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of delivery types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List delivery types", "tags": [ "delivery-types" ] }, "post": { "description": "Creates a new delivery type within the caller account.", "operationId": "DeliveryTypesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeCreate" } } } }, "responses": { "201": { "description": "Delivery type created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A delivery type with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_CODE_ALREADY_EXISTS": { "summary": "Duplicate delivery type code", "value": { "error": { "code": "DELIVERY_TYPE_CODE_ALREADY_EXISTS", "message": "DeliveryType with code \"STANDARD\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "DELIVERY_TYPE_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "DELIVERY_TYPE_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "DELIVERY_TYPE_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create delivery type", "tags": [ "delivery-types" ] } }, "/api/v1/delivery-types/{id}": { "get": { "description": "Returns a delivery type by its identifier.", "operationId": "DeliveryTypesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Delivery type identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Delivery type found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "DeliveryType not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch delivery type", "tags": [ "delivery-types" ] }, "patch": { "description": "Partially updates a delivery type by its identifier. The code is immutable.", "operationId": "DeliveryTypesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Delivery type identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeUpdate" } } } }, "responses": { "200": { "description": "Delivery type updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "DeliveryType not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "DELIVERY_TYPE_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update delivery type", "tags": [ "delivery-types" ] }, "delete": { "description": "Soft-deletes a delivery type by its identifier.", "operationId": "DeliveryTypesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Delivery type identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Delivery type deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "DeliveryType not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete delivery type", "tags": [ "delivery-types" ] } }, "/api/v1/strategies": { "get": { "description": "Returns a paginated list of strategies scoped to the caller account.", "operationId": "StrategiesController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "type", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "category", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "clusterId", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of strategies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List strategies", "tags": [ "strategies" ] }, "post": { "description": "Creates a new strategy within the caller account. When `cluster_id` is provided it must reference an existing cluster owned by the same account.", "operationId": "StrategiesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCreate" } } } }, "responses": { "201": { "description": "Strategy created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Cluster not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_NOT_FOUND": { "summary": "Cluster not found", "value": { "error": { "code": "CLUSTER_NOT_FOUND", "message": "Cluster 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A strategy with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_CODE_ALREADY_EXISTS": { "summary": "Duplicate strategy code", "value": { "error": { "code": "STRATEGY_CODE_ALREADY_EXISTS", "message": "Strategy with code \"OMNI_DEFAULT\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "STRATEGY_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "STRATEGY_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "STRATEGY_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } }, "STRATEGY_HOLIDAY_HOURS_INCONSISTENT": { "summary": "operates_on_holidays does not match holiday_operating_hours", "value": { "error": { "code": "STRATEGY_HOLIDAY_HOURS_INCONSISTENT", "message": "holiday_operating_hours is required when operates_on_holidays is true" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create strategy", "tags": [ "strategies" ] } }, "/api/v1/strategies/{id}": { "get": { "description": "Returns a strategy by its identifier.", "operationId": "StrategiesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Strategy found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Strategy not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch strategy", "tags": [ "strategies" ] }, "patch": { "description": "Partially updates a strategy by its identifier. The code is immutable. When `cluster_id` is provided it must reference an existing cluster owned by the same account.", "operationId": "StrategiesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyUpdate" } } } }, "responses": { "200": { "description": "Strategy updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, Cluster) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "CLUSTER_NOT_FOUND": { "summary": "Cluster not found", "value": { "error": { "code": "CLUSTER_NOT_FOUND", "message": "Cluster 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "STRATEGY_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } }, "STRATEGY_HOLIDAY_HOURS_INCONSISTENT": { "summary": "operates_on_holidays does not match holiday_operating_hours", "value": { "error": { "code": "STRATEGY_HOLIDAY_HOURS_INCONSISTENT", "message": "holiday_operating_hours is required when operates_on_holidays is true" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update strategy", "tags": [ "strategies" ] }, "delete": { "description": "Soft-deletes a strategy by its identifier.", "operationId": "StrategiesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Strategy deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Strategy not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete strategy", "tags": [ "strategies" ] } }, "/api/v1/clusters": { "get": { "description": "Returns a paginated list of clusters scoped to the caller account.", "operationId": "ClustersController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of clusters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List clusters", "tags": [ "clusters" ] }, "post": { "description": "Creates a new cluster within the caller account.", "operationId": "ClustersController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterCreate" } } } }, "responses": { "201": { "description": "Cluster created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A cluster with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_CODE_ALREADY_EXISTS": { "summary": "Duplicate cluster code", "value": { "error": { "code": "CLUSTER_CODE_ALREADY_EXISTS", "message": "Cluster with code \"ZONE_A\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "CLUSTER_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "CLUSTER_INVALID_COLOR": { "summary": "Color is not a valid hex value", "value": { "error": { "code": "CLUSTER_INVALID_COLOR", "message": "color must be a hex value (#RRGGBB)" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create cluster", "tags": [ "clusters" ] } }, "/api/v1/clusters/{id}": { "get": { "description": "Returns a cluster by its identifier.", "operationId": "ClustersController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Cluster identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Cluster found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Cluster not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_NOT_FOUND": { "summary": "Cluster not found", "value": { "error": { "code": "CLUSTER_NOT_FOUND", "message": "Cluster 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch cluster", "tags": [ "clusters" ] }, "patch": { "description": "Partially updates a cluster by its identifier. The code is immutable.", "operationId": "ClustersController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Cluster identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterUpdate" } } } }, "responses": { "200": { "description": "Cluster updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Cluster not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_NOT_FOUND": { "summary": "Cluster not found", "value": { "error": { "code": "CLUSTER_NOT_FOUND", "message": "Cluster 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "CLUSTER_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update cluster", "tags": [ "clusters" ] }, "delete": { "description": "Soft-deletes a cluster by its identifier.", "operationId": "ClustersController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Cluster identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Cluster deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Cluster not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CLUSTER_NOT_FOUND": { "summary": "Cluster not found", "value": { "error": { "code": "CLUSTER_NOT_FOUND", "message": "Cluster 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete cluster", "tags": [ "clusters" ] } }, "/api/v1/strategies/{strategyId}/channels": { "get": { "description": "Returns a paginated list of channels linked to the parent strategy within the caller account.", "operationId": "StrategyChannelsController_list_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "channel_code", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "type", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] } } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of strategy channels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Strategy not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List strategy channels", "tags": [ "strategy-channels" ] }, "post": { "description": "Creates a new strategy channel within the caller account and parent strategy. The parent Strategy and the referenced Channel must already exist in the same account.", "operationId": "StrategyChannelsController_create_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelCreate" } } } }, "responses": { "201": { "description": "Strategy channel created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, Channel) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "CHANNEL_NOT_FOUND": { "summary": "Channel not found", "value": { "error": { "code": "CHANNEL_NOT_FOUND", "message": "Channel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A strategy channel with the same (strategy, channel) composite key already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_CHANNEL_COMPOSITE_KEY_ALREADY_EXISTS": { "summary": "Composite key already in use", "value": { "error": { "code": "STRATEGY_CHANNEL_COMPOSITE_KEY_ALREADY_EXISTS", "message": "StrategyChannel with composite_key \":\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant — typically an invalid inventory allocation value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_CHANNEL_INVALID_INVENTORY_ALLOCATION_VALUE": { "summary": "Inventory allocation value is out of range", "value": { "error": { "code": "STRATEGY_CHANNEL_INVALID_INVENTORY_ALLOCATION_VALUE", "message": "PERCENTAGE allocation value must be a number between 0 and 100" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Link a channel to the strategy", "tags": [ "strategy-channels" ] } }, "/api/v1/strategies/{strategyId}/channels/{id}": { "get": { "description": "Returns a strategy channel by its identifier.", "operationId": "StrategyChannelsController_find_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy channel identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Strategy channel found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyChannel) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_CHANNEL_NOT_FOUND": { "summary": "StrategyChannel not found", "value": { "error": { "code": "STRATEGY_CHANNEL_NOT_FOUND", "message": "StrategyChannel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch strategy channel", "tags": [ "strategy-channels" ] }, "patch": { "description": "Partially updates a strategy channel by its identifier. The composite key (strategy, channel) is immutable.", "operationId": "StrategyChannelsController_update_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy channel identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelUpdate" } } } }, "responses": { "200": { "description": "Strategy channel updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyChannel) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_CHANNEL_NOT_FOUND": { "summary": "StrategyChannel not found", "value": { "error": { "code": "STRATEGY_CHANNEL_NOT_FOUND", "message": "StrategyChannel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant — typically an invalid inventory allocation value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_CHANNEL_INVALID_INVENTORY_ALLOCATION_VALUE": { "summary": "Inventory allocation value is out of range", "value": { "error": { "code": "STRATEGY_CHANNEL_INVALID_INVENTORY_ALLOCATION_VALUE", "message": "PERCENTAGE allocation value must be a number between 0 and 100" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update strategy channel", "tags": [ "strategy-channels" ] }, "delete": { "description": "Soft-deletes a strategy channel by its identifier.", "operationId": "StrategyChannelsController_remove_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy channel identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Strategy channel deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyChannel) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_CHANNEL_NOT_FOUND": { "summary": "StrategyChannel not found", "value": { "error": { "code": "STRATEGY_CHANNEL_NOT_FOUND", "message": "StrategyChannel 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Unlink strategy channel", "tags": [ "strategy-channels" ] } }, "/api/v1/customers": { "get": { "description": "Returns a paginated list of customers scoped to the caller account, with optional type and text search.", "operationId": "CustomersController_list_v1", "parameters": [ { "required": false, "name": "type", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of customers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List customers", "tags": [ "customers" ] }, "post": { "description": "Registers a new customer within the caller account. The document is deduplicated per account.", "operationId": "CustomersController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" } } } }, "responses": { "201": { "description": "Customer created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A customer with the same document already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_DOCUMENT_ALREADY_EXISTS": { "summary": "Duplicate document", "value": { "error": { "code": "CUSTOMER_DOCUMENT_ALREADY_EXISTS", "message": "Customer with document \"*******7735\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_INVALID_DOCUMENT": { "summary": "Document is not a valid CPF or CNPJ", "value": { "error": { "code": "CUSTOMER_INVALID_DOCUMENT", "message": "document must be a valid CPF (11 digits) or CNPJ (14 digits)" } } }, "CUSTOMER_INVALID_NAME": { "summary": "Name is empty or out of bounds", "value": { "error": { "code": "CUSTOMER_INVALID_NAME", "message": "name must be between 2 and 200 characters" } } }, "CUSTOMER_INVALID_EMAIL": { "summary": "Email format is invalid", "value": { "error": { "code": "CUSTOMER_INVALID_EMAIL", "message": "email format is invalid" } } }, "CUSTOMER_FIELD_PF_ONLY": { "summary": "birthDate/socialName sent for a PJ customer", "value": { "error": { "code": "CUSTOMER_FIELD_PF_ONLY", "message": "birthDate and socialName are only allowed for individuals (CPF)" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create customer", "tags": [ "customers" ] } }, "/api/v1/customers/{id}": { "get": { "description": "Returns the customer detail (identification + denormalized KPIs) by its identifier.", "operationId": "CustomersController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Customer found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Customer not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Customer not found", "value": { "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch customer", "tags": [ "customers" ] }, "patch": { "description": "Partially updates a customer contact (e-mail/phone) and name. Document, type and externalId are immutable.", "operationId": "CustomersController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdate" } } } }, "responses": { "200": { "description": "Customer updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Customer not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Customer not found", "value": { "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_INVALID_EMAIL": { "summary": "Email format is invalid", "value": { "error": { "code": "CUSTOMER_INVALID_EMAIL", "message": "email format is invalid" } } }, "CUSTOMER_INVALID_PHONE": { "summary": "Phone exceeds the maximum length", "value": { "error": { "code": "CUSTOMER_INVALID_PHONE", "message": "phone must be at most 30 characters" } } }, "CUSTOMER_INVALID_NAME": { "summary": "Name is empty or out of bounds", "value": { "error": { "code": "CUSTOMER_INVALID_NAME", "message": "name must be between 2 and 200 characters" } } }, "CUSTOMER_FIELD_PF_ONLY": { "summary": "birthDate/socialName sent for a PJ customer", "value": { "error": { "code": "CUSTOMER_FIELD_PF_ONLY", "message": "birthDate and socialName are only allowed for individuals (CPF)" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update customer contact", "tags": [ "customers" ] } }, "/api/v1/customers/{customerId}/addresses": { "post": { "description": "Adds an address to the customer addresses array. The first address becomes the default automatically; toggling is_default promotes the new address and demotes the previous default.", "operationId": "CustomerAddressesController_add_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCustomerAddress" } } } }, "responses": { "201": { "description": "Address added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCustomerAddressResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Customer not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Customer not found", "value": { "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks an address domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_INVALID_ADDRESS": { "summary": "A required address field is empty", "value": { "error": { "code": "CUSTOMER_INVALID_ADDRESS", "message": "address must have non-empty zipCode, street, number, district, city, state and country" } } }, "CUSTOMER_INVALID_ADDRESS_TYPE": { "summary": "The address type is not a known value", "value": { "error": { "code": "CUSTOMER_INVALID_ADDRESS_TYPE", "message": "type must be one of SHIPPING, BILLING, OTHER" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Add customer address", "tags": [ "customer-addresses" ] } }, "/api/v1/customers/{customerId}/addresses/{addressId}": { "patch": { "description": "Replaces the editable data of an existing address. The default flag is unchanged by this action.", "operationId": "CustomerAddressesController_update_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "addressId", "required": true, "in": "path", "description": "Address identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressUpdate" } } } }, "responses": { "200": { "description": "Address updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Customer, CustomerAddress) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Customer not found", "value": { "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "CUSTOMER_ADDRESS_NOT_FOUND": { "summary": "CustomerAddress not found", "value": { "error": { "code": "CUSTOMER_ADDRESS_NOT_FOUND", "message": "CustomerAddress 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks an address domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_INVALID_ADDRESS": { "summary": "A required address field is empty", "value": { "error": { "code": "CUSTOMER_INVALID_ADDRESS", "message": "address must have non-empty zipCode, street, number, district, city, state and country" } } }, "CUSTOMER_INVALID_ADDRESS_TYPE": { "summary": "The address type is not a known value", "value": { "error": { "code": "CUSTOMER_INVALID_ADDRESS_TYPE", "message": "type must be one of SHIPPING, BILLING, OTHER" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update customer address", "tags": [ "customer-addresses" ] }, "delete": { "description": "Removes the address from the customer addresses array. Removing the only default is blocked; removing the current default while others remain requires newDefaultId, which is promoted to the new default.", "operationId": "CustomerAddressesController_remove_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "addressId", "required": true, "in": "path", "description": "Address identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "newDefaultId", "required": false, "in": "query", "description": "Address id to promote to default when removing the current default and others remain.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Address removed." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Customer, CustomerAddress) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Customer not found", "value": { "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "CUSTOMER_ADDRESS_NOT_FOUND": { "summary": "CustomerAddress not found", "value": { "error": { "code": "CUSTOMER_ADDRESS_NOT_FOUND", "message": "CustomerAddress 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The removal breaks an address domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_CANNOT_REMOVE_DEFAULT_ADDRESS": { "summary": "Removing the default while it is the only address", "value": { "error": { "code": "CUSTOMER_CANNOT_REMOVE_DEFAULT_ADDRESS", "message": "cannot remove the default address while it is the only one" } } }, "CUSTOMER_ADDRESS_NEW_DEFAULT_REQUIRED": { "summary": "Removing the default with others but no new default provided", "value": { "error": { "code": "CUSTOMER_ADDRESS_NEW_DEFAULT_REQUIRED", "message": "a new default address must be provided to remove the current default" } } }, "CUSTOMER_ADDRESS_INVALID_NEW_DEFAULT": { "summary": "The provided new default is invalid", "value": { "error": { "code": "CUSTOMER_ADDRESS_INVALID_NEW_DEFAULT", "message": "the new default address must be different from the one being removed" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Remove customer address", "tags": [ "customer-addresses" ] } }, "/api/v1/customers/{customerId}/addresses/{addressId}/default": { "patch": { "description": "Promotes the address to the customer default; the previous default is demoted. Only one default exists.", "operationId": "CustomerAddressesController_setDefault_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "addressId", "required": true, "in": "path", "description": "Address identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Address set as default.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultCustomerAddressResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Customer, CustomerAddress) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Customer not found", "value": { "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "CUSTOMER_ADDRESS_NOT_FOUND": { "summary": "CustomerAddress not found", "value": { "error": { "code": "CUSTOMER_ADDRESS_NOT_FOUND", "message": "CustomerAddress 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Set default customer address", "tags": [ "customer-addresses" ] } }, "/api/v1/freight-types": { "get": { "description": "Returns a paginated list of freight types scoped to the caller account.", "operationId": "FreightTypesController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of freight types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List freight types", "tags": [ "freight-types" ] }, "post": { "description": "Creates a new freight type within the caller account.", "operationId": "FreightTypesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeCreate" } } } }, "responses": { "201": { "description": "Freight type created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A freight type with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FREIGHT_TYPE_CODE_ALREADY_EXISTS": { "summary": "Duplicate freight type code", "value": { "error": { "code": "FREIGHT_TYPE_CODE_ALREADY_EXISTS", "message": "FreightType with code \"CIF\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FREIGHT_TYPE_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "FREIGHT_TYPE_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "FREIGHT_TYPE_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "FREIGHT_TYPE_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create freight type", "tags": [ "freight-types" ] } }, "/api/v1/freight-types/{id}": { "get": { "description": "Returns a freight type by its identifier.", "operationId": "FreightTypesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Freight type identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Freight type found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "FreightType not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FREIGHT_TYPE_NOT_FOUND": { "summary": "FreightType not found", "value": { "error": { "code": "FREIGHT_TYPE_NOT_FOUND", "message": "FreightType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch freight type", "tags": [ "freight-types" ] }, "patch": { "description": "Partially updates a freight type by its identifier. The code is immutable.", "operationId": "FreightTypesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Freight type identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeUpdate" } } } }, "responses": { "200": { "description": "Freight type updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "FreightType not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FREIGHT_TYPE_NOT_FOUND": { "summary": "FreightType not found", "value": { "error": { "code": "FREIGHT_TYPE_NOT_FOUND", "message": "FreightType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FREIGHT_TYPE_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "FREIGHT_TYPE_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update freight type", "tags": [ "freight-types" ] }, "delete": { "description": "Soft-deletes a freight type by its identifier.", "operationId": "FreightTypesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Freight type identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Freight type deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "FreightType not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FREIGHT_TYPE_NOT_FOUND": { "summary": "FreightType not found", "value": { "error": { "code": "FREIGHT_TYPE_NOT_FOUND", "message": "FreightType 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete freight type", "tags": [ "freight-types" ] } }, "/api/v1/inventory": { "get": { "description": "Returns a paginated list of inventory positions scoped to the caller account. Filter by one or more exact \"sku\" (repeatable), free-text \"q\" matching SKU or product name (case-insensitive substring, mutually exclusive with \"sku\") and one or more \"strategyCode\" (repeatable).", "operationId": "InventoryController_list_v1", "parameters": [ { "required": false, "name": "sku", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 } } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "strategyCode", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 } } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of inventory positions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, filters) or \"q\" combined with \"sku\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List inventory positions", "tags": [ "inventory" ] }, "post": { "description": "Validates a batch of inventory items and publishes them to Kafka for asynchronous processing. The discriminator field \"updateType\" (SNAPSHOT|DELTA) at the root selects the validation schema and the resulting event type. SNAPSHOT overwrites the position (onHand, blocked, safetyStock); DELTA increments or decrements onHand. Returns 202 with a correlation id shared by every published event of the batch.", "operationId": "InventoryController_ingest_v1", "parameters": [], "requestBody": { "required": true, "description": "SNAPSHOT or DELTA payload, discriminated by the root \"updateType\" field.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InventorySnapshotIngest" }, { "$ref": "#/components/schemas/InventoryDeltaIngest" } ] } } } }, "responses": { "202": { "description": "Batch accepted and published to Kafka.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryIngestResponse" } } } }, "400": { "description": "Invalid payload: missing or unsupported updateType, schema violation on any item, or batch size out of bounds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } }, "503": { "description": "The message bus rejected or timed out the publish. The batch was not accepted; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SERVICE_UNAVAILABLE": { "summary": "Downstream dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "message bus is temporarily unavailable" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Ingest inventory snapshot or delta batch", "tags": [ "inventory" ] } }, "/api/v1/inventory-movements": { "get": { "description": "Returns a paginated history of inventory movements (SNAPSHOT and DELTA records) read from the Elasticsearch audit log, scoped to the caller account and ordered newest-first (\"occurred_at\" desc) by default. Filter by exact \"sku\", free-text \"q\" matching SKU or product name (case-insensitive substring), \"strategyCode\", \"reason\" and \"updateType\". Each item exposes the running balance (\"balance_after\") recorded when the movement occurred, which may be null for deltas still awaiting backfill.", "operationId": "InventoryMovementsController_list_v1", "parameters": [ { "required": false, "name": "sku", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "strategyCode", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 } } }, { "required": false, "name": "reason", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "updateType", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "occurredFrom", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "occurredTo", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated history of inventory movements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryMovementsListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List inventory movements", "tags": [ "inventory-movements" ] } }, "/api/v1/delivery-modalities": { "get": { "description": "Returns a paginated list of delivery modalities scoped to the caller account.", "operationId": "DeliveryModalitiesController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of delivery modalities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List delivery modalities", "tags": [ "delivery-modalities" ] }, "post": { "description": "Creates a new delivery modality within the caller account.", "operationId": "DeliveryModalitiesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityCreate" } } } }, "responses": { "201": { "description": "Delivery modality created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A delivery modality with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_MODALITY_CODE_ALREADY_EXISTS": { "summary": "Duplicate delivery modality code", "value": { "error": { "code": "DELIVERY_MODALITY_CODE_ALREADY_EXISTS", "message": "DeliveryModality with code \"EXPRESS\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_MODALITY_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "DELIVERY_MODALITY_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "DELIVERY_MODALITY_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "DELIVERY_MODALITY_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create delivery modality", "tags": [ "delivery-modalities" ] } }, "/api/v1/delivery-modalities/{id}": { "get": { "description": "Returns a delivery modality by its identifier.", "operationId": "DeliveryModalitiesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Delivery modality identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Delivery modality found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "DeliveryModality not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_MODALITY_NOT_FOUND": { "summary": "DeliveryModality not found", "value": { "error": { "code": "DELIVERY_MODALITY_NOT_FOUND", "message": "DeliveryModality 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch delivery modality", "tags": [ "delivery-modalities" ] }, "patch": { "description": "Partially updates a delivery modality by its identifier. The code is immutable.", "operationId": "DeliveryModalitiesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Delivery modality identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityUpdate" } } } }, "responses": { "200": { "description": "Delivery modality updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "DeliveryModality not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_MODALITY_NOT_FOUND": { "summary": "DeliveryModality not found", "value": { "error": { "code": "DELIVERY_MODALITY_NOT_FOUND", "message": "DeliveryModality 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_MODALITY_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "DELIVERY_MODALITY_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update delivery modality", "tags": [ "delivery-modalities" ] }, "delete": { "description": "Soft-deletes a delivery modality by its identifier.", "operationId": "DeliveryModalitiesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Delivery modality identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Delivery modality deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "DeliveryModality not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "DELIVERY_MODALITY_NOT_FOUND": { "summary": "DeliveryModality not found", "value": { "error": { "code": "DELIVERY_MODALITY_NOT_FOUND", "message": "DeliveryModality 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete delivery modality", "tags": [ "delivery-modalities" ] } }, "/api/v1/operators": { "get": { "description": "Returns a paginated list of operators scoped to the caller account.", "operationId": "OperatorsController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of operators.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List operators", "tags": [ "operators" ] }, "post": { "description": "Creates a new operator within the caller account.", "operationId": "OperatorsController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCreate" } } } }, "responses": { "201": { "description": "Operator created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "An operator with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_CODE_ALREADY_EXISTS": { "summary": "Duplicate operator code", "value": { "error": { "code": "OPERATOR_CODE_ALREADY_EXISTS", "message": "Operator with code \"WH_SP_01\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "OPERATOR_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } }, "OPERATOR_INVALID_EMAIL": { "summary": "Email format is invalid", "value": { "error": { "code": "OPERATOR_INVALID_EMAIL", "message": "email format is invalid" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create operator", "tags": [ "operators" ] } }, "/api/v1/operators/{id}": { "get": { "description": "Returns an operator by its identifier.", "operationId": "OperatorsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Operator identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Operator found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Operator not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_NOT_FOUND": { "summary": "Operator not found", "value": { "error": { "code": "OPERATOR_NOT_FOUND", "message": "Operator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch operator", "tags": [ "operators" ] }, "patch": { "description": "Partially updates an operator by its identifier. The code is immutable.", "operationId": "OperatorsController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Operator identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorUpdate" } } } }, "responses": { "200": { "description": "Operator updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Operator not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_NOT_FOUND": { "summary": "Operator not found", "value": { "error": { "code": "OPERATOR_NOT_FOUND", "message": "Operator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "OPERATOR_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } }, "OPERATOR_INVALID_EMAIL": { "summary": "Email format is invalid", "value": { "error": { "code": "OPERATOR_INVALID_EMAIL", "message": "email format is invalid" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update operator", "tags": [ "operators" ] }, "delete": { "description": "Soft-deletes an operator by its identifier.", "operationId": "OperatorsController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Operator identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Operator deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Operator not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_NOT_FOUND": { "summary": "Operator not found", "value": { "error": { "code": "OPERATOR_NOT_FOUND", "message": "Operator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "The operator is still linked to one or more strategies via StrategyOperator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "OPERATOR_IN_USE": { "summary": "Operator linked to active StrategyOperator records", "value": { "error": { "code": "OPERATOR_IN_USE", "message": "Operator with id \"\" is in use and cannot be deleted", "details": [ { "entity": "StrategyOperator", "count": 3 } ] } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete operator", "tags": [ "operators" ] } }, "/api/v1/strategies/{strategyId}/operators": { "get": { "description": "Returns a paginated list of operators linked to the parent strategy within the caller account.", "operationId": "StrategyOperatorsController_list_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of strategy operators.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Strategy not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List strategy operators", "tags": [ "strategy-operators" ] }, "post": { "description": "Creates a new strategy operator within the caller account and parent strategy. The parent Strategy and the referenced Operator must already exist in the same account.", "operationId": "StrategyOperatorsController_create_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorCreate" } } } }, "responses": { "201": { "description": "Strategy operator created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, Operator) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "OPERATOR_NOT_FOUND": { "summary": "Operator not found", "value": { "error": { "code": "OPERATOR_NOT_FOUND", "message": "Operator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A strategy operator with the same (strategy, operator) composite key already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_OPERATOR_COMPOSITE_KEY_ALREADY_EXISTS": { "summary": "Composite key already in use", "value": { "error": { "code": "STRATEGY_OPERATOR_COMPOSITE_KEY_ALREADY_EXISTS", "message": "StrategyOperator with composite_key \"/\" already exists" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Assign an operator to the strategy", "tags": [ "strategy-operators" ] } }, "/api/v1/strategies/{strategyId}/operators/{id}": { "get": { "description": "Returns a strategy operator by its identifier.", "operationId": "StrategyOperatorsController_find_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy operator identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Strategy operator found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyOperator) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_OPERATOR_NOT_FOUND": { "summary": "StrategyOperator not found", "value": { "error": { "code": "STRATEGY_OPERATOR_NOT_FOUND", "message": "StrategyOperator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch strategy operator", "tags": [ "strategy-operators" ] }, "patch": { "description": "Partially updates a strategy operator by its identifier. The composite key (strategy, operator) is immutable.", "operationId": "StrategyOperatorsController_update_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy operator identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorUpdate" } } } }, "responses": { "200": { "description": "Strategy operator updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyOperator) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_OPERATOR_NOT_FOUND": { "summary": "StrategyOperator not found", "value": { "error": { "code": "STRATEGY_OPERATOR_NOT_FOUND", "message": "StrategyOperator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update strategy operator", "tags": [ "strategy-operators" ] }, "delete": { "description": "Soft-deletes a strategy operator by its identifier.", "operationId": "StrategyOperatorsController_remove_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy operator identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Strategy operator deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyOperator) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_OPERATOR_NOT_FOUND": { "summary": "StrategyOperator not found", "value": { "error": { "code": "STRATEGY_OPERATOR_NOT_FOUND", "message": "StrategyOperator 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Unlink strategy operator", "tags": [ "strategy-operators" ] } }, "/api/v1/payment-methods": { "get": { "description": "Returns a paginated list of payment methods scoped to the caller account.", "operationId": "PaymentMethodsController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of payment methods.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List payment methods", "tags": [ "payment-methods" ] }, "post": { "description": "Creates a new payment method within the caller account.", "operationId": "PaymentMethodsController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodCreate" } } } }, "responses": { "201": { "description": "Payment method created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A payment method with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PAYMENT_METHOD_CODE_ALREADY_EXISTS": { "summary": "Duplicate payment method code", "value": { "error": { "code": "PAYMENT_METHOD_CODE_ALREADY_EXISTS", "message": "PaymentMethod with code \"PIX\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PAYMENT_METHOD_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "PAYMENT_METHOD_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{2,50}$/" } } }, "PAYMENT_METHOD_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "PAYMENT_METHOD_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create payment method", "tags": [ "payment-methods" ] } }, "/api/v1/payment-methods/{id}": { "get": { "description": "Returns a payment method by its identifier.", "operationId": "PaymentMethodsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment method identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Payment method found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PaymentMethod not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PAYMENT_METHOD_NOT_FOUND": { "summary": "PaymentMethod not found", "value": { "error": { "code": "PAYMENT_METHOD_NOT_FOUND", "message": "PaymentMethod 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch payment method", "tags": [ "payment-methods" ] }, "patch": { "description": "Partially updates a payment method by its identifier. The code is immutable.", "operationId": "PaymentMethodsController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment method identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodUpdate" } } } }, "responses": { "200": { "description": "Payment method updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PaymentMethod not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PAYMENT_METHOD_NOT_FOUND": { "summary": "PaymentMethod not found", "value": { "error": { "code": "PAYMENT_METHOD_NOT_FOUND", "message": "PaymentMethod 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PAYMENT_METHOD_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "PAYMENT_METHOD_INVALID_NAME", "message": "name length must be between 3 and 120 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update payment method", "tags": [ "payment-methods" ] }, "delete": { "description": "Soft-deletes a payment method by its identifier.", "operationId": "PaymentMethodsController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment method identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Payment method deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PaymentMethod not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PAYMENT_METHOD_NOT_FOUND": { "summary": "PaymentMethod not found", "value": { "error": { "code": "PAYMENT_METHOD_NOT_FOUND", "message": "PaymentMethod 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete payment method", "tags": [ "payment-methods" ] } }, "/api/v1/permissions": { "get": { "description": "Returns the localized permission catalog visible to the authenticated caller. The catalog labels and descriptions are resolved using the caller session language (pt-BR fallback).", "operationId": "PermissionsController_find_v1", "parameters": [], "responses": { "200": { "description": "Permission catalog returned." }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List authenticated permissions catalog", "tags": [ "permissions" ] } }, "/api/core/v1/permissions": { "get": { "description": "Returns the localized permission catalog consumed by the upstream IAM service. The catalog labels and descriptions are resolved using the caller session language (pt-BR fallback).", "operationId": "CorePermissionsController_find", "parameters": [], "responses": { "200": { "description": "Permission catalog returned." }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List IAM-facing core permissions catalog", "tags": [ "core-permissions" ] } }, "/api/v1/price-lists": { "get": { "description": "Returns a paginated list of price lists scoped to the caller account.", "operationId": "PriceListsController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "code", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of price lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List price lists", "tags": [ "price-lists" ] }, "post": { "description": "Creates a new price list header within the caller account.", "operationId": "PriceListsController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListCreate" } } } }, "responses": { "201": { "description": "Price list created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A price list with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_CODE_ALREADY_EXISTS": { "summary": "Duplicate price list code", "value": { "error": { "code": "PRICE_LIST_CODE_ALREADY_EXISTS", "message": "PriceList with code \"TABELA_VAREJO\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_INVALID_CODE": { "summary": "Code does not match the canonical format", "value": { "error": { "code": "PRICE_LIST_INVALID_CODE", "message": "code must match /^[A-Z0-9_]{1,100}$/" } } }, "PRICE_LIST_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "PRICE_LIST_INVALID_NAME", "message": "name must be between 1 and 200 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create price list", "tags": [ "price-lists" ] } }, "/api/v1/price-lists/{id}": { "get": { "description": "Returns a price list header by its identifier.", "operationId": "PriceListsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Price list found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PriceList not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch price list", "tags": [ "price-lists" ] }, "patch": { "description": "Partially updates a price list header. The code is immutable.", "operationId": "PriceListsController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListUpdate" } } } }, "responses": { "200": { "description": "Price list updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PriceList not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "PRICE_LIST_INVALID_NAME", "message": "name must be between 1 and 200 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update price list", "tags": [ "price-lists" ] }, "delete": { "description": "Soft-deletes a price list header. Items are not cascaded in this version.", "operationId": "PriceListsController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Price list deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PriceList not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete price list", "tags": [ "price-lists" ] } }, "/api/v1/price-lists/{id}/items": { "get": { "description": "Returns a paginated list of items belonging to the given price list. Items of price lists that are inactive (active=false) are still returned.", "operationId": "PriceListsController_listItems_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of price list items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListListItemResponse" } } } }, "400": { "description": "Invalid query parameters (pagination or q) or path UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PriceList not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List price list items", "tags": [ "price-lists" ] }, "post": { "description": "Validates a batch of price list items and publishes one Kafka event per item. The endpoint is agnostic — clients integrate over HTTP and the OMS translates each item into a PRICE_LIST_ITEM_UPSERTED event on oms.{accountCode}.price-list-item.events.", "operationId": "PriceListsController_upsertItems_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPriceListItems" } } } }, "responses": { "202": { "description": "Batch accepted and published to Kafka.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPriceListItemsResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "PriceList not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Bulk upsert items", "tags": [ "price-lists" ] } }, "/api/v1/product-categories": { "get": { "description": "Returns a paginated list of product categories scoped to the caller account.", "operationId": "ProductCategoriesController_list_v1", "parameters": [ { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of product categories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List product categories", "tags": [ "product-categories" ] }, "post": { "description": "Creates a new product category within the caller account and links the supplied SKUs.", "operationId": "ProductCategoriesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryCreate" } } } }, "responses": { "201": { "description": "Product category created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Product not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_NOT_FOUND": { "summary": "Product not found", "value": { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A product category with the same code or name already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_CODE_ALREADY_EXISTS": { "summary": "Duplicate category code", "value": { "error": { "code": "PRODUCT_CATEGORY_CODE_ALREADY_EXISTS", "message": "ProductCategory with code \"BLACK_FRIDAY\" already exists" } } }, "PRODUCT_CATEGORY_NAME_ALREADY_EXISTS": { "summary": "Duplicate category name", "value": { "error": { "code": "PRODUCT_CATEGORY_NAME_ALREADY_EXISTS", "message": "ProductCategory with name \"Promoção Black Friday\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_INVALID_NAME": { "summary": "Name is empty or out of bounds", "value": { "error": { "code": "PRODUCT_CATEGORY_INVALID_NAME", "message": "name must be between 2 and 60 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create product category", "tags": [ "product-categories" ] } }, "/api/v1/product-categories/{id}/products": { "get": { "description": "Returns a paginated list of products linked to the given category. Consumed by downstream engines (Promotions, Coupons).", "operationId": "ProductCategoriesController_listProducts_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product category identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of products linked to the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsByCategoryListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, filter values, or id not a UUID v4).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "ProductCategory not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_NOT_FOUND": { "summary": "ProductCategory not found", "value": { "error": { "code": "PRODUCT_CATEGORY_NOT_FOUND", "message": "ProductCategory 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List products by category", "tags": [ "product-categories" ] } }, "/api/v1/product-categories/{id}": { "get": { "description": "Returns a product category by id together with all linked productIds.", "operationId": "ProductCategoriesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product category identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Product category found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "ProductCategory not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_NOT_FOUND": { "summary": "ProductCategory not found", "value": { "error": { "code": "PRODUCT_CATEGORY_NOT_FOUND", "message": "ProductCategory 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch product category", "tags": [ "product-categories" ] }, "patch": { "description": "Partially updates a product category.", "operationId": "ProductCategoriesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product category identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryUpdate" } } } }, "responses": { "200": { "description": "Product category updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (ProductCategory, Product) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_NOT_FOUND": { "summary": "ProductCategory not found", "value": { "error": { "code": "PRODUCT_CATEGORY_NOT_FOUND", "message": "ProductCategory 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "PRODUCT_NOT_FOUND": { "summary": "Product not found", "value": { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "The new name collides with another category in the same account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_NAME_ALREADY_EXISTS": { "summary": "Duplicate category name", "value": { "error": { "code": "PRODUCT_CATEGORY_NAME_ALREADY_EXISTS", "message": "ProductCategory with name \"Promoção Black Friday\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_INVALID_NAME": { "summary": "Name is empty or out of bounds", "value": { "error": { "code": "PRODUCT_CATEGORY_INVALID_NAME", "message": "name must be between 2 and 60 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update product category", "tags": [ "product-categories" ] }, "delete": { "description": "Soft-deletes a product category by id. Refuses when the category still has linked products.", "operationId": "ProductCategoriesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product category identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Product category deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "ProductCategory not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_NOT_FOUND": { "summary": "ProductCategory not found", "value": { "error": { "code": "PRODUCT_CATEGORY_NOT_FOUND", "message": "ProductCategory 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "The category still has products linked to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_CATEGORY_IN_USE": { "summary": "Category has linked products", "value": { "error": { "code": "PRODUCT_CATEGORY_IN_USE", "message": "ProductCategory cannot be deleted because it is in use" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete product category", "tags": [ "product-categories" ] } }, "/api/v1/products": { "get": { "description": "Returns a paginated list of products scoped to the caller account.", "operationId": "ProductsController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "categories", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of products.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List products", "tags": [ "products" ] }, "post": { "description": "Idempotently ingests a product into the catalog by its natural key (SKU). When a product with the same SKU already exists, its mutable fields are updated; otherwise a new product is created. The response flag `created` distinguishes the two cases.", "operationId": "ProductsController_ingest_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductIngest" } } } }, "responses": { "200": { "description": "Product ingested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductIngestResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "The incoming EAN already belongs to a different product in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_EAN_ALREADY_EXISTS": { "summary": "EAN is already used by another product", "value": { "error": { "code": "PRODUCT_EAN_ALREADY_EXISTS", "message": "Product with ean \"7891000100100\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_INVALID_SKU": { "summary": "SKU is empty after trimming", "value": { "error": { "code": "PRODUCT_INVALID_SKU", "message": "sku must not be empty" } } }, "PRODUCT_INVALID_NAME": { "summary": "Name is empty or too long", "value": { "error": { "code": "PRODUCT_INVALID_NAME", "message": "name length must be between 3 and 200 characters" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Ingest product", "tags": [ "products" ] } }, "/api/v1/products/{id}": { "get": { "description": "Returns a product by its identifier.", "operationId": "ProductsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Product identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Product found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Product not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PRODUCT_NOT_FOUND": { "summary": "Product not found", "value": { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch product", "tags": [ "products" ] } }, "/api/v1/promotions": { "post": { "description": "Creates a new promotion within the caller account. The promotion is always created inactive.", "operationId": "PromotionsController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionCreate" } } } }, "responses": { "201": { "description": "Promotion created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A promotion with the same code already exists in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_CODE_ALREADY_EXISTS": { "summary": "Duplicate promotion code", "value": { "error": { "code": "PROMOTION_CODE_ALREADY_EXISTS", "message": "Promotion with code \"SUMMER_SALE\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant or references a missing entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_INVALID_VALIDITY": { "summary": "End date is not after start date", "value": { "error": { "code": "PROMOTION_INVALID_VALIDITY", "message": "validity.ends_at must be after validity.starts_at" } } }, "PROMOTION_INVALID_REFERENCE": { "summary": "Referenced entity does not exist in the account", "value": { "error": { "code": "PROMOTION_INVALID_REFERENCE", "message": "strategy ids not found: 99999999-9999-4999-8999-999999999999" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create promotion", "tags": [ "promotions" ] }, "get": { "description": "Returns a paginated list of promotions scoped to the caller account.", "operationId": "PromotionsController_list_v1", "parameters": [ { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of promotions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List promotions", "tags": [ "promotions" ] } }, "/api/v1/promotions/{id}": { "get": { "description": "Returns a promotion by its identifier.", "operationId": "PromotionsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Promotion identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Promotion found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Promotion not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_NOT_FOUND": { "summary": "Promotion not found", "value": { "error": { "code": "PROMOTION_NOT_FOUND", "message": "Promotion 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch promotion", "tags": [ "promotions" ] }, "patch": { "description": "Partially updates a promotion by its identifier. The code is immutable. Editing content is blocked while the promotion is active and in effect; toggling \"active\" is always allowed.", "operationId": "PromotionsController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Promotion identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionUpdate" } } } }, "responses": { "200": { "description": "Promotion updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Promotion not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_NOT_FOUND": { "summary": "Promotion not found", "value": { "error": { "code": "PROMOTION_NOT_FOUND", "message": "Promotion 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant, references a missing entity, or the promotion cannot have its content edited in its current lifecycle state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_EDIT_BLOCKED": { "summary": "Active and in-effect promotion cannot be edited", "value": { "error": { "code": "PROMOTION_EDIT_BLOCKED", "message": "an active promotion in effect cannot have its content edited; deactivate it first" } } }, "PROMOTION_INVALID_VALIDITY": { "summary": "End date is not after start date", "value": { "error": { "code": "PROMOTION_INVALID_VALIDITY", "message": "validity.ends_at must be after validity.starts_at" } } }, "PROMOTION_INVALID_REFERENCE": { "summary": "Referenced entity does not exist in the account", "value": { "error": { "code": "PROMOTION_INVALID_REFERENCE", "message": "strategy ids not found: 99999999-9999-4999-8999-999999999999" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update promotion", "tags": [ "promotions" ] }, "delete": { "description": "Soft-deletes a promotion by its identifier. An active promotion cannot be deleted.", "operationId": "PromotionsController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Promotion identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Promotion deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Promotion not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_NOT_FOUND": { "summary": "Promotion not found", "value": { "error": { "code": "PROMOTION_NOT_FOUND", "message": "Promotion 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The promotion is active and therefore cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PROMOTION_DELETE_BLOCKED": { "summary": "Active promotion cannot be deleted", "value": { "error": { "code": "PROMOTION_DELETE_BLOCKED", "message": "an active promotion cannot be deleted; deactivate it first" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete promotion", "tags": [ "promotions" ] } }, "/api/v1/state-machines": { "get": { "description": "Returns a paginated list of state machines for an entity type within the caller account.", "operationId": "StateMachinesController_list_v1", "parameters": [ { "required": true, "name": "entityType", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of state machines.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineListResponse" } } } }, "400": { "description": "Invalid query parameters (entityType, pagination).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List state machines", "tags": [ "state-machines" ] }, "post": { "description": "Creates a new state machine within the caller account. The transition graph is validated against the Kruzer mandatory skeleton (mandatory statuses present, cancellation route, no post-invoice cancellation, arrow integrity, custom status placement, nature composition).", "operationId": "StateMachinesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineCreate" } } } }, "responses": { "201": { "description": "State machine created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Status not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_NOT_FOUND": { "summary": "Status not found", "value": { "error": { "code": "STATUS_NOT_FOUND", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A state machine with the same code already exists for the entity type within the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_CODE_ALREADY_EXISTS": { "summary": "Duplicate state machine code", "value": { "error": { "code": "STATE_MACHINE_CODE_ALREADY_EXISTS", "message": "StateMachine with code \"DEFAULT_FLOW\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a structural save validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_VALIDATION_FAILED": { "summary": "One or more structural save validations failed (all violations are listed in details)", "value": { "error": { "code": "STATE_MACHINE_VALIDATION_FAILED", "message": "state machine failed structural validation", "details": [ { "code": "STATE_MACHINE_TRANSITION_NOT_ADJACENT", "message": "transition CREATED -> INVOICED skips or reverses the mandatory order" }, { "code": "STATE_MACHINE_MISSING_CANCEL_ROUTE", "message": "a transition to CANCELLED from a pre-INVOICED state (or wildcard) is required" }, { "code": "STATE_MACHINE_POST_INVOICE_CANCEL", "message": "transition INVOICED -> CANCELLED is not allowed from INVOICED onwards" }, { "code": "STATE_MACHINE_TRANSITION_UNDECLARED_STATE", "message": "transitions reference states not declared in the machine: REVIEW" }, { "code": "STATE_MACHINE_MISSING_MANDATORY_STATUS", "message": "mandatory statuses are missing from the declared states: FINISHED" }, { "code": "STATE_MACHINE_CUSTOM_STATUS_MISPLACED", "message": "custom status QUALITY_CHECK must sit between two consecutive mandatory statuses" }, { "code": "STATE_MACHINE_CHAIN_NOT_NAVIGABLE", "message": "there is no path from CREATED to FINISHED following the mandatory order" }, { "code": "STATE_MACHINE_NATURE_INITIAL_INVALID", "message": "state machine must have exactly 1 INITIAL status, found 0" }, { "code": "STATE_MACHINE_NATURE_FINAL_MISSING", "message": "state machine must have at least 1 FINAL status" }, { "code": "STATE_MACHINE_INVALID_STATE_CONFIG", "message": "state config for status PACKING is duplicated" } ] } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create state machine", "tags": [ "state-machines" ] } }, "/api/v1/state-machines/{id}": { "get": { "description": "Returns a state machine by its identifier.", "operationId": "StateMachinesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State machine identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "State machine found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "StateMachine not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_NOT_FOUND": { "summary": "StateMachine not found", "value": { "error": { "code": "STATE_MACHINE_NOT_FOUND", "message": "StateMachine 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch state machine", "tags": [ "state-machines" ] }, "patch": { "description": "Partially updates a state machine by its identifier (name, transitions, active). The code and entity type are immutable. When transitions change, the resulting graph goes through the same structural save validations as creation.", "operationId": "StateMachinesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State machine identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineUpdate" } } } }, "responses": { "200": { "description": "State machine updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (StateMachine, Status) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_NOT_FOUND": { "summary": "StateMachine not found", "value": { "error": { "code": "STATE_MACHINE_NOT_FOUND", "message": "StateMachine 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STATUS_NOT_FOUND": { "summary": "Status not found", "value": { "error": { "code": "STATUS_NOT_FOUND", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a structural save validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_VALIDATION_FAILED": { "summary": "One or more structural save validations failed (all violations are listed in details)", "value": { "error": { "code": "STATE_MACHINE_VALIDATION_FAILED", "message": "state machine failed structural validation", "details": [ { "code": "STATE_MACHINE_TRANSITION_NOT_ADJACENT", "message": "transition CREATED -> INVOICED skips or reverses the mandatory order" }, { "code": "STATE_MACHINE_MISSING_CANCEL_ROUTE", "message": "a transition to CANCELLED from a pre-INVOICED state (or wildcard) is required" }, { "code": "STATE_MACHINE_POST_INVOICE_CANCEL", "message": "transition INVOICED -> CANCELLED is not allowed from INVOICED onwards" }, { "code": "STATE_MACHINE_TRANSITION_UNDECLARED_STATE", "message": "transitions reference states not declared in the machine: REVIEW" }, { "code": "STATE_MACHINE_MISSING_MANDATORY_STATUS", "message": "mandatory statuses are missing from the declared states: FINISHED" }, { "code": "STATE_MACHINE_CUSTOM_STATUS_MISPLACED", "message": "custom status QUALITY_CHECK must sit between two consecutive mandatory statuses" }, { "code": "STATE_MACHINE_CHAIN_NOT_NAVIGABLE", "message": "there is no path from CREATED to FINISHED following the mandatory order" }, { "code": "STATE_MACHINE_NATURE_INITIAL_INVALID", "message": "state machine must have exactly 1 INITIAL status, found 0" }, { "code": "STATE_MACHINE_NATURE_FINAL_MISSING", "message": "state machine must have at least 1 FINAL status" }, { "code": "STATE_MACHINE_INVALID_STATE_CONFIG", "message": "state config for status PACKING is duplicated" } ] } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update state machine", "tags": [ "state-machines" ] }, "delete": { "description": "Soft-deletes a state machine by its identifier.", "operationId": "StateMachinesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State machine identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "State machine deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "StateMachine not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_NOT_FOUND": { "summary": "StateMachine not found", "value": { "error": { "code": "STATE_MACHINE_NOT_FOUND", "message": "StateMachine 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete state machine", "tags": [ "state-machines" ] } }, "/api/v1/statuses": { "get": { "description": "Returns a paginated list of statuses for an entity type, combining KRUZER base statuses and the caller account custom statuses.", "operationId": "StatusesController_list_v1", "parameters": [ { "required": true, "name": "entityType", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusListResponse" } } } }, "400": { "description": "Invalid query parameters (entityType, pagination).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List statuses", "tags": [ "statuses" ] }, "post": { "description": "Creates a new custom status within the caller account.", "operationId": "StatusesController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusCreate" } } } }, "responses": { "201": { "description": "Status created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "409": { "description": "A status with the same code already exists for the entity type, as a custom or KRUZER base status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_CODE_ALREADY_EXISTS": { "summary": "Duplicate status code", "value": { "error": { "code": "STATUS_CODE_ALREADY_EXISTS", "message": "Status with code \"QUALITY_CHECK\" already exists" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_INVALID_NATURE": { "summary": "Custom statuses only accept PROCESSING or ERROR natures", "value": { "error": { "code": "STATUS_INVALID_NATURE", "message": "custom statuses only accept PROCESSING or ERROR natures" } } }, "STATUS_INVALID_NATURE__1": { "summary": "ERROR nature is exclusive to FULFILLMENT_ORDER", "value": { "error": { "code": "STATUS_INVALID_NATURE", "message": "ERROR nature is only allowed for FULFILLMENT_ORDER statuses" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create status", "tags": [ "statuses" ] } }, "/api/v1/statuses/{id}": { "get": { "description": "Returns a status by its identifier.", "operationId": "StatusesController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Status identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Status found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Status not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_NOT_FOUND": { "summary": "Status not found", "value": { "error": { "code": "STATUS_NOT_FOUND", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch status", "tags": [ "statuses" ] }, "patch": { "description": "Partially updates a custom status by its identifier (label, color, active). The code and entity type are immutable. KRUZER base statuses cannot be modified.", "operationId": "StatusesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Status identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdate" } } } }, "responses": { "200": { "description": "Status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Status not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_NOT_FOUND": { "summary": "Status not found", "value": { "error": { "code": "STATUS_NOT_FOUND", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "The status cannot be deactivated while state machine transitions reference its code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_IN_USE": { "summary": "Status referenced by state machine transitions", "value": { "error": { "code": "STATUS_IN_USE", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a cannot be deleted because it is in use", "details": [ { "entity": "StateMachine", "count": 1 } ] } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_KRUZER_IMMUTABLE": { "summary": "KRUZER base statuses are read-only", "value": { "error": { "code": "STATUS_KRUZER_IMMUTABLE", "message": "KRUZER base statuses cannot be modified" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update status", "tags": [ "statuses" ] }, "delete": { "description": "Soft-deletes a custom status by its identifier. KRUZER base statuses cannot be deleted.", "operationId": "StatusesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Status identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Status deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Status not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_NOT_FOUND": { "summary": "Status not found", "value": { "error": { "code": "STATUS_NOT_FOUND", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "The status cannot be deleted while state machine transitions reference its code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_IN_USE": { "summary": "Status referenced by state machine transitions", "value": { "error": { "code": "STATUS_IN_USE", "message": "Status 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a cannot be deleted because it is in use", "details": [ { "entity": "StateMachine", "count": 1 } ] } } } } } } }, "422": { "description": "KRUZER base statuses cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATUS_KRUZER_IMMUTABLE": { "summary": "KRUZER base statuses are read-only", "value": { "error": { "code": "STATUS_KRUZER_IMMUTABLE", "message": "KRUZER base statuses cannot be modified" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete status", "tags": [ "statuses" ] } }, "/api/v1/strategies/{strategyId}/price-lists": { "get": { "description": "Returns a paginated list of price list bindings for the given strategy. Each item joins the referenced PriceList name. Default sort is priority ascending (lowest = primary).", "operationId": "StrategyPriceListsController_list_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "required": false, "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "required": false, "name": "price_list_id", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "page", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "limit", "in": "query", "schema": { "type": "number" } }, { "required": false, "name": "sortBy", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "sortOrder", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of strategy price lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, or filter values).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "Strategy not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "List strategy price lists", "tags": [ "strategy-price-lists" ] }, "post": { "description": "Binds an existing PriceList to the given Strategy. The composite key (strategy, price_list) is unique per active binding.", "operationId": "StrategyPriceListsController_create_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListCreate" } } } }, "responses": { "201": { "description": "Strategy price list created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListCreateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, PriceList) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "409": { "description": "A non-deleted binding already exists for this (strategy, price_list) pair.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_PRICE_LIST_COMPOSITE_KEY_ALREADY_EXISTS": { "summary": "Composite key already in use", "value": { "error": { "code": "STRATEGY_PRICE_LIST_COMPOSITE_KEY_ALREADY_EXISTS", "message": "StrategyPriceList with composite_key \"/\" already exists" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Create strategy price list", "tags": [ "strategy-price-lists" ] } }, "/api/v1/strategies/{strategyId}/price-lists/{id}": { "get": { "description": "Returns a strategy price list binding by its identifier.", "operationId": "StrategyPriceListsController_find_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "200": { "description": "Strategy price list found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListFindResponse" } } } }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyPriceList) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_PRICE_LIST_NOT_FOUND": { "summary": "StrategyPriceList not found", "value": { "error": { "code": "STRATEGY_PRICE_LIST_NOT_FOUND", "message": "StrategyPriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Fetch strategy price list", "tags": [ "strategy-price-lists" ] }, "patch": { "description": "Partially updates a strategy price list. Only active is mutable; strategy_id and price_list_id are immutable.", "operationId": "StrategyPriceListsController_update_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListUpdate" } } } }, "responses": { "200": { "description": "Strategy price list updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListUpdateResponse" } } } }, "400": { "description": "Request payload, query string, or path parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyPriceList) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_PRICE_LIST_NOT_FOUND": { "summary": "StrategyPriceList not found", "value": { "error": { "code": "STRATEGY_PRICE_LIST_NOT_FOUND", "message": "StrategyPriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Update strategy price list", "tags": [ "strategy-price-lists" ] }, "delete": { "description": "Soft-deletes a strategy price list binding by its identifier.", "operationId": "StrategyPriceListsController_remove_v1", "parameters": [ { "name": "strategyId", "required": true, "in": "path", "description": "Parent strategy identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy price list identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a" } } ], "responses": { "204": { "description": "Strategy price list deleted." }, "400": { "description": "Path parameter is not a UUID v4.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "One or more fields failed validation", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "code", "reason": "code must match /^[A-Z0-9_]{2,50}$/" }, { "field": "name", "reason": "name must be at least 3 characters long" } ] } } }, "VALIDATION_ERROR__1": { "summary": "Path parameter is not a UUID v4", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID v4" } ] } } } } } } }, "401": { "description": "Authentication is missing, malformed, expired, or refers to a session that is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "UNAUTHORIZED": { "summary": "Authentication required or invalid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } } } } } }, "403": { "description": "The caller is authenticated but lacks the required permission for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FORBIDDEN": { "summary": "Caller lacks the required permission", "value": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } } } }, "404": { "description": "One of the referenced resources (Strategy, StrategyPriceList) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } }, "STRATEGY_PRICE_LIST_NOT_FOUND": { "summary": "StrategyPriceList not found", "value": { "error": { "code": "STRATEGY_PRICE_LIST_NOT_FOUND", "message": "StrategyPriceList 6f0d9c5a-7d4d-4f6a-9b6a-2b5a0b5a0b5a not found" } } } } } } }, "500": { "description": "Unexpected server error. The response body never leaks internal details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "INTERNAL_ERROR": { "summary": "Unhandled server-side failure", "value": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } } } }, "security": [ { "basic": [] }, { "bearer": [] } ], "summary": "Delete strategy price list", "tags": [ "strategy-price-lists" ] } } }, "info": { "title": "OMS API", "description": "HTTP API for the Kruzer Order Management System.\n\nAuthentication is required for every domain endpoint and supports two schemes: Bearer JWT (issued by the IAM service for human users) and HTTP Basic (service accounts). Public endpoints (health probes) are unauthenticated.", "version": "1.0", "contact": {} }, "tags": [ { "name": "health", "description": "Liveness and readiness probes for orchestrators." }, { "name": "carriers", "description": "Logistics carriers configured per tenant." }, { "name": "channels", "description": "Sales channels and storefronts integrated with the OMS." }, { "name": "clusters", "description": "Distribution clusters that group operators by region or strategy." }, { "name": "customers", "description": "Customers registered manually or projected from ERP/orders, scoped per tenant." }, { "name": "customer-addresses", "description": "Delivery/billing addresses embedded in a customer, managed under the customer resource." }, { "name": "delivery-modalities", "description": "Delivery modalities offered to end customers (e.g. express, scheduled)." }, { "name": "delivery-types", "description": "Delivery types describing the underlying fulfillment mechanic." }, { "name": "freight-types", "description": "Freight types used when computing shipping cost and SLA." }, { "name": "inventory", "description": "Inventory ingestion endpoint consumed by ERP/WMS (SNAPSHOT and DELTA modes)." }, { "name": "inventory-movements", "description": "Inventory movement history (paginated, filterable audit trail of SNAPSHOT and DELTA records)." }, { "name": "operators", "description": "Operators (warehouses, stores) responsible for fulfilling orders." }, { "name": "payment-methods", "description": "Payment methods accepted per tenant." }, { "name": "price-lists", "description": "Price list headers (catalog of pricing tables per tenant)." }, { "name": "product-categories", "description": "Manual SKU groupings consumed by Catalog, Promotions and Coupons engines." }, { "name": "products", "description": "Product catalog projected from upstream PIM." }, { "name": "state-machines", "description": "State machines describing the lifecycle of orders and fulfillment orders per tenant." }, { "name": "statuses", "description": "Status catalog combining KRUZER base statuses and tenant custom statuses." }, { "name": "strategies", "description": "Fulfillment strategies that drive operator selection." }, { "name": "strategy-carriers", "description": "Carrier preferences attached to each fulfillment strategy." }, { "name": "strategy-price-lists", "description": "Price list bindings (primary + fallbacks) attached to each fulfillment strategy." }, { "name": "permissions", "description": "Authenticated permission catalog scoped to the caller account." }, { "name": "core-permissions", "description": "Internal core-permission catalog consumed by the IAM service." } ], "servers": [ { "url": "https://oms-api.{tenant}.krzlabs.io", "description": "Ambiente Kruzer Labs (por tenant)", "variables": { "tenant": { "default": "{{tenant}}", "description": "Slug do tenant da sua organização. Substitua `{{tenant}}` pelo identificador fornecido pela Kruzer no momento da contratação." } } }, { "url": "http://localhost:3000", "description": "Desenvolvimento local" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "IAM-issued JWT." }, "basic": { "type": "http", "scheme": "basic", "description": "Service account credentials." } }, "schemas": { "ErrorBody": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, machine-readable error code emitted by the domain or application layer.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable summary of the error.", "example": "name must be at least 3 characters long" }, "details": { "type": "object", "description": "Optional structured payload (e.g. validation field errors, dependency list for EntityInUseError).", "additionalProperties": true } }, "required": [ "code", "message" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "error" ] }, "CarrierListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } }, "required": [ "tracking", "same_day", "returns" ] }, "default_freight_rules": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "default_operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "description", "active", "capabilities", "default_freight_rules", "default_operating_hours", "created_at", "updated_at" ] }, "PaginationMetaResponse": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of records that match the filter.", "example": 42 }, "pages": { "type": "number", "description": "Number of pages available.", "example": 3 }, "current_page": { "type": "number", "description": "Page number returned in this response.", "example": 1 }, "next_page": { "type": "number", "nullable": true, "description": "Next page number, or null when on the last page.", "example": 2 }, "previous_page": { "type": "number", "nullable": true, "description": "Previous page number, or null when on the first page.", "example": null }, "limit": { "type": "number", "description": "Page size used to compute pagination.", "example": 20 } }, "required": [ "total", "pages", "current_page", "next_page", "previous_page", "limit" ] }, "CarrierListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "CarrierCapabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } }, "CarrierFreightRules": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "CarrierOperatingHour": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] }, "CarrierCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "active": { "type": "boolean" }, "capabilities": { "$ref": "#/components/schemas/CarrierCapabilities" }, "default_freight_rules": { "$ref": "#/components/schemas/CarrierFreightRules" }, "default_operating_hours": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierOperatingHour" } }, "metadata": { "type": "object" } }, "required": [ "code", "name", "active" ] }, "CarrierCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } }, "required": [ "tracking", "same_day", "returns" ] }, "default_freight_rules": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "default_operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "active", "capabilities", "default_freight_rules", "default_operating_hours", "metadata", "created_at", "updated_at" ] }, "CarrierFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } }, "required": [ "tracking", "same_day", "returns" ] }, "default_freight_rules": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "default_operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "active", "capabilities", "default_freight_rules", "default_operating_hours", "metadata", "created_at", "updated_at" ] }, "CarrierUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "active": { "type": "boolean" }, "capabilities": { "$ref": "#/components/schemas/CarrierCapabilities" }, "default_freight_rules": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CarrierFreightRules" } ] }, "default_operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/CarrierOperatingHour" } }, "metadata": { "type": "object", "nullable": true } } }, "CarrierUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } }, "required": [ "tracking", "same_day", "returns" ] }, "default_freight_rules": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "default_operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "active", "capabilities", "default_freight_rules", "default_operating_hours", "metadata", "created_at", "updated_at" ] }, "ChannelListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "type", "active", "created_at", "updated_at" ] }, "ChannelListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "ChannelCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "type": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } }, "required": [ "code", "name", "type" ] }, "ChannelCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "type", "active", "metadata", "created_at", "updated_at" ] }, "ChannelFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "type", "active", "metadata", "created_at", "updated_at" ] }, "ChannelUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "type": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } } }, "ChannelUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ] }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "type", "active", "metadata", "created_at", "updated_at" ] }, "StrategyCarrierListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "strategy_id": { "type": "string" }, "carrier_id": { "type": "string" }, "delivery_type_codes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "holidays_open": { "type": "boolean" }, "delivery_modalities": { "type": "array", "items": { "type": "string" } }, "channel_codes": { "type": "array", "items": { "type": "string" } }, "coverage_area": { "type": "object", "nullable": true }, "freight_rules": { "type": "object", "nullable": true }, "operating_hours": { "nullable": true, "type": "array", "items": { "type": "object" } }, "holidays_hours": { "type": "object", "nullable": true }, "carrier": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "carrier_id", "delivery_type_codes", "active", "holidays_open", "delivery_modalities", "channel_codes", "coverage_area", "freight_rules", "operating_hours", "holidays_hours", "carrier", "created_at", "updated_at" ] }, "StrategyCarrierListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyCarrierListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "CoverageCity": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" } }, "required": [ "city", "state" ] }, "CoverageZipRange": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{8}$" }, "end": { "type": "string", "pattern": "^\\d{8}$" } }, "required": [ "start", "end" ] }, "PolygonGeometry": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Polygon" ] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } } }, "required": [ "type", "coordinates" ] }, "CoverageArea": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "STATES", "CITIES", "ZIP_RANGES", "POLYGON" ] }, "states": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "cities": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CoverageCity" } }, "ranges": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CoverageZipRange" } }, "polygon": { "$ref": "#/components/schemas/PolygonGeometry" } }, "required": [ "type" ] }, "StrategyCarrierFreightRules": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "StrategyCarrierOperatingHour": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] }, "StrategyCarrierHolidaysHours": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] }, "StrategyCarrierCreate": { "type": "object", "properties": { "carrier_id": { "type": "string" }, "delivery_type_codes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "holidays_open": { "type": "boolean" }, "delivery_modalities": { "type": "array", "items": { "type": "string" } }, "channel_codes": { "type": "array", "items": { "type": "string" } }, "coverage_area": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CoverageArea" } ] }, "freight_rules": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierFreightRules" } ] }, "operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StrategyCarrierOperatingHour" } }, "holidays_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierHolidaysHours" } ] }, "metadata": { "type": "object", "nullable": true } }, "required": [ "carrier_id", "delivery_type_codes" ] }, "StrategyCarrierCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "carrier_id": { "type": "string" }, "delivery_type_codes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "holidays_open": { "type": "boolean" }, "delivery_modalities": { "type": "array", "items": { "type": "string" } }, "channel_codes": { "type": "array", "items": { "type": "string" } }, "coverage_area": { "type": "object", "nullable": true }, "freight_rules": { "type": "object", "properties": { "value": { "type": "object", "nullable": true }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "operating_hours": { "type": "object", "properties": { "value": { "nullable": true, "type": "array", "items": { "type": "object" } }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "holidays_hours": { "type": "object", "nullable": true }, "carrier_active": { "type": "boolean" }, "carrier": { "type": "object" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "carrier_id", "delivery_type_codes", "active", "holidays_open", "delivery_modalities", "channel_codes", "coverage_area", "freight_rules", "operating_hours", "holidays_hours", "carrier_active", "carrier", "metadata", "created_at", "updated_at" ] }, "StrategyCarrierFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "carrier_id": { "type": "string" }, "delivery_type_codes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "holidays_open": { "type": "boolean" }, "delivery_modalities": { "type": "array", "items": { "type": "string" } }, "channel_codes": { "type": "array", "items": { "type": "string" } }, "coverage_area": { "type": "object", "nullable": true }, "freight_rules": { "type": "object", "properties": { "value": { "type": "object", "nullable": true }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "operating_hours": { "type": "object", "properties": { "value": { "nullable": true, "type": "array", "items": { "type": "object" } }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "holidays_hours": { "type": "object", "nullable": true }, "carrier_active": { "type": "boolean" }, "carrier": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "carrier_id", "delivery_type_codes", "active", "holidays_open", "delivery_modalities", "channel_codes", "coverage_area", "freight_rules", "operating_hours", "holidays_hours", "carrier_active", "carrier", "metadata", "created_at", "updated_at" ] }, "StrategyCarrierUpdate": { "type": "object", "properties": { "active": { "type": "boolean" }, "holidays_open": { "type": "boolean" }, "delivery_type_codes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "delivery_modalities": { "type": "array", "items": { "type": "string" } }, "channel_codes": { "type": "array", "items": { "type": "string" } }, "coverage_area": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CoverageArea" } ] }, "freight_rules": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierFreightRules" } ] }, "operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StrategyCarrierOperatingHour" } }, "holidays_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierHolidaysHours" } ] }, "metadata": { "type": "object", "nullable": true } } }, "StrategyCarrierUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "carrier_id": { "type": "string" }, "delivery_type_codes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "holidays_open": { "type": "boolean" }, "delivery_modalities": { "type": "array", "items": { "type": "string" } }, "channel_codes": { "type": "array", "items": { "type": "string" } }, "coverage_area": { "type": "object", "nullable": true }, "freight_rules": { "type": "object", "properties": { "value": { "type": "object", "nullable": true }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "operating_hours": { "type": "object", "properties": { "value": { "nullable": true, "type": "array", "items": { "type": "object" } }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "holidays_hours": { "type": "object", "nullable": true }, "carrier_active": { "type": "boolean" }, "carrier": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "carrier_id", "delivery_type_codes", "active", "holidays_open", "delivery_modalities", "channel_codes", "coverage_area", "freight_rules", "operating_hours", "holidays_hours", "carrier_active", "carrier", "metadata", "created_at", "updated_at" ] }, "DeliveryTypeListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "active", "created_at", "updated_at" ] }, "DeliveryTypeListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryTypeListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "DeliveryTypeCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "metadata": { "type": "object" } }, "required": [ "code", "name" ] }, "DeliveryTypeCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "DeliveryTypeFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "DeliveryTypeUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } } }, "DeliveryTypeUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "StrategyListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "STORE", "DC", "DARK_STORE", "SELLER", "FULFILLMENT_NODE" ] }, "category": { "type": "string", "enum": [ "SALES", "OPERATIONS", "SALES_AND_OPERATIONS" ] }, "active": { "type": "boolean" }, "sfs": { "type": "boolean" }, "endless_aisle": { "type": "boolean" }, "operates_on_holidays": { "type": "boolean" }, "cluster_id": { "type": "string", "nullable": true }, "cluster": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string", "nullable": true } }, "required": [ "name", "color" ] }, "color": { "type": "string", "nullable": true }, "daily_capacity": { "type": "number" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zip_code": { "type": "string" } }, "required": [ "street", "number", "complement", "district", "city", "state", "country", "zip_code" ] }, "contact": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "required": [ "name", "email", "phone" ] }, "operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day", "is_24h", "opens_at", "closes_at" ] } }, "holiday_operating_hours": { "type": "object", "properties": { "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "is_24h", "opens_at", "closes_at" ] }, "tags": { "nullable": true, "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "description", "type", "category", "active", "sfs", "endless_aisle", "operates_on_holidays", "cluster_id", "cluster", "color", "daily_capacity", "address", "contact", "operating_hours", "holiday_operating_hours", "tags", "created_at", "updated_at" ] }, "StrategyListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "StrategyAddress": { "type": "object", "properties": { "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zip_code": { "type": "string" } }, "required": [ "street", "number", "district", "city", "state", "country", "zip_code" ] }, "StrategyContact": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "phone": { "type": "string", "nullable": true } } }, "StrategyOperatingHour": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day" ] }, "StrategyHolidayHours": { "type": "object", "properties": { "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } } }, "StrategyCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "type": { "type": "string", "enum": [ "STORE", "DC", "DARK_STORE", "SELLER", "FULFILLMENT_NODE" ] }, "category": { "type": "string", "enum": [ "SALES", "OPERATIONS", "SALES_AND_OPERATIONS" ] }, "active": { "type": "boolean" }, "daily_capacity": { "type": "number", "minimum": 1 }, "sfs": { "type": "boolean" }, "endless_aisle": { "type": "boolean" }, "operates_on_holidays": { "type": "boolean" }, "cluster_id": { "type": "string", "nullable": true }, "color": { "type": "string" }, "address": { "$ref": "#/components/schemas/StrategyAddress" }, "contact": { "$ref": "#/components/schemas/StrategyContact" }, "operating_hours": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyOperatingHour" } }, "holiday_operating_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyHolidayHours" } ] }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "metadata": { "type": "object" } }, "required": [ "code", "name", "type", "category", "active", "daily_capacity" ] }, "StrategyCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "STORE", "DC", "DARK_STORE", "SELLER", "FULFILLMENT_NODE" ] }, "category": { "type": "string", "enum": [ "SALES", "OPERATIONS", "SALES_AND_OPERATIONS" ] }, "active": { "type": "boolean" }, "sfs": { "type": "boolean" }, "endless_aisle": { "type": "boolean" }, "operates_on_holidays": { "type": "boolean" }, "cluster_id": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "daily_capacity": { "type": "number" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zip_code": { "type": "string" } }, "required": [ "street", "number", "complement", "district", "city", "state", "country", "zip_code" ] }, "contact": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "required": [ "name", "email", "phone" ] }, "operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day", "is_24h", "opens_at", "closes_at" ] } }, "holiday_operating_hours": { "type": "object", "properties": { "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "is_24h", "opens_at", "closes_at" ] }, "tags": { "nullable": true, "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "type", "category", "active", "sfs", "endless_aisle", "operates_on_holidays", "cluster_id", "color", "daily_capacity", "address", "contact", "operating_hours", "holiday_operating_hours", "tags", "metadata", "created_at", "updated_at" ] }, "StrategyFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "STORE", "DC", "DARK_STORE", "SELLER", "FULFILLMENT_NODE" ] }, "category": { "type": "string", "enum": [ "SALES", "OPERATIONS", "SALES_AND_OPERATIONS" ] }, "active": { "type": "boolean" }, "sfs": { "type": "boolean" }, "endless_aisle": { "type": "boolean" }, "operates_on_holidays": { "type": "boolean" }, "cluster_id": { "type": "string", "nullable": true }, "cluster": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string", "nullable": true } }, "required": [ "name", "color" ] }, "color": { "type": "string", "nullable": true }, "daily_capacity": { "type": "number" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zip_code": { "type": "string" } }, "required": [ "street", "number", "complement", "district", "city", "state", "country", "zip_code" ] }, "contact": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "required": [ "name", "email", "phone" ] }, "operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day", "is_24h", "opens_at", "closes_at" ] } }, "holiday_operating_hours": { "type": "object", "properties": { "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "is_24h", "opens_at", "closes_at" ] }, "tags": { "nullable": true, "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "type", "category", "active", "sfs", "endless_aisle", "operates_on_holidays", "cluster_id", "cluster", "color", "daily_capacity", "address", "contact", "operating_hours", "holiday_operating_hours", "tags", "metadata", "created_at", "updated_at" ] }, "StrategyUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "type": { "type": "string", "enum": [ "STORE", "DC", "DARK_STORE", "SELLER", "FULFILLMENT_NODE" ] }, "category": { "type": "string", "enum": [ "SALES", "OPERATIONS", "SALES_AND_OPERATIONS" ] }, "active": { "type": "boolean" }, "daily_capacity": { "type": "number", "minimum": 1 }, "sfs": { "type": "boolean" }, "endless_aisle": { "type": "boolean" }, "operates_on_holidays": { "type": "boolean" }, "cluster_id": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyAddress" } ] }, "contact": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyContact" } ] }, "operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StrategyOperatingHour" } }, "holiday_operating_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyHolidayHours" } ] }, "tags": { "nullable": true, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "metadata": { "type": "object", "nullable": true } } }, "StrategyUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "STORE", "DC", "DARK_STORE", "SELLER", "FULFILLMENT_NODE" ] }, "category": { "type": "string", "enum": [ "SALES", "OPERATIONS", "SALES_AND_OPERATIONS" ] }, "active": { "type": "boolean" }, "sfs": { "type": "boolean" }, "endless_aisle": { "type": "boolean" }, "operates_on_holidays": { "type": "boolean" }, "cluster_id": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "daily_capacity": { "type": "number" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zip_code": { "type": "string" } }, "required": [ "street", "number", "complement", "district", "city", "state", "country", "zip_code" ] }, "contact": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "required": [ "name", "email", "phone" ] }, "operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day", "is_24h", "opens_at", "closes_at" ] } }, "holiday_operating_hours": { "type": "object", "properties": { "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "is_24h", "opens_at", "closes_at" ] }, "tags": { "nullable": true, "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "type", "category", "active", "sfs", "endless_aisle", "operates_on_holidays", "cluster_id", "color", "daily_capacity", "address", "contact", "operating_hours", "holiday_operating_hours", "tags", "metadata", "created_at", "updated_at" ] }, "ClusterListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "strategies_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "description", "color", "active", "strategies_count", "created_at", "updated_at" ] }, "ClusterListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "ClusterCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "color": { "type": "string" }, "metadata": { "type": "object" } }, "required": [ "code", "name" ] }, "ClusterCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "color", "active", "metadata", "created_at", "updated_at" ] }, "ClusterFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "color", "active", "metadata", "created_at", "updated_at" ] }, "ClusterUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "color": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } } }, "ClusterUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "color", "active", "metadata", "created_at", "updated_at" ] }, "StrategyChannelListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "strategy_id": { "type": "string" }, "channel_code": { "type": "string" }, "active": { "type": "boolean" }, "inventory_allocation": { "type": "object", "nullable": true }, "price_list_code": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "nullable": true }, "channel": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "enum": [ "MARKETPLACE", "ECOMMERCE", "POS", "TELEVENDAS", "WHATSAPP", "APP" ], "type": "string" } }, "required": [ "name", "type" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_code", "delivery_promise", "channel", "created_at", "updated_at" ] }, "StrategyChannelListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyChannelListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "InventoryAllocation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FIXED", "PERCENTAGE" ] }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "DeliveryPromise": { "type": "object", "properties": { "value": { "type": "number", "minimum": 1 }, "unit": { "type": "string", "enum": [ "MINUTES", "HOURS", "DAYS" ] } }, "required": [ "value", "unit" ] }, "StrategyChannelCreate": { "type": "object", "properties": { "channel_code": { "type": "string" }, "active": { "type": "boolean" }, "inventory_allocation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryAllocation" } ] }, "price_list_code": { "type": "string", "nullable": true }, "delivery_promise": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromise" } ] }, "metadata": { "type": "object", "nullable": true } }, "required": [ "channel_code" ] }, "StrategyChannelCreateResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "strategy_id": { "type": "string" }, "channel_code": { "type": "string" }, "active": { "type": "boolean" }, "inventory_allocation": { "type": "object", "nullable": true }, "price_list_code": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_code", "delivery_promise", "created_at", "updated_at" ] }, "StrategyChannelFindResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "strategy_id": { "type": "string" }, "channel_code": { "type": "string" }, "active": { "type": "boolean" }, "inventory_allocation": { "type": "object", "nullable": true }, "price_list_code": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_code", "delivery_promise", "created_at", "updated_at" ] }, "StrategyChannelUpdate": { "type": "object", "properties": { "active": { "type": "boolean" }, "inventory_allocation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryAllocation" } ] }, "price_list_code": { "type": "string", "nullable": true }, "delivery_promise": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromise" } ] }, "metadata": { "type": "object", "nullable": true } } }, "StrategyChannelUpdateResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "strategy_id": { "type": "string" }, "channel_code": { "type": "string" }, "active": { "type": "boolean" }, "inventory_allocation": { "type": "object", "nullable": true }, "price_list_code": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_code", "delivery_promise", "created_at", "updated_at" ] }, "CustomerListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "enum": [ "CPF", "CNPJ" ], "type": "string" } }, "required": [ "value", "type" ] }, "type": { "type": "string", "enum": [ "PF", "PJ" ] }, "origin": { "type": "string", "enum": [ "ERP", "ORDER", "MANUAL" ] }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true }, "social_name": { "type": "string", "nullable": true }, "phone_is_whatsapp": { "type": "boolean" }, "total_orders": { "type": "number" }, "total_spent": { "type": "number" }, "avg_ticket": { "type": "number" }, "first_order_at": { "type": "string", "nullable": true }, "last_order_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "origin", "name", "email", "phone", "birth_date", "social_name", "phone_is_whatsapp", "total_orders", "total_spent", "avg_ticket", "first_order_at", "last_order_at", "created_at", "updated_at" ] }, "CustomerListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "CustomerCreate": { "type": "object", "properties": { "birth_date": { "type": "string", "example": "1990-05-20", "description": "Date of birth (PF only). Not allowed for PJ customers." }, "social_name": { "type": "string", "nullable": true, "maxLength": 200 }, "phone_is_whatsapp": { "type": "boolean" }, "document": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "email": { "type": "string", "nullable": true, "maxLength": 254 }, "phone": { "type": "string", "nullable": true, "maxLength": 30 } }, "required": [ "document", "name" ] }, "CustomerCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "enum": [ "CPF", "CNPJ" ], "type": "string" } }, "required": [ "value", "type" ] }, "type": { "type": "string", "enum": [ "PF", "PJ" ] }, "origin": { "type": "string", "enum": [ "ERP", "ORDER", "MANUAL" ] }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true }, "social_name": { "type": "string", "nullable": true }, "phone_is_whatsapp": { "type": "boolean" }, "total_orders": { "type": "number" }, "total_spent": { "type": "number" }, "avg_ticket": { "type": "number" }, "first_order_at": { "type": "string", "nullable": true }, "last_order_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "origin", "name", "email", "phone", "birth_date", "social_name", "phone_is_whatsapp", "total_orders", "total_spent", "avg_ticket", "first_order_at", "last_order_at", "created_at", "updated_at" ] }, "CustomerFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "enum": [ "CPF", "CNPJ" ], "type": "string" } }, "required": [ "value", "type" ] }, "type": { "type": "string", "enum": [ "PF", "PJ" ] }, "origin": { "type": "string", "enum": [ "ERP", "ORDER", "MANUAL" ] }, "external_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true }, "social_name": { "type": "string", "nullable": true }, "phone_is_whatsapp": { "type": "boolean" }, "total_orders": { "type": "number" }, "total_spent": { "type": "number" }, "avg_ticket": { "type": "number" }, "first_order_at": { "type": "string", "nullable": true }, "last_order_at": { "type": "string", "nullable": true }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "enum": [ "SHIPPING", "BILLING", "OTHER" ], "type": "string" }, "zip_code": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "is_default": { "type": "boolean" }, "source": { "enum": [ "MANUAL", "ERP" ], "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "type", "zip_code", "street", "number", "complement", "district", "city", "state", "country", "is_default", "source", "created_at", "updated_at" ] } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "origin", "external_id", "name", "email", "phone", "birth_date", "social_name", "phone_is_whatsapp", "total_orders", "total_spent", "avg_ticket", "first_order_at", "last_order_at", "addresses", "created_at", "updated_at" ] }, "CustomerUpdate": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "maxLength": 254 }, "phone": { "type": "string", "nullable": true, "maxLength": 30 }, "birth_date": { "type": "string", "nullable": true, "example": "1990-05-20" }, "social_name": { "type": "string", "nullable": true, "maxLength": 200 }, "phone_is_whatsapp": { "type": "boolean" }, "name": { "type": "string", "minLength": 2, "maxLength": 200 } } }, "CustomerUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "enum": [ "CPF", "CNPJ" ], "type": "string" } }, "required": [ "value", "type" ] }, "type": { "type": "string", "enum": [ "PF", "PJ" ] }, "origin": { "type": "string", "enum": [ "ERP", "ORDER", "MANUAL" ] }, "external_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true }, "social_name": { "type": "string", "nullable": true }, "phone_is_whatsapp": { "type": "boolean" }, "total_orders": { "type": "number" }, "total_spent": { "type": "number" }, "avg_ticket": { "type": "number" }, "first_order_at": { "type": "string", "nullable": true }, "last_order_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "origin", "external_id", "name", "email", "phone", "birth_date", "social_name", "phone_is_whatsapp", "total_orders", "total_spent", "avg_ticket", "first_order_at", "last_order_at", "created_at", "updated_at" ] }, "AddCustomerAddress": { "type": "object", "properties": { "complement": { "type": "string", "nullable": true }, "is_default": { "type": "boolean", "default": false }, "type": { "type": "string", "enum": [ "SHIPPING", "BILLING", "OTHER" ] }, "zip_code": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } }, "required": [ "type", "zip_code", "street", "number", "district", "city", "state", "country" ] }, "AddCustomerAddressResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "SHIPPING", "BILLING", "OTHER" ] }, "zip_code": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "is_default": { "type": "boolean" }, "source": { "type": "string", "enum": [ "MANUAL", "ERP" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "type", "zip_code", "street", "number", "complement", "district", "city", "state", "country", "is_default", "source", "created_at", "updated_at" ] }, "CustomerAddressUpdate": { "type": "object", "properties": { "complement": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "SHIPPING", "BILLING", "OTHER" ] }, "zip_code": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } }, "required": [ "type", "zip_code", "street", "number", "district", "city", "state", "country" ] }, "CustomerAddressUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "SHIPPING", "BILLING", "OTHER" ] }, "zip_code": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "is_default": { "type": "boolean" }, "source": { "type": "string", "enum": [ "MANUAL", "ERP" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "type", "zip_code", "street", "number", "complement", "district", "city", "state", "country", "is_default", "source", "created_at", "updated_at" ] }, "SetDefaultCustomerAddressResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "SHIPPING", "BILLING", "OTHER" ] }, "zip_code": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "is_default": { "type": "boolean" }, "source": { "type": "string", "enum": [ "MANUAL", "ERP" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "type", "zip_code", "street", "number", "complement", "district", "city", "state", "country", "is_default", "source", "created_at", "updated_at" ] }, "FreightTypeListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "active", "created_at", "updated_at" ] }, "FreightTypeListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FreightTypeListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "FreightTypeCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "metadata": { "type": "object" } }, "required": [ "code", "name" ] }, "FreightTypeCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "FreightTypeFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "FreightTypeUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } } }, "FreightTypeUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "InventorySnapshotItemIngest": { "type": "object", "properties": { "blocked": { "type": "number", "minimum": 0, "description": "Quantidade bloqueada na posição (inteiro >= 0).", "example": 5 }, "onHand": { "type": "number", "minimum": 0, "description": "Quantidade física disponível na posição (inteiro >= 0).", "example": 150 }, "safetyStock": { "type": "number", "minimum": 0, "description": "Estoque de segurança configurado (inteiro >= 0).", "example": 10 }, "sku": { "type": "string", "description": "SKU do produto.", "example": "SKU-001" }, "strategyCode": { "type": "string", "description": "Código da strategy (posição de estoque).", "example": "loja-barra" } }, "required": [ "blocked", "onHand", "safetyStock", "sku", "strategyCode" ] }, "InventorySnapshotIngest": { "type": "object", "properties": { "items": { "minItems": 1, "description": "Batch de posições absolutas (1..5000). Sobrescreve onHand, blocked e safetyStock da posição.", "type": "array", "items": { "$ref": "#/components/schemas/InventorySnapshotItemIngest" } }, "updateType": { "type": "string", "enum": [ "SNAPSHOT", "DELTA" ], "description": "Discriminador do modo de ingestão. Para snapshot, deve ser exatamente \"SNAPSHOT\".", "example": "SNAPSHOT" } }, "required": [ "items", "updateType" ] }, "InventoryDeltaItemIngest": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Identificador único da movimentação no sistema origem. Usado como chave de dedup no consumer.", "example": "evt-9a8b7c6d" }, "quantity": { "type": "number", "description": "Variação inteira a aplicar em onHand. Pode ser negativa (saída) ou positiva (entrada).", "example": -2 }, "reason": { "enum": [ "ADJUSTMENT", "ERP_SYNC", "ORDER_RELEASED", "ORDER_RESERVED", "POS_SALE", "RETURN_RECEIVED", "SAFETY_STOCK_CONFIG", "STOCK_SHORTAGE", "TRANSFER" ], "type": "string", "description": "Motivo da movimentação. Apenas reasons externos do ERP/WMS são aceitos aqui: POS_SALE, ADJUSTMENT, TRANSFER, ERP_SYNC.", "example": "POS_SALE" }, "sku": { "type": "string", "description": "SKU do produto.", "example": "SKU-001" }, "strategyCode": { "type": "string", "description": "Código da strategy (posição de estoque).", "example": "loja-barra" } }, "required": [ "eventId", "quantity", "reason", "sku", "strategyCode" ] }, "InventoryDeltaIngest": { "type": "object", "properties": { "items": { "minItems": 1, "description": "Batch de movimentações incrementais (1..1000). Incrementa/decrementa onHand da posição.", "type": "array", "items": { "$ref": "#/components/schemas/InventoryDeltaItemIngest" } }, "updateType": { "type": "string", "enum": [ "SNAPSHOT", "DELTA" ], "description": "Discriminador do modo de ingestão. Para delta, deve ser exatamente \"DELTA\".", "example": "DELTA" } }, "required": [ "items", "updateType" ] }, "InventoryListItemResponse": { "type": "object", "properties": { "last_snapshot_at": { "type": "string", "nullable": true, "description": "Last snapshot ingestion timestamp, or null." }, "product_name": { "type": "string", "nullable": true, "description": "Current product name resolved from the catalog by SKU; null for unregistered SKUs." }, "strategy_name": { "type": "string", "nullable": true, "description": "Current strategy name resolved by code; null when the strategy is not registered." }, "id": { "type": "string" }, "sku": { "type": "string" }, "strategy_code": { "type": "string" }, "on_hand": { "type": "number" }, "reserved": { "type": "number" }, "blocked": { "type": "number" }, "safety_stock": { "type": "number" }, "available": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "last_snapshot_at", "product_name", "strategy_name", "id", "sku", "strategy_code", "on_hand", "reserved", "blocked", "safety_stock", "available", "created_at", "updated_at" ] }, "InventoryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "InventoryIngestResponse": { "type": "object", "properties": { "accepted": { "type": "number", "description": "Number of items accepted and published to Kafka (always equals items.length on 202).", "example": 150 }, "correlation_id": { "type": "string", "description": "Batch correlation id (UUID v4) shared by every published event.", "example": "8f2a3b1c-7d6e-4f5a-9b8c-1d2e3f4a5b6c" }, "update_type": { "enum": [ "SNAPSHOT", "DELTA" ], "type": "string", "description": "Update mode of the accepted batch.", "example": "SNAPSHOT" } }, "required": [ "accepted", "correlation_id", "update_type" ] }, "InventoryMovementBalanceAfterResponse": { "type": "object", "properties": { "on_hand": { "type": "number" }, "reserved": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "on_hand", "reserved", "blocked" ] }, "InventoryMovementListItemResponse": { "type": "object", "properties": { "update_type": { "enum": [ "SNAPSHOT", "DELTA" ], "type": "string" }, "reason": { "enum": [ "ADJUSTMENT", "ERP_SYNC", "ORDER_RELEASED", "ORDER_RESERVED", "POS_SALE", "RETURN_RECEIVED", "SAFETY_STOCK_CONFIG", "STOCK_SHORTAGE", "TRANSFER" ], "type": "string" }, "balance_after": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryMovementBalanceAfterResponse" } ] }, "product_name": { "type": "string", "nullable": true, "description": "Product name at the time the movement was recorded; null for older documents and unregistered SKUs." }, "strategy_name": { "type": "string", "nullable": true, "description": "Strategy name at the time the movement was recorded; null for older documents and unregistered strategies." }, "id": { "type": "string" }, "event_id": { "type": "string" }, "sku": { "type": "string" }, "strategy_code": { "type": "string" }, "quantity": { "type": "number" }, "occurred_at": { "type": "string" } }, "required": [ "update_type", "reason", "balance_after", "product_name", "strategy_name", "id", "event_id", "sku", "strategy_code", "quantity", "occurred_at" ] }, "InventoryMovementsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryMovementListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "DeliveryModalityListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "active", "created_at", "updated_at" ] }, "DeliveryModalityListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryModalityListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "DeliveryModalityCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "metadata": { "type": "object" } }, "required": [ "code", "name" ] }, "DeliveryModalityCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "DeliveryModalityFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "DeliveryModalityUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } } }, "DeliveryModalityUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "OperatorListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "email": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "active", "email", "created_at", "updated_at" ] }, "OperatorListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "OperatorCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "email": { "type": "string", "nullable": true, "maxLength": 254, "format": "email" }, "metadata": { "type": "object", "nullable": true } }, "required": [ "code", "name" ] }, "OperatorCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "email": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "email", "metadata", "created_at", "updated_at" ] }, "OperatorFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "email": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "email", "metadata", "created_at", "updated_at" ] }, "OperatorUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "email": { "type": "string", "nullable": true, "maxLength": 254, "format": "email" }, "metadata": { "type": "object", "nullable": true } } }, "OperatorUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "email": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "email", "metadata", "created_at", "updated_at" ] }, "StrategyOperatorListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "operator_id": { "type": "string" }, "active": { "type": "boolean" }, "operator": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "operator_id", "active", "operator", "created_at", "updated_at" ] }, "StrategyOperatorListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyOperatorListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "StrategyOperatorCreate": { "type": "object", "properties": { "operator_id": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "operator_id" ] }, "StrategyOperatorCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "operator_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "operator_id", "active", "created_at", "updated_at" ] }, "StrategyOperatorFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "operator_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "operator_id", "active", "created_at", "updated_at" ] }, "StrategyOperatorUpdate": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "StrategyOperatorUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "operator_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "operator_id", "active", "created_at", "updated_at" ] }, "PaymentMethodListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "active", "created_at", "updated_at" ] }, "PaymentMethodListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "PaymentMethodCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "metadata": { "type": "object" } }, "required": [ "code", "name" ] }, "PaymentMethodCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "PaymentMethodFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "PaymentMethodUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } } }, "PaymentMethodUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "PriceListListItemResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceListItemListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "PriceListListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceListListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "PriceListCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } }, "required": [ "code", "name" ] }, "PriceListCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "PriceListFindResponse": { "type": "object", "properties": { "items_count": { "type": "number", "description": "Total of non-deleted items in the price list." }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "items_count", "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "PriceListItemListItemResponse": { "type": "object", "properties": { "product_name": { "type": "string", "nullable": true, "description": "Product name resolved from the catalog by sku." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "price_list_code": { "type": "string" }, "sku": { "type": "string" }, "cost_price": { "type": "number", "nullable": true }, "list_price": { "type": "number", "nullable": true }, "sale_price": { "type": "number" }, "start_date": { "type": "string", "nullable": true }, "end_date": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "product_name", "metadata", "id", "price_list_code", "sku", "cost_price", "list_price", "sale_price", "start_date", "end_date", "created_at", "updated_at" ] }, "UpsertPriceListItem": { "type": "object", "properties": { "sku": { "type": "string", "description": "Product SKU", "example": "SHAMPOO_X" }, "salePrice": { "type": "number", "minimum": 1, "description": "Sale price in cents (positive integer)", "example": 1290 }, "costPrice": { "type": "number", "nullable": true, "minimum": 0, "description": "Cost price in cents (non-negative integer) or null", "example": 800 }, "listPrice": { "type": "number", "nullable": true, "minimum": 0, "description": "List price in cents (non-negative integer) or null", "example": 1500 }, "startDate": { "type": "string", "nullable": true, "description": "Validity start date (ISO 8601) or null", "example": "2026-05-15T00:00:00.000Z" }, "endDate": { "type": "string", "nullable": true, "description": "Validity end date (ISO 8601) or null; must be greater than startDate when both are set", "example": null }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Free-form metadata propagated to the consumer", "example": { "source": "boletim_2026_05" } } }, "required": [ "sku", "salePrice" ] }, "UpsertPriceListItems": { "type": "object", "properties": { "items": { "minItems": 1, "description": "Batch of items to upsert (non-empty, capped by PRICING_BULK_MAX_ITEMS)", "type": "array", "items": { "$ref": "#/components/schemas/UpsertPriceListItem" } } }, "required": [ "items" ] }, "UpsertPriceListItemsResponse": { "type": "object", "properties": { "accepted": { "type": "number", "description": "Number of items accepted and published", "example": 1000 }, "rejected": { "type": "number", "description": "Number of items rejected (always 0 on 202)", "example": 0 }, "correlation_id": { "type": "string", "description": "Batch correlation id (UUID v4) shared by every published event", "example": "8f2a3b1c-7d6e-4f5a-9b8c-1d2e3f4a5b6c" } }, "required": [ "accepted", "rejected", "correlation_id" ] }, "PriceListUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } } }, "PriceListUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "active", "metadata", "created_at", "updated_at" ] }, "ProductCategoryListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "product_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "product_count", "created_at", "updated_at" ] }, "ProductCategoryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategoryListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "ProductCategoryCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": { "type": "string", "nullable": true, "maxLength": 240 }, "productIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "productIds" ] }, "ProductCategoryCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "product_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "product_count", "created_at", "updated_at" ] }, "ProductsByCategoryListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ean": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "sku", "name", "description", "ean", "active", "created_at", "updated_at" ] }, "ProductsByCategoryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductsByCategoryListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "ProductCategoryFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "product_ids": { "type": "array", "items": { "type": "string" } }, "product_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "product_ids", "product_count", "created_at", "updated_at" ] }, "ProductCategoryUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": { "type": "string", "nullable": true, "maxLength": 240 }, "productIds": { "type": "array", "items": { "type": "string" } } } }, "ProductCategoryUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "product_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "product_count", "created_at", "updated_at" ] }, "ProductListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ean": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "sku", "name", "description", "ean", "active", "created_at", "updated_at" ] }, "ProductListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "ProductIngest": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "description": { "type": "string", "nullable": true, "maxLength": 2000 }, "ean": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true } }, "required": [ "sku", "name", "ean" ] }, "ProductIngestResponse": { "type": "object", "properties": { "data": { "type": "object" }, "created": { "type": "boolean" } }, "required": [ "data", "created" ] }, "ProductFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ean": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "sku", "name", "description", "ean", "active", "metadata", "created_at", "updated_at" ] }, "PromotionValidity": { "type": "object", "properties": { "starts_at": { "type": "string" }, "ends_at": { "type": "string", "nullable": true }, "recurring_weekdays": { "type": "array", "items": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ] } } }, "required": [ "starts_at", "recurring_weekdays" ] }, "PromotionEligibility": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "ALL", "ONLY", "EXCEPT" ] }, "cluster_ids": { "type": "array", "items": { "type": "string" } }, "strategy_ids": { "type": "array", "items": { "type": "string" } }, "apply_to_all_channels": { "type": "boolean" }, "channel_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "scope", "cluster_ids", "strategy_ids", "apply_to_all_channels", "channel_ids" ] }, "PromotionBenefit": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DISCOUNT", "SHIPPING", "GIFT" ] }, "kind": { "type": "string" }, "value": { "type": "number" }, "apply_by": { "type": "string", "enum": [ "CART", "ITEM" ] }, "quantity": { "type": "number" }, "product_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ] }, "PromotionItemRestriction": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "PRODUCT", "CATEGORY" ] }, "operator": { "type": "string", "enum": [ "IN", "NOT_IN" ] }, "values": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "dimension", "operator", "values" ] }, "PromotionCondition": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ORDER_VALUE", "SHIPPING_TYPE", "PAYMENT_METHOD", "INSTALLMENTS" ] }, "min": { "type": "number" }, "max": { "type": "number" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ] }, "PromotionEligibleItemsLimit": { "type": "object", "properties": { "limit": { "type": "number" }, "count_by": { "type": "string", "enum": [ "ORDER", "PRODUCT" ] } }, "required": [ "limit", "count_by" ] }, "PromotionUsageLimits": { "type": "object", "properties": { "per_customer": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "eligible_items": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/PromotionEligibleItemsLimit" } ] } } }, "PromotionAccumulation": { "type": "object", "properties": { "with_discount_promotions": { "type": "boolean" }, "with_manual_prices": { "type": "boolean" } }, "required": [ "with_discount_promotions", "with_manual_prices" ] }, "PromotionCreate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "description": { "type": "string", "nullable": true, "minLength": 0, "maxLength": 10000 }, "validity": { "$ref": "#/components/schemas/PromotionValidity" }, "eligibility": { "$ref": "#/components/schemas/PromotionEligibility" }, "benefit": { "$ref": "#/components/schemas/PromotionBenefit" }, "item_restrictions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionItemRestriction" } }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionCondition" } }, "usage_limits": { "$ref": "#/components/schemas/PromotionUsageLimits" }, "accumulation": { "$ref": "#/components/schemas/PromotionAccumulation" }, "metadata": { "type": "object" } }, "required": [ "code", "name", "validity", "eligibility", "benefit", "item_restrictions", "conditions", "usage_limits", "accumulation" ] }, "PromotionCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "validity": { "type": "object" }, "eligibility": { "type": "object" }, "benefit": { "type": "object" }, "item_restrictions": { "type": "array", "items": { "type": "object" } }, "conditions": { "type": "array", "items": { "type": "object" } }, "usage_limits": { "type": "object" }, "accumulation": { "type": "object" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "active", "validity", "eligibility", "benefit", "item_restrictions", "conditions", "usage_limits", "accumulation", "metadata", "created_at", "updated_at" ] }, "PromotionListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "validity": { "type": "object" }, "eligibility": { "type": "object" }, "benefit": { "type": "object" }, "item_restrictions": { "type": "array", "items": { "type": "object" } }, "conditions": { "type": "array", "items": { "type": "object" } }, "usage_limits": { "type": "object" }, "accumulation": { "type": "object" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "description", "active", "validity", "eligibility", "benefit", "item_restrictions", "conditions", "usage_limits", "accumulation", "created_at", "updated_at" ] }, "PromotionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "PromotionFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "validity": { "type": "object" }, "eligibility": { "type": "object" }, "benefit": { "type": "object" }, "item_restrictions": { "type": "array", "items": { "type": "object" } }, "conditions": { "type": "array", "items": { "type": "object" } }, "usage_limits": { "type": "object" }, "accumulation": { "type": "object" }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "description", "active", "validity", "eligibility", "benefit", "item_restrictions", "conditions", "usage_limits", "accumulation", "metadata", "created_at", "updated_at" ] }, "PromotionUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "description": { "type": "string", "nullable": true, "minLength": 0, "maxLength": 10000 }, "active": { "type": "boolean" }, "validity": { "$ref": "#/components/schemas/PromotionValidity" }, "eligibility": { "$ref": "#/components/schemas/PromotionEligibility" }, "benefit": { "$ref": "#/components/schemas/PromotionBenefit" }, "item_restrictions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionItemRestriction" } }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionCondition" } }, "usage_limits": { "$ref": "#/components/schemas/PromotionUsageLimits" }, "accumulation": { "$ref": "#/components/schemas/PromotionAccumulation" }, "metadata": { "type": "object", "nullable": true } } }, "PromotionUpdateResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "validity": { "type": "object" }, "eligibility": { "type": "object" }, "benefit": { "type": "object" }, "item_restrictions": { "type": "array", "items": { "type": "object" } }, "conditions": { "type": "array", "items": { "type": "object" } }, "usage_limits": { "type": "object" }, "accumulation": { "type": "object" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "code", "name", "description", "active", "validity", "eligibility", "benefit", "item_restrictions", "conditions", "usage_limits", "accumulation", "created_at", "updated_at" ] }, "StateMachineTransitionResponse": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "StateMachineStateDetailResponse": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } }, "status": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string", "nullable": true } }, "required": [ "actions", "status", "label", "color" ] }, "StateMachineListItemResponse": { "type": "object", "properties": { "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransitionResponse" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateDetailResponse" } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "transitions", "states", "id", "entity_type", "code", "name", "active", "created_at", "updated_at" ] }, "StateMachineListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "StateMachineTransition": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "StateMachineStateConfig": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "StateMachineCreate": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransition" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateConfig" } } }, "required": [ "entityType", "code", "name", "transitions" ] }, "StateMachineStateConfigResponse": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } }, "status": { "type": "string" } }, "required": [ "actions", "status" ] }, "StateMachineCreateResponse": { "type": "object", "properties": { "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransitionResponse" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateConfigResponse" } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "transitions", "states", "id", "entity_type", "code", "name", "active", "created_at", "updated_at" ] }, "StateMachineFindResponse": { "type": "object", "properties": { "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransitionResponse" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateDetailResponse" } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "transitions", "states", "id", "entity_type", "code", "name", "active", "created_at", "updated_at" ] }, "StateMachineUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransition" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateConfig" } }, "active": { "type": "boolean" } } }, "StateMachineUpdateResponse": { "type": "object", "properties": { "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransitionResponse" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateConfigResponse" } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "transitions", "states", "id", "entity_type", "code", "name", "active", "created_at", "updated_at" ] }, "StatusListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "label": { "type": "string" }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ] }, "color": { "type": "string" }, "origin": { "type": "string", "enum": [ "KRUZER", "CUSTOM" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "entity_type", "code", "label", "nature", "color", "origin", "active", "created_at", "updated_at" ] }, "StatusListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "StatusCreate": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ] }, "color": { "type": "string" } }, "required": [ "entityType", "code", "label", "nature", "color" ] }, "StatusCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "label": { "type": "string" }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ] }, "color": { "type": "string" }, "origin": { "type": "string", "enum": [ "KRUZER", "CUSTOM" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "entity_type", "code", "label", "nature", "color", "origin", "active", "created_at", "updated_at" ] }, "StatusFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "label": { "type": "string" }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ] }, "color": { "type": "string" }, "origin": { "type": "string", "enum": [ "KRUZER", "CUSTOM" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "entity_type", "code", "label", "nature", "color", "origin", "active", "created_at", "updated_at" ] }, "StatusUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "string" }, "active": { "type": "boolean" } } }, "StatusUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "label": { "type": "string" }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ] }, "color": { "type": "string" }, "origin": { "type": "string", "enum": [ "KRUZER", "CUSTOM" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "entity_type", "code", "label", "nature", "color", "origin", "active", "created_at", "updated_at" ] }, "StrategyPriceListListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "price_list_id": { "type": "string" }, "active": { "type": "boolean" }, "price_list": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "price_list_id", "active", "price_list", "created_at", "updated_at" ] }, "StrategyPriceListListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyPriceListListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "StrategyPriceListCreate": { "type": "object", "properties": { "price_list_id": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "price_list_id" ] }, "StrategyPriceListCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "price_list_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "price_list_id", "active", "created_at", "updated_at" ] }, "StrategyPriceListFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "price_list_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "price_list_id", "active", "created_at", "updated_at" ] }, "StrategyPriceListUpdate": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "StrategyPriceListUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "strategy_id": { "type": "string" }, "price_list_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "strategy_id", "price_list_id", "active", "created_at", "updated_at" ] } } } }