{ "openapi": "3.0.0", "paths": { "/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Carrier found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Carrier deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Channel found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Channel deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "CARRIER_NOT_FOUND": { "summary": "Carrier not found", "value": { "error": { "code": "CARRIER_NOT_FOUND", "message": "Carrier 01920000-0000-7000-8000-000000000000 not found" } } }, "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy carrier identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Strategy carrier found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCarrierFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_CARRIER_NOT_FOUND": { "summary": "StrategyCarrier not found", "value": { "error": { "code": "STRATEGY_CARRIER_NOT_FOUND", "message": "StrategyCarrier 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy carrier identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_CARRIER_NOT_FOUND": { "summary": "StrategyCarrier not found", "value": { "error": { "code": "STRATEGY_CARRIER_NOT_FOUND", "message": "StrategyCarrier 01920000-0000-7000-8000-000000000000 not found" } } }, "DELIVERY_TYPE_NOT_FOUND": { "summary": "DeliveryType not found", "value": { "error": { "code": "DELIVERY_TYPE_NOT_FOUND", "message": "DeliveryType 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy carrier identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Strategy carrier deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_CARRIER_NOT_FOUND": { "summary": "StrategyCarrier not found", "value": { "error": { "code": "STRATEGY_CARRIER_NOT_FOUND", "message": "StrategyCarrier 01920000-0000-7000-8000-000000000000 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Delivery type found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryTypeFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Delivery type deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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": "cluster_id", "in": "query", "schema": { "type": "string" } }, { "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": "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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. When `state_machine_id` is omitted, the account default FULFILLMENT_ORDER state machine is resolved and stored; when provided it must reference an active FULFILLMENT_ORDER state machine.", "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (Cluster, StateMachine) was 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 01920000-0000-7000-8000-000000000000 not found" } } }, "STATE_MACHINE_NOT_FOUND": { "summary": "StateMachine not found", "value": { "error": { "code": "STATE_MACHINE_NOT_FOUND", "message": "StateMachine 01920000-0000-7000-8000-000000000000 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" } } }, "STRATEGY_STATE_MACHINE_INACTIVE": { "summary": "state_machine_id references an inactive state machine", "value": { "error": { "code": "STRATEGY_STATE_MACHINE_INACTIVE", "message": "state machine is inactive" } } }, "STRATEGY_STATE_MACHINE_INVALID_TYPE": { "summary": "state_machine_id references a machine that is not FULFILLMENT_ORDER", "value": { "error": { "code": "STRATEGY_STATE_MACHINE_INVALID_TYPE", "message": "state_machine_id must reference a FULFILLMENT_ORDER state machine" } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Strategy found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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. When `state_machine_id` is provided it must reference an active FULFILLMENT_ORDER state machine; sending `null` re-resolves the account default.", "operationId": "StrategiesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Strategy identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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, StateMachine) 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 01920000-0000-7000-8000-000000000000 not found" } } }, "CLUSTER_NOT_FOUND": { "summary": "Cluster not found", "value": { "error": { "code": "CLUSTER_NOT_FOUND", "message": "Cluster 01920000-0000-7000-8000-000000000000 not found" } } }, "STATE_MACHINE_NOT_FOUND": { "summary": "StateMachine not found", "value": { "error": { "code": "STATE_MACHINE_NOT_FOUND", "message": "StateMachine 01920000-0000-7000-8000-000000000000 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" } } }, "STRATEGY_STATE_MACHINE_INACTIVE": { "summary": "state_machine_id references an inactive state machine", "value": { "error": { "code": "STRATEGY_STATE_MACHINE_INACTIVE", "message": "state machine is inactive" } } }, "STRATEGY_STATE_MACHINE_INVALID_TYPE": { "summary": "state_machine_id references a machine that is not FULFILLMENT_ORDER", "value": { "error": { "code": "STRATEGY_STATE_MACHINE_INVALID_TYPE", "message": "state_machine_id must reference a FULFILLMENT_ORDER state machine" } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Strategy deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Cluster found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Cluster deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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/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": false, "description": "Busca textual por name ou code (case-insensitive).", "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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 business rule: ORDER machines are not creatable via the API (provisioned by the account seed), or the FULFILLMENT_ORDER graph breaks a structural save validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_STATE_MACHINE_NOT_CREATABLE": { "summary": "ORDER is the single canonical flow per account and is not creatable via the API", "value": { "error": { "code": "ORDER_STATE_MACHINE_NOT_CREATABLE", "message": "ORDER state machine is not creatable via API; it is provisioned by the account seed" } } }, "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 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "State machine found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateMachineFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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. Deactivating (`active: false`) is blocked while a live strategy references the machine, and ORDER machines cannot be deactivated at all (canonical order flow of the account).", "operationId": "StateMachinesController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State machine identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STATUS_NOT_FOUND": { "summary": "Status not found", "value": { "error": { "code": "STATUS_NOT_FOUND", "message": "Status 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "409": { "description": "The state machine is referenced by at least one live strategy and cannot be deleted or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_IN_USE": { "summary": "State machine referenced by live strategies", "value": { "error": { "code": "STATE_MACHINE_IN_USE", "message": "StateMachine cannot be deleted because it is in use", "details": [ { "entity": "Strategy", "count": 3 } ] } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a business rule: an ORDER machine cannot be deactivated, or a structural save validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_STATE_MACHINE_NOT_DEACTIVATABLE": { "summary": "Attempt to deactivate the ORDER state machine", "value": { "error": { "code": "ORDER_STATE_MACHINE_NOT_DEACTIVATABLE", "message": "ORDER state machine cannot be deactivated; it is the canonical order flow of the account" } } }, "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 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. ORDER state machines are not deletable (canonical order flow of the account).", "operationId": "StateMachinesController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State machine identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "State machine deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "409": { "description": "The state machine is referenced by at least one live strategy and cannot be deleted or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_IN_USE": { "summary": "State machine referenced by live strategies", "value": { "error": { "code": "STATE_MACHINE_IN_USE", "message": "StateMachine cannot be deleted because it is in use", "details": [ { "entity": "Strategy", "count": 3 } ] } } } } } } }, "422": { "description": "The state machine cannot be deleted because it is the canonical ORDER flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_STATE_MACHINE_NOT_DELETABLE": { "summary": "Attempt to delete the ORDER state machine", "value": { "error": { "code": "ORDER_STATE_MACHINE_NOT_DELETABLE", "message": "ORDER state machine is not deletable via API; it is the canonical order flow of the account" } } } } } } }, "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/state-machines/{id}/default": { "patch": { "description": "Promotes the state machine to the default for its entity type within the account, demoting the previous default atomically. Idempotent: promoting the current default is a successful no-op.", "operationId": "StateMachinesController_setDefault_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "State machine identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "State machine set as default.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultStateMachineResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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 state machine as default", "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Status found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Status deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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}/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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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, 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 01920000-0000-7000-8000-000000000000 not found" } } }, "CHANNEL_NOT_FOUND": { "summary": "Channel not found", "value": { "error": { "code": "CHANNEL_NOT_FOUND", "message": "Channel 01920000-0000-7000-8000-000000000000 not found" } } }, "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy channel identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Strategy channel found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyChannelFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_CHANNEL_NOT_FOUND": { "summary": "StrategyChannel not found", "value": { "error": { "code": "STRATEGY_CHANNEL_NOT_FOUND", "message": "StrategyChannel 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy channel identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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, 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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_CHANNEL_NOT_FOUND": { "summary": "StrategyChannel not found", "value": { "error": { "code": "STRATEGY_CHANNEL_NOT_FOUND", "message": "StrategyChannel 01920000-0000-7000-8000-000000000000 not found" } } }, "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy channel identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Strategy channel deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_CHANNEL_NOT_FOUND": { "summary": "StrategyChannel not found", "value": { "error": { "code": "STRATEGY_CHANNEL_NOT_FOUND", "message": "StrategyChannel 01920000-0000-7000-8000-000000000000 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/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Price list found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Price list deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "required": false, "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "skus", "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 price list items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListListItemResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, q, or skus) 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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-items.ingestion.", "operationId": "PriceListsController_upsertItems_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Price list identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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_DOCUMENT_TYPE_MISMATCH": { "summary": "Informed type does not match the document", "value": { "error": { "code": "CUSTOMER_DOCUMENT_TYPE_MISMATCH", "message": "document does not match the informed type: type PF requires a CPF" } } }, "CUSTOMER_INVALID_BIRTH_DATE": { "summary": "Birth date is in the future", "value": { "error": { "code": "CUSTOMER_INVALID_BIRTH_DATE", "message": "birth date must not be in the future" } } } } } } }, "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 + addresses) by its identifier.", "operationId": "CustomersController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Customer found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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 customer contact fields (name, e-mail, phone, birth date, metadata). Document, type and externalId are immutable.", "operationId": "CustomersController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Customer identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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_INVALID_BIRTH_DATE": { "summary": "Birth date is in the future", "value": { "error": { "code": "CUSTOMER_INVALID_BIRTH_DATE", "message": "birth date must not be in the future" } } } } } } }, "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_create_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressCreate" } } } }, "responses": { "201": { "description": "Address created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressCreateResponse" } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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": "Create customer address", "tags": [ "customer-addresses" ] } }, "/api/v1/customers/{customerId}/addresses/{addressId}": { "patch": { "description": "Replaces the editable data of an existing address. Sending is_default=true also promotes it to the customer default (demoting the previous one).", "operationId": "CustomerAddressesController_update_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "addressId", "required": true, "in": "path", "description": "Address identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "CUSTOMER_ADDRESS_NOT_FOUND": { "summary": "CustomerAddress not found", "value": { "error": { "code": "CUSTOMER_ADDRESS_NOT_FOUND", "message": "CustomerAddress 01920000-0000-7000-8000-000000000000 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.", "operationId": "CustomerAddressesController_remove_v1", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "Customer identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "addressId", "required": true, "in": "path", "description": "Address identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Address removed." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "CUSTOMER_ADDRESS_NOT_FOUND": { "summary": "CustomerAddress not found", "value": { "error": { "code": "CUSTOMER_ADDRESS_NOT_FOUND", "message": "CustomerAddress 01920000-0000-7000-8000-000000000000 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": "Remove 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Freight type found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightTypeFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Freight type deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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 the SKU (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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 absolute inventory positions and publishes them to Kafka for asynchronous processing. Each item overwrites the position (onHand, blocked, safetyStock) for its sku/strategyCode. Returns 202 with a correlation id shared by every published event of the batch.", "operationId": "InventoryController_ingest_v1", "parameters": [], "requestBody": { "required": true, "description": "Batch of absolute inventory positions (snapshot).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySnapshotIngest" } } } }, "responses": { "202": { "description": "Batch accepted and published to Kafka.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryIngestResponse" } } } }, "400": { "description": "Invalid payload: 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Delivery modality found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryModalityFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Delivery modality deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Operator found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Operator deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "OPERATOR_NOT_FOUND": { "summary": "Operator not found", "value": { "error": { "code": "OPERATOR_NOT_FOUND", "message": "Operator 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy operator identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Strategy operator found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyOperatorFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_OPERATOR_NOT_FOUND": { "summary": "StrategyOperator not found", "value": { "error": { "code": "STRATEGY_OPERATOR_NOT_FOUND", "message": "StrategyOperator 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy operator identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_OPERATOR_NOT_FOUND": { "summary": "StrategyOperator not found", "value": { "error": { "code": "STRATEGY_OPERATOR_NOT_FOUND", "message": "StrategyOperator 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy operator identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Strategy operator deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_OPERATOR_NOT_FOUND": { "summary": "StrategyOperator not found", "value": { "error": { "code": "STRATEGY_OPERATOR_NOT_FOUND", "message": "StrategyOperator 01920000-0000-7000-8000-000000000000 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/orders": { "post": { "description": "Validates and synchronously materializes a channel order: checks the channel is active; optionally links an existing customer by customer_id (the order is left unidentified when omitted); validates every item SKU against an active product and every payment method against an active payment method; cross-checks the subtotal against the sum of item totals; then persists the order, its items, addresses, mirrored payments and bootstrap timeline event in a single transaction. A duplicate (same external_order_id + channel) is rejected with 409. Authenticated as a channel service account.", "operationId": "OrdersController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "201": { "description": "Order created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateResponse" } } } }, "400": { "description": "Invalid payload: schema violation, missing required field, or empty items/payments.", "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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, Product, PaymentMethod) 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 01920000-0000-7000-8000-000000000000 not found" } } }, "PRODUCT_NOT_FOUND": { "summary": "Product not found", "value": { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product 01920000-0000-7000-8000-000000000000 not found" } } }, "PAYMENT_METHOD_NOT_FOUND": { "summary": "PaymentMethod not found", "value": { "error": { "code": "PAYMENT_METHOD_NOT_FOUND", "message": "PaymentMethod 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "409": { "description": "An order with the same external_order_id already exists for the channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_EXTERNAL_ORDER_ID_ALREADY_EXISTS": { "summary": "Duplicate channel order", "value": { "error": { "code": "ORDER_EXTERNAL_ORDER_ID_ALREADY_EXISTS", "message": "Order with external_order_id \"EXT-123\" already exists" } } } } } } }, "422": { "description": "Business rule violation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_CHANNEL_INACTIVE": { "summary": "Channel is missing or inactive", "value": { "error": { "code": "ORDER_CHANNEL_INACTIVE", "message": "channel ECOMMERCE is not an active channel for the account" } } }, "ORDER_PRODUCT_INACTIVE": { "summary": "An item references an inactive product", "value": { "error": { "code": "ORDER_PRODUCT_INACTIVE", "message": "product SKU-123 is not active for the account" } } }, "ORDER_PAYMENT_METHOD_INACTIVE": { "summary": "A payment references an inactive payment method", "value": { "error": { "code": "ORDER_PAYMENT_METHOD_INACTIVE", "message": "payment method PIX is not active for the account" } } }, "ORDER_TOTALS_MISMATCH": { "summary": "Subtotal does not match the items", "value": { "error": { "code": "ORDER_TOTALS_MISMATCH", "message": "subtotal must equal the sum of item total prices" } } }, "ORDER_NO_DEFAULT_STATE_MACHINE": { "summary": "Account has no default ORDER state machine", "value": { "error": { "code": "ORDER_NO_DEFAULT_STATE_MACHINE", "message": "no default ORDER state machine is configured for account ACME" } } } } } } }, "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 a channel order (synchronous)", "tags": [ "orders" ] }, "get": { "description": "Returns a paginated list of orders scoped to the caller account. A creation-date window (createdFrom/createdTo, ISO 8601, max 6 months apart) is required; status, channel filters, free-text search and sorting are optional.", "operationId": "OrdersController_list_v1", "parameters": [ { "required": false, "name": "status", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 50 } } }, { "required": false, "name": "channelId", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "required": false, "name": "customerId", "in": "query", "schema": { "type": "string" } }, { "required": true, "name": "createdFrom", "in": "query", "schema": { "type": "string" } }, { "required": true, "name": "createdTo", "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 orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } }, "400": { "description": "Invalid query parameters: missing/invalid creation-date window (required, max 6 months), or invalid 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 orders", "tags": [ "orders" ] } }, "/api/v1/orders/{id}/status": { "patch": { "description": "Transitions the order to a new status, validated by the order state machine snapshot embedded at creation. On success it appends an immutable timeline event (OrderTrackingEvent). Operator / internal-integration path: accountCode and the actor (user or service account) come from the JWT.", "operationId": "OrdersController_updateStatus_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusUpdate" } } } }, "responses": { "200": { "description": "Order status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusUpdateResponse" } } } }, "400": { "description": "Invalid payload: missing/invalid status, metadata is not an object, or id is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "Order not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "422": { "description": "The status transition is not allowed by the order state machine, or the target is CANCELLED (cancellation must go through POST /orders/:id/cancel).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_TRANSITION_NOT_ALLOWED": { "summary": "No such edge in the snapshot", "value": { "error": { "code": "STATE_MACHINE_TRANSITION_NOT_ALLOWED", "message": "transition CREATED -> INVOICED is not allowed by the state machine" } } }, "ORDER_STATUS_CANCEL_NOT_ALLOWED": { "summary": "Cancellation must use the dedicated endpoint", "value": { "error": { "code": "ORDER_STATUS_CANCEL_NOT_ALLOWED", "message": "CANCELLED is not an allowed target for PATCH /status; use POST /orders/:id/cancel to cancel an order" } } } } } } }, "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 an order status (synchronous)", "tags": [ "orders" ] } }, "/api/v1/orders/{id}/addresses": { "patch": { "description": "Sets the shipping (SHIPPING) address of an existing order — edits it when present, or creates it when the order was created without one (e.g. store pickup). accountCode comes from the JWT; a reason is required and recorded in the narrative log.", "operationId": "OrdersController_updateAddresses_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderAddressesUpdate" } } } }, "responses": { "200": { "description": "Order shipping address set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderAddressesUpdateResponse" } } } }, "400": { "description": "Invalid payload: missing reason, malformed shipping address, or id is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "Order not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "422": { "description": "The shipping address fields are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_ADDRESS_INVALID_ZIPCODE": { "summary": "zipCode must contain 8 digits", "value": { "error": { "code": "ORDER_ADDRESS_INVALID_ZIPCODE", "message": "zipCode must contain 8 digits" } } } } } } }, "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 an order shipping address (synchronous)", "tags": [ "orders" ] } }, "/api/v1/orders/{id}/cancel": { "post": { "description": "Cancels an order as a CANCELLED transition validated by the order state machine version pinned at creation. A required free-text reason plus any free-form metadata are captured on an immutable timeline event (OrderTrackingEvent — the cancellation moment is previousStatus; the server-validated reason always wins over a same-named metadata key) and echoed back in the response metadata. The transition and the event are written in a single transaction. Orders past INVOICED have no declared edge to CANCELLED and are rejected with 422. accountCode and the actor (user or service account) come from the JWT.", "operationId": "OrdersController_cancel_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrder" } } } }, "responses": { "200": { "description": "Order cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponse" } } } }, "400": { "description": "Invalid payload: missing/empty reason, reason over 500 chars, metadata is not an object, or id is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "Order not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "422": { "description": "The CANCELLED transition is not allowed by the order state machine from the current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_TRANSITION_NOT_ALLOWED": { "summary": "Order can no longer be cancelled (at or after invoicing)", "value": { "error": { "code": "STATE_MACHINE_TRANSITION_NOT_ALLOWED", "message": "transition INVOICED -> CANCELLED is not allowed by the state machine" } } } } } } }, "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": "Cancel an order (synchronous)", "tags": [ "orders" ] } }, "/api/v1/orders/{id}": { "get": { "description": "Returns the full order detail scoped to the caller account: header (id, external order id, channel, status, currency, creation), resolved customer, shipping/billing addresses, items (with metadata), mirrored payments, totals, the resolved state machine (id/code/name/version + transitions of the pinned version), the fulfillment orders block, and a unified chronological timeline that merges order status events, fulfillment order status events and shipment tracking events (each shipment event carries the resolved carrier and tracking code). An order that does not exist, is soft-deleted, or belongs to another account returns 404.", "operationId": "OrdersController_findById_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "The order detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderFindResponse" } } } }, "400": { "description": "Invalid path parameter: id is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "Order not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 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": "Get an order by id", "tags": [ "orders" ] } }, "/api/v1/orders/{orderId}/payments": { "post": { "description": "Records a payment against an existing order (a gateway payment or a manual one with method=MANUAL). The order is never marked paid directly: when the captured (PAID) payments cover the total, the order is derived to PAID and a tracking event is appended in the same transaction.", "operationId": "OrderPaymentsController_create_v1", "parameters": [ { "name": "orderId", "required": true, "in": "path", "description": "Order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentCreate" } } } }, "responses": { "201": { "description": "Payment registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentCreateResponse" } } } }, "400": { "description": "Invalid payload: missing/invalid method, amount, status, or orderId is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (Order, PaymentMethod) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 not found" } } }, "PAYMENT_METHOD_NOT_FOUND": { "summary": "PaymentMethod not found", "value": { "error": { "code": "PAYMENT_METHOD_NOT_FOUND", "message": "PaymentMethod 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "409": { "description": "A payment with the same gateway transaction already exists for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_PAYMENT_IDEMPOTENCY_ALREADY_EXISTS": { "summary": "Duplicate gateway transaction", "value": { "error": { "code": "ORDER_PAYMENT_IDEMPOTENCY_ALREADY_EXISTS", "message": "OrderPayment with idempotency \"pix@tx-123\" already exists" } } } } } } }, "422": { "description": "Business rule violation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_PAYMENT_METHOD_INACTIVE": { "summary": "The payment method is not active", "value": { "error": { "code": "ORDER_PAYMENT_METHOD_INACTIVE", "message": "payment method PIX is not active for the account" } } } } } } }, "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": "Register a payment for an order", "tags": [ "order-payments" ] } }, "/api/v1/orders/{orderId}/payments/{paymentId}": { "patch": { "description": "Updates the status of an existing payment (e.g. confirming a pending PIX as PAID). When the captured payments come to cover the total, the order is derived to PAID and a tracking event is appended in the same transaction.", "operationId": "OrderPaymentsController_update_v1", "parameters": [ { "name": "orderId", "required": true, "in": "path", "description": "Order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "paymentId", "required": true, "in": "path", "description": "Order payment identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentUpdate" } } } }, "responses": { "200": { "description": "Payment status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentUpdateResponse" } } } }, "400": { "description": "Invalid payload: missing/invalid status, or orderId/paymentId is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (Order, OrderPayment) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 not found" } } }, "ORDER_PAYMENT_NOT_FOUND": { "summary": "OrderPayment not found", "value": { "error": { "code": "ORDER_PAYMENT_NOT_FOUND", "message": "OrderPayment 01920000-0000-7000-8000-000000000000 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 an order payment status", "tags": [ "order-payments" ] } }, "/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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" ] } }, "/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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Payment method found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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" ] } }, "/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Product found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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/orders/{orderId}/fulfillment-orders": { "get": { "description": "Returns the consolidated fulfillment view of a single order: every fulfillment order it spawned, each with its full timeline (tracking events), its shipments, and each shipment tracking timeline. One order may spawn more than one fulfillment order (split, re-routing, re-assignment). NOT paginated — an order is served by at most a handful of operations. Validates that the parent order exists (404 when it does not, belongs to another account, or is soft-deleted). Scoped to the caller account; soft-deleted records are excluded. accountCode comes from the JWT.", "operationId": "OrderFulfillmentOrdersController_list_v1", "parameters": [ { "name": "orderId", "required": true, "in": "path", "description": "Parent order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "The fulfillment orders of the order, each enriched with timeline, shipments and shipment tracking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderFulfillmentOrderListResponse" } } } }, "400": { "description": "The orderId is not a valid 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "Order not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ORDER_NOT_FOUND": { "summary": "Order not found", "value": { "error": { "code": "ORDER_NOT_FOUND", "message": "Order 01920000-0000-7000-8000-000000000000 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 the fulfillment orders of an order", "tags": [ "orders" ] } }, "/api/v1/fulfillment-orders": { "get": { "description": "Returns a paginated list of fulfillment orders scoped to the caller account. Optional, combinable filters: order (orderId), operation/store (strategyId), current stage (status) and a creation-date window (createdFrom/createdTo, ISO 8601, at most 6 months apart when both are given). Sortable by createdAt/updatedAt (default createdAt desc). accountCode comes from the JWT.", "operationId": "FulfillmentOrdersController_list_v1", "parameters": [ { "required": false, "name": "orderId", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "strategyId", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "status", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "createdFrom", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "createdTo", "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 fulfillment orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderListResponse" } } } }, "400": { "description": "Invalid query parameters (pagination, sorting, filters, or creation-date range).", "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 fulfillment orders", "tags": [ "fulfillment-orders" ] } }, "/api/v1/fulfillment-orders/{id}": { "get": { "description": "Returns the fulfillment order detail scoped to the caller account: the fulfillment order header, its items and its status timeline (tracking events ordered chronologically by occurrence — creation, status changes, cancellation/rejection, each with actor, moment and any reason captured in metadata). Shipments and their tracking live on the nested shipments resource. accountCode comes from the JWT.", "operationId": "FulfillmentOrdersController_findById_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Fulfillment order identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "The fulfillment order detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderFindResponse" } } } }, "400": { "description": "Invalid path parameter: id 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "FulfillmentOrder not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 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": "Get a fulfillment order by id", "tags": [ "fulfillment-orders" ] } }, "/api/v1/fulfillment-orders/{id}/cancel": { "post": { "description": "Cancels a fulfillment order as a CANCELLED transition validated against the state machine version pinned on the FO. A required free-text reason plus any free-form metadata are captured on an immutable timeline event (FulfillmentOrderTrackingEvent — the cancellation moment is previousStatus; the server-validated reason always wins over a same-named metadata key) and echoed back in the response metadata. On enter, the CANCELLED state releases the inventory reservation (RELEASE_INVENTORY); the transition, the timeline event and the stock release run in a single transaction. A fulfillment order at or after INVOICED has no declared edge to CANCELLED and is rejected with 422. accountCode and the actor (user or service account) come from the JWT.", "operationId": "FulfillmentOrdersController_cancel_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Fulfillment order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelFulfillmentOrder" } } } }, "responses": { "200": { "description": "Fulfillment order cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelFulfillmentOrderResponse" } } } }, "400": { "description": "Invalid payload: missing/empty reason, reason over 500 chars, metadata is not an object, or id is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (FulfillmentOrder, Strategy) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_NOT_FOUND": { "summary": "Strategy not found", "value": { "error": { "code": "STRATEGY_NOT_FOUND", "message": "Strategy 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "422": { "description": "The CANCELLED transition is not allowed by the FO state machine from the current status, or the inventory reservation cannot be released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_TRANSITION_NOT_ALLOWED": { "summary": "FO can no longer be cancelled (at or after invoicing)", "value": { "error": { "code": "STATE_MACHINE_TRANSITION_NOT_ALLOWED", "message": "transition INVOICED -> CANCELLED is not allowed by the state machine" } } }, "INVENTORY_INSUFFICIENT_RESERVED": { "summary": "Reserved cannot satisfy the release", "value": { "error": { "code": "INVENTORY_INSUFFICIENT_RESERVED", "message": "cannot release 2; only 1 reserved" } } } } } } }, "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": "Cancel a fulfillment order (synchronous)", "tags": [ "fulfillment-orders" ] } }, "/api/v1/fulfillment-orders/{id}/status": { "patch": { "description": "Transitions the fulfillment order to a new status, validated against the state machine version pinned on the FO at creation. On a valid transition it appends an immutable timeline event (FulfillmentOrderTrackingEvent) — the status change and the timeline entry run in a single transaction. Inventory effects are not applied by this endpoint. CANCELLED and REJECTED are not allowed here: they require a reason and go through the dedicated reject/cancel endpoint. accountCode and the actor (user or service account) come from the JWT.", "operationId": "FulfillmentOrdersController_updateStatus_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Fulfillment order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderStatusUpdate" } } } }, "responses": { "200": { "description": "Fulfillment order status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderStatusUpdateResponse" } } } }, "400": { "description": "Invalid payload: missing/invalid status, metadata is not an object, or id is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (FulfillmentOrder, StateMachineVersion) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 not found" } } }, "STATE_MACHINE_VERSION_NOT_FOUND": { "summary": "StateMachineVersion not found", "value": { "error": { "code": "STATE_MACHINE_VERSION_NOT_FOUND", "message": "StateMachineVersion 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "422": { "description": "The status transition is not allowed by the FO state machine version, or the target is a terminal (CANCELLED/REJECTED) that must use the dedicated reject/cancel endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "STATE_MACHINE_TRANSITION_NOT_ALLOWED": { "summary": "No such edge in the pinned version", "value": { "error": { "code": "STATE_MACHINE_TRANSITION_NOT_ALLOWED", "message": "transition ASSIGNED -> SHIPPED is not allowed by the state machine" } } }, "FULFILLMENT_ORDER_TERMINAL_TRANSITION_NOT_ALLOWED": { "summary": "Terminal must use the dedicated endpoint", "value": { "error": { "code": "FULFILLMENT_ORDER_TERMINAL_TRANSITION_NOT_ALLOWED", "message": "REJECTED requires a reason; use the dedicated reject/cancel endpoint to reach a terminal state" } } } } } } }, "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 a fulfillment order status (synchronous)", "tags": [ "fulfillment-orders" ] } }, "/api/v1/fulfillment-orders/{fulfillmentOrderId}/shipments": { "get": { "description": "Returns a paginated list of shipments scoped to the caller account and parent fulfillment order.", "operationId": "FulfillmentOrderShipmentsController_list_v1", "parameters": [ { "name": "fulfillmentOrderId", "required": true, "in": "path", "description": "Parent fulfillment order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "required": false, "name": "status", "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 fulfillment order shipments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderShipmentListResponse" } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "FulfillmentOrder not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 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 fulfillment order shipments", "tags": [ "fulfillment-order-shipments" ] }, "post": { "description": "Creates a shipment (status SHIPMENT_CREATED — not yet dispatched by the carrier) linked to the fulfillment order and opens its tracking timeline with a matching event, in a single transaction. It does not change the fulfillment order status. Validates that the fulfillment order, the carrier and every package SKU exist. accountCode comes from the JWT.", "operationId": "FulfillmentOrderShipmentsController_create_v1", "parameters": [ { "name": "fulfillmentOrderId", "required": true, "in": "path", "description": "Parent fulfillment order identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderShipmentCreate" } } } }, "responses": { "201": { "description": "Shipment created (status SHIPMENT_CREATED, awaiting dispatch). Fulfillment order status unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderShipmentCreateResponse" } } } }, "400": { "description": "Invalid payload: missing/invalid carrier UUID, empty packages/items, or invalid measures.", "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (FulfillmentOrder, Carrier, Product) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 not found" } } }, "CARRIER_NOT_FOUND": { "summary": "Carrier not found", "value": { "error": { "code": "CARRIER_NOT_FOUND", "message": "Carrier 01920000-0000-7000-8000-000000000000 not found" } } }, "PRODUCT_NOT_FOUND": { "summary": "Product not found", "value": { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "409": { "description": "A shipment with the same tracking code already exists in the account (when a tracking code is sent).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_SHIPMENT_TRACKING_CODE_ALREADY_EXISTS": { "summary": "Duplicate tracking code", "value": { "error": { "code": "FULFILLMENT_ORDER_SHIPMENT_TRACKING_CODE_ALREADY_EXISTS", "message": "FulfillmentOrderShipment with tracking_code \"BR123456789BR\" 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 a shipment on a fulfillment order (synchronous)", "tags": [ "fulfillment-order-shipments" ] } }, "/api/v1/fulfillment-orders/{fulfillmentOrderId}/shipments/{id}": { "get": { "description": "Returns the shipment detail scoped to the caller account and parent fulfillment order: header, packages and its tracking timeline (events ordered chronologically by occurrence).", "operationId": "FulfillmentOrderShipmentsController_findById_v1", "parameters": [ { "name": "fulfillmentOrderId", "required": true, "in": "path", "description": "Parent fulfillment order identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Fulfillment order shipment identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "The fulfillment order shipment detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderShipmentFindResponse" } } } }, "400": { "description": "Invalid path parameter: fulfillmentOrderId or id 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (FulfillmentOrder, FulfillmentOrderShipment) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 not found" } } }, "FULFILLMENT_ORDER_SHIPMENT_NOT_FOUND": { "summary": "FulfillmentOrderShipment not found", "value": { "error": { "code": "FULFILLMENT_ORDER_SHIPMENT_NOT_FOUND", "message": "FulfillmentOrderShipment 01920000-0000-7000-8000-000000000000 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": "Get a fulfillment order shipment by id", "tags": [ "fulfillment-order-shipments" ] } }, "/api/v1/fulfillment-orders/{fulfillmentOrderId}/shipments/{shipmentId}/tracking-events": { "get": { "description": "Returns every tracking event of the shipment ordered by occurred_at ascending — the full timeline, not paginated. Read-only: events are written on shipment creation and on each inbound tracking status update. Validates that the parent fulfillment order and the shipment (under that fulfillment order) exist. accountCode comes from the JWT.", "operationId": "FulfillmentOrderShipmentTrackingEventsController_list_v1", "parameters": [ { "name": "fulfillmentOrderId", "required": true, "in": "path", "description": "Parent fulfillment order identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "shipmentId", "required": true, "in": "path", "description": "Shipment identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "The shipment's tracking events ordered by occurred_at ascending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderShipmentTrackingEventListResponse" } } } }, "400": { "description": "Invalid path parameters (fulfillment order or shipment 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 (FulfillmentOrder, FulfillmentOrderShipment) was not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 not found" } } }, "FULFILLMENT_ORDER_SHIPMENT_NOT_FOUND": { "summary": "FulfillmentOrderShipment not found", "value": { "error": { "code": "FULFILLMENT_ORDER_SHIPMENT_NOT_FOUND", "message": "FulfillmentOrderShipment 01920000-0000-7000-8000-000000000000 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 a shipment's tracking events (chronological timeline)", "tags": [ "fulfillment-order-shipment-tracking-events" ] } }, "/api/v1/fulfillment-orders/{fulfillmentOrderId}/tracking-events": { "get": { "description": "Returns every tracking event of the fulfillment order ordered by occurred_at ascending — the full timeline, not paginated. Read-only: events are written on each fulfillment order status transition and on cancellation. Each event carries the status change (previous_status -> new_status), the actor (user or service account) and any metadata (e.g. a cancellation reason). Validates that the parent fulfillment order exists. accountCode comes from the JWT.", "operationId": "FulfillmentOrderTrackingEventsController_list_v1", "parameters": [ { "name": "fulfillmentOrderId", "required": true, "in": "path", "description": "Parent fulfillment order identifier (UUID v4).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "The fulfillment order's tracking events ordered by occurred_at ascending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentOrderTrackingEventListResponse" } } } }, "400": { "description": "Invalid path parameter: fulfillmentOrderId 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "FulfillmentOrder not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "FULFILLMENT_ORDER_NOT_FOUND": { "summary": "FulfillmentOrder not found", "value": { "error": { "code": "FULFILLMENT_ORDER_NOT_FOUND", "message": "FulfillmentOrder 01920000-0000-7000-8000-000000000000 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 a fulfillment order's tracking events (chronological timeline)", "tags": [ "fulfillment-order-tracking-events" ] } }, "/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/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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}": { "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Product category found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "PRODUCT_NOT_FOUND": { "summary": "Product not found", "value": { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Product category deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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/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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Promotion found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Promotion deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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/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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "PRICE_LIST_NOT_FOUND": { "summary": "PriceList not found", "value": { "error": { "code": "PRICE_LIST_NOT_FOUND", "message": "PriceList 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy price list identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Strategy price list found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyPriceListFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_PRICE_LIST_NOT_FOUND": { "summary": "StrategyPriceList not found", "value": { "error": { "code": "STRATEGY_PRICE_LIST_NOT_FOUND", "message": "StrategyPriceList 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy price list identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_PRICE_LIST_NOT_FOUND": { "summary": "StrategyPriceList not found", "value": { "error": { "code": "STRATEGY_PRICE_LIST_NOT_FOUND", "message": "StrategyPriceList 01920000-0000-7000-8000-000000000000 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).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } }, { "name": "id", "required": true, "in": "path", "description": "Strategy price list identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Strategy price list deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 01920000-0000-7000-8000-000000000000 not found" } } }, "STRATEGY_PRICE_LIST_NOT_FOUND": { "summary": "StrategyPriceList not found", "value": { "error": { "code": "STRATEGY_PRICE_LIST_NOT_FOUND", "message": "StrategyPriceList 01920000-0000-7000-8000-000000000000 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" ] } }, "/api/v1/webhook-subscriptions": { "get": { "description": "Returns a paginated list of webhook subscriptions scoped to the caller account.", "operationId": "WebhookSubscriptionsController_list_v1", "parameters": [ { "required": false, "description": "Free-text search with case-insensitive partial match on name and url.", "name": "q", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "required": false, "name": "status", "in": "query", "schema": { "type": "string" } }, { "required": false, "name": "eventType", "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 webhook subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListResponse" } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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 webhook subscriptions", "tags": [ "webhook-subscriptions" ] }, "post": { "description": "Creates a new webhook subscription within the caller account.", "operationId": "WebhookSubscriptionsController_create_v1", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreate" } } } }, "responses": { "201": { "description": "Webhook subscription created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateResponse" } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "WEBHOOK_SUBSCRIPTION_INVALID_URL": { "summary": "URL is not a valid http(s) URL", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_INVALID_URL", "message": "url must use the http or https protocol" } } }, "WEBHOOK_SUBSCRIPTION_UNKNOWN_EVENT_TYPE": { "summary": "Event type outside the known catalog", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_UNKNOWN_EVENT_TYPE", "message": "eventTypes must be a subset of ORDER_CREATED, ORDER_STATUS_CHANGED" } } } } } } }, "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 webhook subscription", "tags": [ "webhook-subscriptions" ] } }, "/api/v1/webhook-subscriptions/event-types": { "get": { "description": "Returns the catalog of subscribable webhook event types with localized labels. Static — derived from the domain enum, no database access.", "operationId": "WebhookSubscriptionsController_eventTypes_v1", "parameters": [], "responses": { "200": { "description": "Catalog of subscribable webhook event types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTypesListResponse" } } } }, "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 webhook event types", "tags": [ "webhook-subscriptions" ] } }, "/api/v1/webhook-subscriptions/{id}": { "get": { "description": "Returns a webhook subscription by its identifier.", "operationId": "WebhookSubscriptionsController_find_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook subscription identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "200": { "description": "Webhook subscription found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionFindResponse" } } } }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "WebhookSubscription not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WebhookSubscription not found", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "message": "WebhookSubscription 01920000-0000-7000-8000-000000000000 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 webhook subscription", "tags": [ "webhook-subscriptions" ] }, "patch": { "description": "Partially updates a webhook subscription by its identifier.", "operationId": "WebhookSubscriptionsController_update_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook subscription identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdate" } } } }, "responses": { "200": { "description": "Webhook subscription updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateResponse" } } } }, "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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "WebhookSubscription not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WebhookSubscription not found", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "message": "WebhookSubscription 01920000-0000-7000-8000-000000000000 not found" } } } } } } }, "422": { "description": "The payload passed schema validation but breaks a domain invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "WEBHOOK_SUBSCRIPTION_INVALID_URL": { "summary": "URL is not a valid http(s) URL", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_INVALID_URL", "message": "url must use the http or https protocol" } } }, "WEBHOOK_SUBSCRIPTION_UNKNOWN_EVENT_TYPE": { "summary": "Event type outside the known catalog", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_UNKNOWN_EVENT_TYPE", "message": "eventTypes must be a subset of ORDER_CREATED, ORDER_STATUS_CHANGED" } } } } } } }, "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 webhook subscription", "tags": [ "webhook-subscriptions" ] }, "delete": { "description": "Soft-deletes a webhook subscription by its identifier.", "operationId": "WebhookSubscriptionsController_remove_v1", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook subscription identifier (UUID).", "schema": { "type": "string", "format": "uuid", "example": "01920000-0000-7000-8000-000000000000" } } ], "responses": { "204": { "description": "Webhook subscription deleted." }, "400": { "description": "Path parameter is not a 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", "value": { "error": { "code": "VALIDATION_ERROR", "message": "invalid request payload", "details": [ { "field": "id", "reason": "id must be a valid UUID" } ] } } } } } } }, "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": "WebhookSubscription not found in the caller account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "WEBHOOK_SUBSCRIPTION_NOT_FOUND": { "summary": "WebhookSubscription not found", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_NOT_FOUND", "message": "WebhookSubscription 01920000-0000-7000-8000-000000000000 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 webhook subscription", "tags": [ "webhook-subscriptions" ] } } }, "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": [], "servers": [ { "url": "https://oms-api.tenant.krzlabs.io", "description": "Produção — troque 'tenant' pelo subdomínio da sua conta." }, { "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" ] }, "CarrierCapabilitiesCreate": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } }, "CarrierFreightRulesCreate": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "CarrierOperatingHourCreate": { "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/CarrierCapabilitiesCreate" }, "default_freight_rules": { "$ref": "#/components/schemas/CarrierFreightRulesCreate" }, "default_operating_hours": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierOperatingHourCreate" } }, "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" ] }, "CarrierCapabilitiesUpdate": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } }, "CarrierFreightRulesUpdate": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "CarrierOperatingHourUpdate": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] }, "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/CarrierCapabilitiesUpdate" }, "default_freight_rules": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CarrierFreightRulesUpdate" } ] }, "default_operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/CarrierOperatingHourUpdate" } }, "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", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "operating_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "holidays_hours": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] }, "carrier": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } } }, "required": [ "name", "code", "capabilities" ] }, "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" ] }, "CoverageCityCreate": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" } }, "required": [ "city", "state" ] }, "CoverageZipRangeCreate": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{8}$" }, "end": { "type": "string", "pattern": "^\\d{8}$" } }, "required": [ "start", "end" ] }, "PolygonGeometryCreate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Polygon" ] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } } }, "required": [ "type", "coordinates" ] }, "CoverageAreaCreate": { "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/CoverageCityCreate" } }, "ranges": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CoverageZipRangeCreate" } }, "polygon": { "$ref": "#/components/schemas/PolygonGeometryCreate" } }, "required": [ "type" ] }, "StrategyCarrierFreightRulesCreate": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "StrategyCarrierOperatingHourCreate": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] }, "StrategyCarrierHolidaysHoursCreate": { "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/CoverageAreaCreate" } ] }, "freight_rules": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierFreightRulesCreate" } ] }, "operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StrategyCarrierOperatingHourCreate" } }, "holidays_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierHolidaysHoursCreate" } ] }, "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", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } } }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "operating_hours": { "type": "object", "properties": { "value": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "inherited": { "type": "boolean" } }, "required": [ "inherited" ] }, "holidays_hours": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] }, "carrier_active": { "type": "boolean" }, "carrier": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } } }, "required": [ "name", "code", "capabilities" ] }, "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", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } } }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "operating_hours": { "type": "object", "properties": { "value": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "inherited": { "type": "boolean" } }, "required": [ "inherited" ] }, "holidays_hours": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] }, "carrier_active": { "type": "boolean" }, "carrier": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } } }, "required": [ "name", "code", "capabilities" ] }, "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" ] }, "CoverageCityUpdate": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" } }, "required": [ "city", "state" ] }, "CoverageZipRangeUpdate": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{8}$" }, "end": { "type": "string", "pattern": "^\\d{8}$" } }, "required": [ "start", "end" ] }, "PolygonGeometryUpdate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Polygon" ] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } } }, "required": [ "type", "coordinates" ] }, "CoverageAreaUpdate": { "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/CoverageCityUpdate" } }, "ranges": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CoverageZipRangeUpdate" } }, "polygon": { "$ref": "#/components/schemas/PolygonGeometryUpdate" } }, "required": [ "type" ] }, "StrategyCarrierFreightRulesUpdate": { "type": "object", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } }, "required": [ "sla_hours", "fixed_cost", "cost_per_kg" ] }, "StrategyCarrierOperatingHourUpdate": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] }, "StrategyCarrierHolidaysHoursUpdate": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] }, "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/CoverageAreaUpdate" } ] }, "freight_rules": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierFreightRulesUpdate" } ] }, "operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StrategyCarrierOperatingHourUpdate" } }, "holidays_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyCarrierHolidaysHoursUpdate" } ] }, "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", "properties": { "sla_hours": { "type": "number" }, "fixed_cost": { "type": "number" }, "cost_per_kg": { "type": "number" } } }, "inherited": { "type": "boolean" } }, "required": [ "value", "inherited" ] }, "operating_hours": { "type": "object", "properties": { "value": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "day", "open", "close" ] } }, "inherited": { "type": "boolean" } }, "required": [ "inherited" ] }, "holidays_hours": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } }, "required": [ "open", "close" ] }, "carrier_active": { "type": "boolean" }, "carrier": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "capabilities": { "type": "object", "properties": { "tracking": { "type": "boolean" }, "same_day": { "type": "boolean" }, "returns": { "type": "boolean" } } } }, "required": [ "name", "code", "capabilities" ] }, "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" ] }, "state_machine_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" } }, "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", "state_machine_id", "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" ] }, "StrategyAddressCreate": { "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" ] }, "StrategyContactCreate": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "phone": { "type": "string", "nullable": true } } }, "StrategyOperatingHourCreate": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day" ] }, "StrategyHolidayHoursCreate": { "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 }, "state_machine_id": { "type": "string", "nullable": true }, "color": { "type": "string" }, "address": { "$ref": "#/components/schemas/StrategyAddressCreate" }, "contact": { "$ref": "#/components/schemas/StrategyContactCreate" }, "operating_hours": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyOperatingHourCreate" } }, "holiday_operating_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyHolidayHoursCreate" } ] }, "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 }, "state_machine_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", "state_machine_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" ] }, "state_machine_id": { "type": "string", "nullable": true }, "state_machine": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "entity_type": { "enum": [ "ORDER", "FULFILLMENT_ORDER" ], "type": "string" }, "is_default": { "type": "boolean" }, "active": { "type": "boolean" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "states": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "actions" ] } } }, "required": [ "id", "code", "name", "entity_type", "is_default", "active" ] }, "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", "state_machine_id", "state_machine", "color", "daily_capacity", "address", "contact", "operating_hours", "holiday_operating_hours", "tags", "metadata", "created_at", "updated_at" ] }, "StrategyAddressUpdate": { "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" ] }, "StrategyContactUpdate": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "phone": { "type": "string", "nullable": true } } }, "StrategyOperatingHourUpdate": { "type": "object", "properties": { "day": { "type": "string" }, "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } }, "required": [ "day" ] }, "StrategyHolidayHoursUpdate": { "type": "object", "properties": { "is_24h": { "type": "boolean" }, "opens_at": { "type": "string", "nullable": true }, "closes_at": { "type": "string", "nullable": true } } }, "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 }, "state_machine_id": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyAddressUpdate" } ] }, "contact": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyContactUpdate" } ] }, "operating_hours": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StrategyOperatingHourUpdate" } }, "holiday_operating_hours": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StrategyHolidayHoursUpdate" } ] }, "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 }, "state_machine_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", "state_machine_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" ] }, "StateMachineListItemResponse": { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string", "nullable": true }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } } } } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "states", "id", "entity_type", "code", "name", "transitions", "active", "is_default", "version", "created_at", "updated_at" ] }, "StateMachineListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "StateMachineTransitionCreate": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "StateMachineStateConfigCreate": { "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/StateMachineTransitionCreate" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateConfigCreate" } } }, "required": [ "entityType", "code", "name", "transitions" ] }, "StateMachineCreateResponse": { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } } } } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "states", "id", "entity_type", "code", "name", "transitions", "active", "is_default", "version", "created_at", "updated_at" ] }, "StateMachineFindResponse": { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string", "nullable": true }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } } } } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "states", "id", "entity_type", "code", "name", "transitions", "active", "is_default", "version", "created_at", "updated_at" ] }, "StateMachineGenerateFulfillmentActionUpdate": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "StateMachineTransitionUpdate": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "StateMachineStateConfigUpdate": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "StateMachineUpdate": { "type": "object", "properties": { "generateFulfillmentAction": { "$ref": "#/components/schemas/StateMachineGenerateFulfillmentActionUpdate" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineTransitionUpdate" } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateMachineStateConfigUpdate" } }, "active": { "type": "boolean" } } }, "StateMachineUpdateResponse": { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } } } } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "states", "id", "entity_type", "code", "name", "transitions", "active", "is_default", "version", "created_at", "updated_at" ] }, "SetDefaultStateMachineResponse": { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "GENERATE_FULFILLMENT", "RESERVE_INVENTORY", "COMMIT_INVENTORY", "RELEASE_INVENTORY" ] } } } } }, "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "name": { "type": "string" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "states", "id", "entity_type", "code", "name", "transitions", "active", "is_default", "version", "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" }, "description": { "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", "description", "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 }, "description": { "type": "string", "minLength": 1, "maxLength": 60 }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ] }, "color": { "type": "string" } }, "required": [ "entityType", "code", "label", "description", "nature", "color" ] }, "StatusCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ORDER", "FULFILLMENT_ORDER" ] }, "code": { "type": "string" }, "label": { "type": "string" }, "description": { "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", "description", "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" }, "description": { "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", "description", "nature", "color", "origin", "active", "created_at", "updated_at" ] }, "StatusUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 60 }, "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" }, "description": { "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", "description", "nature", "color", "origin", "active", "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", "properties": { "type": { "enum": [ "FIXED", "PERCENTAGE" ], "type": "string" }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "price_list_id": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "enum": [ "MINUTES", "HOURS", "DAYS" ], "type": "string" } }, "required": [ "value", "unit" ] }, "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_id", "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" ] }, "InventoryAllocationCreate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FIXED", "PERCENTAGE" ] }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "DeliveryPromiseCreate": { "type": "object", "properties": { "value": { "type": "number", "minimum": 1 }, "unit": { "type": "string", "enum": [ "MINUTES", "HOURS", "DAYS" ] } }, "required": [ "value", "unit" ] }, "StrategyChannelCreate": { "type": "object", "properties": { "price_list_id": { "type": "string", "nullable": true, "format": "uuid" }, "channel_code": { "type": "string" }, "active": { "type": "boolean" }, "inventory_allocation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryAllocationCreate" } ] }, "delivery_promise": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromiseCreate" } ] }, "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", "properties": { "type": { "enum": [ "FIXED", "PERCENTAGE" ], "type": "string" }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "price_list_id": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "enum": [ "MINUTES", "HOURS", "DAYS" ], "type": "string" } }, "required": [ "value", "unit" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_id", "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", "properties": { "type": { "enum": [ "FIXED", "PERCENTAGE" ], "type": "string" }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "price_list_id": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "enum": [ "MINUTES", "HOURS", "DAYS" ], "type": "string" } }, "required": [ "value", "unit" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_id", "delivery_promise", "created_at", "updated_at" ] }, "InventoryAllocationUpdate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FIXED", "PERCENTAGE" ] }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "DeliveryPromiseUpdate": { "type": "object", "properties": { "value": { "type": "number", "minimum": 1 }, "unit": { "type": "string", "enum": [ "MINUTES", "HOURS", "DAYS" ] } }, "required": [ "value", "unit" ] }, "StrategyChannelUpdate": { "type": "object", "properties": { "price_list_id": { "type": "string", "nullable": true, "format": "uuid" }, "active": { "type": "boolean" }, "inventory_allocation": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InventoryAllocationUpdate" } ] }, "delivery_promise": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DeliveryPromiseUpdate" } ] }, "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", "properties": { "type": { "enum": [ "FIXED", "PERCENTAGE" ], "type": "string" }, "value": { "type": "number" } }, "required": [ "type", "value" ] }, "price_list_id": { "type": "string", "nullable": true }, "delivery_promise": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "enum": [ "MINUTES", "HOURS", "DAYS" ], "type": "string" } }, "required": [ "value", "unit" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "strategy_id", "channel_code", "active", "inventory_allocation", "price_list_id", "delivery_promise", "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_id": { "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_id", "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 PRICE_LIST_ITEM_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) 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" ] }, "CustomerListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "PF", "PJ" ] }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "name", "email", "phone", "birth_date", "metadata", "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": { "document": { "type": "string", "nullable": true, "description": "CPF (11 digits) or CNPJ (14 characters). Optional." }, "type": { "nullable": true, "enum": [ "PF", "PJ" ], "type": "string" }, "birth_date": { "type": "string", "example": "1990-05-20", "description": "Date of birth." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "email": { "type": "string", "nullable": true, "maxLength": 254 }, "phone": { "type": "string", "nullable": true, "maxLength": 30 } }, "required": [ "name" ] }, "CustomerCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "PF", "PJ" ] }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "name", "email", "phone", "birth_date", "metadata", "created_at", "updated_at" ] }, "CustomerFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "PF", "PJ" ] }, "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 }, "metadata": { "type": "object", "nullable": true }, "total_orders": { "type": "number" }, "total_spent": { "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", "external_id", "name", "email", "phone", "birth_date", "metadata", "total_orders", "total_spent", "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" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "name": { "type": "string", "minLength": 2, "maxLength": 200 } } }, "CustomerUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "PF", "PJ" ] }, "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 }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "document", "type", "external_id", "name", "email", "phone", "birth_date", "metadata", "created_at", "updated_at" ] }, "CustomerAddressCreate": { "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" ] }, "CustomerAddressCreateResponse": { "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 }, "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" ] }, "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" ] }, "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" ] }, "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" ] }, "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" } } }, "required": [ "items" ] }, "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) shared by every published event.", "example": "8f2a3b1c-7d6e-4f5a-9b8c-1d2e3f4a5b6c" }, "update_type": { "type": "string", "enum": [ "SNAPSHOT" ], "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": { "type": "string", "enum": [ "SNAPSHOT" ] }, "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" }, "code": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "required": [ "name", "code", "email" ] }, "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" ] }, "OrderAddressCreate": { "type": "object", "properties": { "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" } }, "required": [ "zip_code", "street", "number", "district", "city", "state", "country" ] }, "OrderItemCreate": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "number", "minimum": 1 }, "unit_price": { "type": "number", "minimum": 0 }, "discount": { "type": "number", "minimum": 0 }, "total_price": { "type": "number", "minimum": 0 }, "category": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "required": [ "sku", "name", "quantity", "unit_price", "total_price" ] }, "OrderPaymentInput": { "type": "object", "properties": { "method": { "type": "string" }, "amount": { "type": "number", "minimum": 0 }, "installments": { "type": "number", "minimum": 1 }, "gateway_payment_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REJECTED", "REFUNDED" ] } }, "required": [ "method", "amount", "status" ] }, "OrderTotalsCreate": { "type": "object", "properties": { "subtotal": { "type": "number", "minimum": 0 }, "shipping": { "type": "number", "minimum": 0 }, "discount": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 } }, "required": [ "subtotal", "shipping", "discount", "total" ] }, "OrderCreate": { "type": "object", "properties": { "requested_strategy_code": { "type": "string", "nullable": true }, "source_store": { "type": "string", "nullable": true }, "shipping_method": { "type": "string", "nullable": true }, "currency": { "enum": [ "BRL", "USD" ], "type": "string", "default": "BRL" }, "customer_id": { "type": "string", "nullable": true, "format": "uuid" }, "shipping_address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressCreate" } ] }, "billing_address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrderAddressCreate" } ] }, "items": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/OrderItemCreate" } }, "payments": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/OrderPaymentInput" } }, "totals": { "$ref": "#/components/schemas/OrderTotalsCreate" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "external_order_id": { "type": "string" }, "channel_code": { "type": "string" } }, "required": [ "items", "payments", "totals", "external_order_id", "channel_code" ] }, "OrderCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "external_order_id": { "type": "string" }, "channel_id": { "type": "string" }, "customer_id": { "type": "string", "nullable": true }, "requested_strategy_code": { "type": "string", "nullable": true }, "source_store": { "type": "string", "nullable": true }, "shipping_method": { "type": "string", "nullable": true }, "status": { "type": "string" }, "state_machine_version_id": { "type": "string" }, "state_machine_id": { "type": "string" }, "currency": { "type": "string", "enum": [ "BRL", "USD" ] }, "subtotal": { "type": "number" }, "shipping": { "type": "number" }, "discount": { "type": "number" }, "total": { "type": "number" }, "item_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_order_id", "channel_id", "customer_id", "requested_strategy_code", "source_store", "shipping_method", "status", "state_machine_version_id", "state_machine_id", "currency", "subtotal", "shipping", "discount", "total", "item_count", "created_at", "updated_at" ] }, "OrderStatusUpdate": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "status": { "type": "string" } }, "required": [ "status" ] }, "OrderStatusUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "previous_status": { "type": "string" }, "updated_at": { "type": "string" }, "event_id": { "type": "string" } }, "required": [ "id", "status", "previous_status", "updated_at", "event_id" ] }, "OrderAddressUpdate": { "type": "object", "properties": { "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" } }, "required": [ "zip_code", "street", "number", "district", "city", "state", "country" ] }, "OrderAddressesUpdate": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 }, "shipping_address": { "$ref": "#/components/schemas/OrderAddressUpdate" } }, "required": [ "reason", "shipping_address" ] }, "OrderAddressesUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "updated_at": { "type": "string" }, "shipping_address": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "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" }, "updated_at": { "type": "string" } }, "required": [ "id", "type", "zip_code", "street", "number", "complement", "district", "city", "state", "country", "updated_at" ] } }, "required": [ "id", "updated_at", "shipping_address" ] }, "CancelOrder": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Free-text reason for the cancellation. Recorded inside the timeline event metadata." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Free-form cancellation context (e.g. refund_status). Merged verbatim into the timeline event; the server-validated reason always wins over a same-named key here." } }, "required": [ "reason" ] }, "CancelOrderResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "previous_status": { "type": "string" }, "metadata": { "type": "object" }, "updated_at": { "type": "string" }, "event_id": { "type": "string" } }, "required": [ "id", "status", "previous_status", "metadata", "updated_at", "event_id" ] }, "OrderListItemResponse": { "type": "object", "properties": { "channel": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "status": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string", "nullable": true }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ], "nullable": true } } }, "customer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "document": { "type": "string", "nullable": true }, "document_type": { "type": "string", "enum": [ "PF", "PJ" ], "nullable": true } } }, "id": { "type": "string" }, "external_order_id": { "type": "string" }, "item_count": { "type": "number" }, "total": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "channel", "status", "customer", "id", "external_order_id", "item_count", "total", "created_at", "updated_at" ] }, "OrderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "OrderFindResponse": { "type": "object", "properties": { "status": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string", "nullable": true }, "nature": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINAL", "ERROR" ], "nullable": true } } }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "customer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "document": { "type": "string", "nullable": true }, "document_type": { "type": "string", "enum": [ "PF", "PJ" ], "nullable": true }, "external_id": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "nullable": true } } }, "state_machine": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "number" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } } } } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "timeline": { "type": "array", "description": "Unified chronological timeline of the order journey, merging order status events (type=order), fulfillment order status events (type=fulfillment) and shipment tracking events (type=shipment). Shipment events carry the resolved carrier and tracking code under the shipment block.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "order", "fulfillment", "shipment" ] }, "status": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "occurred_at": { "type": "string" }, "shipment": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "carrier": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "tracking_code": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "event_id": { "type": "string", "nullable": true } } } } } }, "fulfillments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "store": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "nullable": true }, "sku": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "number" } } } } } } }, "id": { "type": "string" }, "external_order_id": { "type": "string" }, "requested_strategy_code": { "type": "string", "nullable": true }, "source_store": { "type": "string", "nullable": true }, "shipping_method": { "type": "string", "nullable": true }, "currency": { "type": "string", "enum": [ "BRL", "USD" ] }, "shipping_address": { "type": "object", "properties": { "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" } }, "required": [ "zip_code", "street", "number", "complement", "district", "city", "state", "country" ] }, "billing_address": { "type": "object", "properties": { "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" } }, "required": [ "zip_code", "street", "number", "complement", "district", "city", "state", "country" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "discount": { "type": "number" }, "total_price": { "type": "number" }, "metadata": { "type": "object", "nullable": true } }, "required": [ "sku", "name", "category", "quantity", "unit_price", "discount", "total_price", "metadata" ] } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "method": { "type": "string" }, "amount": { "type": "number" }, "currency": { "enum": [ "BRL", "USD" ], "type": "string" }, "installments": { "type": "number" }, "status": { "enum": [ "PENDING", "PAID", "REJECTED", "REFUNDED" ], "type": "string" }, "gateway": { "type": "string", "nullable": true }, "gateway_payment_id": { "type": "string", "nullable": true }, "authorization_code": { "type": "string", "nullable": true }, "nsu": { "type": "string", "nullable": true }, "acquirer": { "type": "string", "nullable": true }, "card": { "type": "object", "properties": { "brand": { "type": "string", "nullable": true }, "last4": { "type": "string", "nullable": true }, "funding": { "type": "string", "nullable": true }, "exp_month": { "type": "number", "nullable": true }, "exp_year": { "type": "number", "nullable": true } } }, "pix": { "type": "object", "properties": { "txid": { "type": "string", "nullable": true }, "e2eid": { "type": "string", "nullable": true }, "qr_code": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "nullable": true } } }, "boleto": { "type": "object", "properties": { "digitable_line": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "due_date": { "type": "string", "nullable": true } } }, "paid_at": { "type": "string", "nullable": true }, "refunded_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "method", "amount", "currency", "installments", "status", "gateway", "gateway_payment_id", "authorization_code", "nsu", "acquirer", "card", "pix", "boleto", "paid_at", "refunded_at", "created_at", "updated_at" ] } }, "totals": { "type": "object", "properties": { "subtotal": { "type": "number" }, "shipping": { "type": "number" }, "discount": { "type": "number" }, "total": { "type": "number" } }, "required": [ "subtotal", "shipping", "discount", "total" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "status", "channel", "customer", "state_machine", "metadata", "timeline", "fulfillments", "id", "external_order_id", "requested_strategy_code", "source_store", "shipping_method", "currency", "shipping_address", "billing_address", "items", "payments", "totals", "created_at", "updated_at" ] }, "OrderPaymentCreate": { "type": "object", "properties": { "currency": { "enum": [ "BRL", "USD" ], "type": "string" }, "installments": { "type": "number", "minimum": 1 }, "gateway": { "type": "string", "nullable": true }, "gateway_payment_id": { "type": "string", "nullable": true }, "method": { "type": "string" }, "amount": { "type": "number", "minimum": 1 }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "REJECTED", "REFUNDED" ] } }, "required": [ "method", "amount", "status" ] }, "OrderPaymentCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "order_status": { "type": "string" }, "method": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "installments": { "type": "number" }, "status": { "type": "string" }, "gateway": { "type": "string", "nullable": true }, "gateway_payment_id": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "order_id", "order_status", "method", "amount", "currency", "installments", "status", "gateway", "gateway_payment_id", "created_at" ] }, "OrderPaymentUpdate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "PAID", "REJECTED", "REFUNDED" ] } }, "required": [ "status" ] }, "OrderPaymentUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "order_status": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "updated_at": { "type": "string" } }, "required": [ "id", "order_id", "order_status", "status", "amount", "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" ] }, "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 }, "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" ] }, "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" ] }, "OrderFulfillmentTrackingEventResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "previous_status": { "type": "string", "nullable": true }, "new_status": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "service_account_id": { "type": "string", "nullable": true }, "occurred_at": { "type": "string" } }, "required": [ "metadata", "id", "previous_status", "new_status", "user_id", "service_account_id", "occurred_at" ] }, "OrderFulfillmentShipmentPackageResponse": { "type": "object", "properties": { "dimensions": { "type": "object", "nullable": true, "properties": { "length_cm": { "type": "number" }, "width_cm": { "type": "number" }, "height_cm": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" } } } }, "weight_kg": { "type": "number", "nullable": true }, "label_url": { "type": "string", "nullable": true } }, "required": [ "dimensions", "items", "weight_kg", "label_url" ] }, "OrderFulfillmentShipmentTrackingEventResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "source": { "type": "string", "nullable": true }, "event_id": { "type": "string", "nullable": true }, "occurred_at": { "type": "string" } }, "required": [ "id", "status", "source", "event_id", "occurred_at" ] }, "OrderFulfillmentShipmentResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/OrderFulfillmentShipmentPackageResponse" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "tracking_events": { "type": "array", "items": { "$ref": "#/components/schemas/OrderFulfillmentShipmentTrackingEventResponse" } }, "id": { "type": "string" }, "carrier_id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "tracking_code": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "dispatched_at": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "packages", "metadata", "tracking_events", "id", "carrier_id", "status", "tracking_code", "label", "dispatched_at", "delivered_at", "created_at", "updated_at" ] }, "OrderFulfillmentOrderListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "tracking_events": { "type": "array", "items": { "$ref": "#/components/schemas/OrderFulfillmentTrackingEventResponse" } }, "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/OrderFulfillmentShipmentResponse" } }, "id": { "type": "string" }, "order_id": { "type": "string" }, "strategy_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "tracking_events", "shipments", "id", "order_id", "strategy_id", "status", "created_at", "updated_at" ] }, "OrderFulfillmentOrderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderFulfillmentOrderListItemResponse" } } }, "required": [ "data" ] }, "FulfillmentOrderListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "order_id": { "type": "string" }, "strategy_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "metadata", "id", "order_id", "strategy_id", "status", "created_at", "updated_at" ] }, "FulfillmentOrderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "FulfillmentOrderFindItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "discount": { "type": "number" }, "total_price": { "type": "number" } }, "required": [ "metadata", "sku", "name", "category", "quantity", "unit_price", "discount", "total_price" ] }, "FulfillmentOrderTimelineFindResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "previous_status": { "type": "string", "nullable": true }, "new_status": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "service_account_id": { "type": "string", "nullable": true }, "occurred_at": { "type": "string" } }, "required": [ "metadata", "id", "previous_status", "new_status", "user_id", "service_account_id", "occurred_at" ] }, "FulfillmentOrderShipmentPackageFindResponse": { "type": "object", "properties": { "dimensions": { "type": "object", "nullable": true, "properties": { "length_cm": { "type": "number" }, "width_cm": { "type": "number" }, "height_cm": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" } } } }, "weight_kg": { "type": "number", "nullable": true }, "label_url": { "type": "string", "nullable": true } }, "required": [ "dimensions", "items", "weight_kg", "label_url" ] }, "FulfillmentOrderShipmentTimelineFindResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "occurred_at": { "type": "string" }, "source": { "type": "string", "nullable": true }, "event_id": { "type": "string", "nullable": true } }, "required": [ "id", "status", "occurred_at", "source", "event_id" ] }, "FulfillmentOrderShipmentFindResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentPackageFindResponse" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "occurred_at": { "type": "string" }, "source": { "type": "string", "nullable": true }, "event_id": { "type": "string", "nullable": true } } } }, "id": { "type": "string" }, "fulfillment_order_id": { "type": "string" }, "order_id": { "type": "string" }, "carrier_id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "tracking_code": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "dispatched_at": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "packages", "metadata", "timeline", "id", "fulfillment_order_id", "order_id", "carrier_id", "status", "tracking_code", "label", "dispatched_at", "delivered_at", "created_at", "updated_at" ] }, "FulfillmentOrderFindResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderFindItemResponse" } }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderTimelineFindResponse" } }, "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentFindResponse" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "order_id": { "type": "string" }, "strategy_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "items", "timeline", "shipments", "metadata", "id", "order_id", "strategy_id", "status", "created_at", "updated_at" ] }, "CancelFulfillmentOrder": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Free-text reason for the cancellation. Recorded inside the timeline event metadata." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Free-form cancellation context (e.g. refund_status). Merged verbatim into the timeline event; the server-validated reason always wins over a same-named key here." } }, "required": [ "reason" ] }, "CancelFulfillmentOrderResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "previous_status": { "type": "string" }, "metadata": { "type": "object" }, "updated_at": { "type": "string" }, "event_id": { "type": "string" } }, "required": [ "id", "status", "previous_status", "metadata", "updated_at", "event_id" ] }, "FulfillmentOrderStatusUpdate": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "status": { "type": "string" } }, "required": [ "status" ] }, "FulfillmentOrderStatusUpdateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "previous_status": { "type": "string" }, "updated_at": { "type": "string" }, "event_id": { "type": "string" } }, "required": [ "id", "status", "previous_status", "updated_at", "event_id" ] }, "FulfillmentOrderShipmentPackageResponse": { "type": "object", "properties": { "dimensions": { "type": "object", "nullable": true, "properties": { "length_cm": { "type": "number" }, "width_cm": { "type": "number" }, "height_cm": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" } } } }, "weight_kg": { "type": "number", "nullable": true }, "label_url": { "type": "string", "nullable": true } }, "required": [ "dimensions", "items", "weight_kg", "label_url" ] }, "FulfillmentOrderShipmentListItemResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentPackageResponse" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "fulfillment_order_id": { "type": "string" }, "order_id": { "type": "string" }, "carrier_id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "tracking_code": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "dispatched_at": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "packages", "metadata", "id", "fulfillment_order_id", "order_id", "carrier_id", "status", "tracking_code", "label", "dispatched_at", "delivered_at", "created_at", "updated_at" ] }, "FulfillmentOrderShipmentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "FulfillmentOrderShipmentPackageDimensionsCreate": { "type": "object", "properties": { "length_cm": { "type": "number", "minimum": 1, "description": "Comprimento em cm (> 0).", "example": 20 }, "width_cm": { "type": "number", "minimum": 1, "description": "Largura em cm (> 0).", "example": 15 }, "height_cm": { "type": "number", "minimum": 1, "description": "Altura em cm (> 0).", "example": 10 } }, "required": [ "length_cm", "width_cm", "height_cm" ] }, "FulfillmentOrderShipmentPackageItemCreate": { "type": "object", "properties": { "sku": { "type": "string", "description": "SKU do item embarcado.", "example": "SKU-001" }, "quantity": { "type": "number", "minimum": 1, "description": "Quantidade do item no volume (inteiro > 0).", "example": 2 } }, "required": [ "sku", "quantity" ] }, "FulfillmentOrderShipmentPackageCreate": { "type": "object", "properties": { "weight_kg": { "type": "number", "nullable": true, "minimum": 1, "description": "Peso do volume em kg (> 0).", "example": 1.5 }, "dimensions": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/FulfillmentOrderShipmentPackageDimensionsCreate" } ] }, "items": { "minItems": 1, "description": "Itens do volume (>= 1).", "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentPackageItemCreate" } }, "label_url": { "type": "string", "nullable": true, "description": "URL da etiqueta do volume, quando o carrier a emite." } }, "required": [ "items" ] }, "FulfillmentOrderShipmentCreate": { "type": "object", "properties": { "carrier_id": { "type": "string", "description": "Identificador (UUID) da transportadora cadastrada.", "example": "9a29b0c5-faff-4149-b7dd-5eeca344d157" }, "tracking_code": { "type": "string", "nullable": true, "description": "Código de rastreio, quando já atribuído pela transportadora. Ausente na criação até o despacho.", "example": "BR123456789BR" }, "label": { "type": "string", "nullable": true, "description": "Referência da etiqueta de transporte, quando o carrier a emite." }, "packages": { "minItems": 1, "description": "Volumes da remessa (>= 1).", "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentPackageCreate" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "carrier_id", "packages" ] }, "FulfillmentOrderShipmentPackageCreateResponse": { "type": "object", "properties": { "dimensions": { "type": "object", "nullable": true, "properties": { "length_cm": { "type": "number" }, "width_cm": { "type": "number" }, "height_cm": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" } } } }, "weight_kg": { "type": "number", "nullable": true }, "label_url": { "type": "string", "nullable": true } }, "required": [ "dimensions", "items", "weight_kg", "label_url" ] }, "FulfillmentOrderShipmentCreateResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentPackageCreateResponse" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "shipment_id": { "type": "string" }, "fo_status": { "type": "string" }, "fulfillment_order_id": { "type": "string" }, "order_id": { "type": "string" }, "carrier_id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "tracking_code": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "dispatched_at": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "packages", "metadata", "shipment_id", "fo_status", "fulfillment_order_id", "order_id", "carrier_id", "status", "tracking_code", "label", "dispatched_at", "delivered_at", "created_at", "updated_at" ] }, "FulfillmentOrderShipmentTrackingEventListItemResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "SHIPMENT_CREATED", "DISPATCHED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_FAILED", "RETURNED", "LOST", "LABEL_CREATED", "AWAITING_PICKUP", "IN_TRANSFER" ] }, "occurred_at": { "type": "string" }, "source": { "type": "string", "nullable": true }, "event_id": { "type": "string", "nullable": true } }, "required": [ "id", "status", "occurred_at", "source", "event_id" ] }, "FulfillmentOrderShipmentTrackingEventListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderShipmentTrackingEventListItemResponse" } } }, "required": [ "data" ] }, "FulfillmentOrderTrackingEventListItemResponse": { "type": "object", "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "previous_status": { "type": "string", "nullable": true }, "new_status": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "service_account_id": { "type": "string", "nullable": true }, "occurred_at": { "type": "string" } }, "required": [ "metadata", "id", "previous_status", "new_status", "user_id", "service_account_id", "occurred_at" ] }, "FulfillmentOrderTrackingEventListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentOrderTrackingEventListItemResponse" } } }, "required": [ "data" ] }, "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" ] }, "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" ] }, "PromotionValidityCreate": { "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" ] }, "PromotionEligibilityCreate": { "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" ] }, "PromotionBenefitCreate": { "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" ] }, "PromotionItemRestrictionCreate": { "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" ] }, "PromotionConditionCreate": { "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" ] }, "PromotionEligibleItemsLimitCreate": { "type": "object", "properties": { "limit": { "type": "number" }, "count_by": { "type": "string", "enum": [ "ORDER", "PRODUCT" ] } }, "required": [ "limit", "count_by" ] }, "PromotionUsageLimitsCreate": { "type": "object", "properties": { "per_customer": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "eligible_items": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/PromotionEligibleItemsLimitCreate" } ] } } }, "PromotionAccumulationCreate": { "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/PromotionValidityCreate" }, "eligibility": { "$ref": "#/components/schemas/PromotionEligibilityCreate" }, "benefit": { "$ref": "#/components/schemas/PromotionBenefitCreate" }, "item_restrictions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionItemRestrictionCreate" } }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionConditionCreate" } }, "usage_limits": { "$ref": "#/components/schemas/PromotionUsageLimitsCreate" }, "accumulation": { "$ref": "#/components/schemas/PromotionAccumulationCreate" }, "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" ] }, "PromotionValidityUpdate": { "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" ] }, "PromotionEligibilityUpdate": { "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" ] }, "PromotionBenefitUpdate": { "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" ] }, "PromotionItemRestrictionUpdate": { "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" ] }, "PromotionConditionUpdate": { "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" ] }, "PromotionEligibleItemsLimitUpdate": { "type": "object", "properties": { "limit": { "type": "number" }, "count_by": { "type": "string", "enum": [ "ORDER", "PRODUCT" ] } }, "required": [ "limit", "count_by" ] }, "PromotionUsageLimitsUpdate": { "type": "object", "properties": { "per_customer": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "eligible_items": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/PromotionEligibleItemsLimitUpdate" } ] } } }, "PromotionAccumulationUpdate": { "type": "object", "properties": { "with_discount_promotions": { "type": "boolean" }, "with_manual_prices": { "type": "boolean" } }, "required": [ "with_discount_promotions", "with_manual_prices" ] }, "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/PromotionValidityUpdate" }, "eligibility": { "$ref": "#/components/schemas/PromotionEligibilityUpdate" }, "benefit": { "$ref": "#/components/schemas/PromotionBenefitUpdate" }, "item_restrictions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionItemRestrictionUpdate" } }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionConditionUpdate" } }, "usage_limits": { "$ref": "#/components/schemas/PromotionUsageLimitsUpdate" }, "accumulation": { "$ref": "#/components/schemas/PromotionAccumulationUpdate" }, "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" ] }, "StrategyPriceListListItemResponse": { "type": "object", "properties": { "price_list": { "type": "object", "properties": { "name": { "type": "string" }, "items_count": { "type": "number" } }, "required": [ "name", "items_count" ] }, "id": { "type": "string" }, "strategy_id": { "type": "string" }, "price_list_id": { "type": "string" }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "price_list", "id", "strategy_id", "price_list_id", "active", "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" ] }, "WebhookSubscriptionListItemResponse": { "type": "object", "properties": { "status": { "enum": [ "ACTIVE", "DISABLED_BY_FAILURES", "DISABLED_BY_USER" ], "type": "string" }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ] } }, "disabled_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "status", "headers", "metadata", "id", "name", "url", "event_types", "disabled_at", "created_at", "updated_at" ] }, "WebhookSubscriptionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionListItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMetaResponse" } }, "required": [ "data", "meta" ] }, "WebhookSubscriptionCreate": { "type": "object", "properties": { "event_types": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ] } }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "event_types", "name", "url" ] }, "WebhookSubscriptionCreateResponse": { "type": "object", "properties": { "status": { "enum": [ "ACTIVE", "DISABLED_BY_FAILURES", "DISABLED_BY_USER" ], "type": "string" }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ] } }, "disabled_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "status", "headers", "metadata", "id", "name", "url", "event_types", "disabled_at", "created_at", "updated_at" ] }, "WebhookEventTypeItemResponse": { "type": "object", "properties": { "value": { "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ], "type": "string" }, "label": { "type": "string", "example": "Pedido criado" } }, "required": [ "value", "label" ] }, "WebhookEventTypesListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventTypeItemResponse" } } }, "required": [ "data" ] }, "WebhookSubscriptionFindResponse": { "type": "object", "properties": { "status": { "enum": [ "ACTIVE", "DISABLED_BY_FAILURES", "DISABLED_BY_USER" ], "type": "string" }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ] } }, "disabled_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "status", "headers", "metadata", "id", "name", "url", "event_types", "disabled_at", "created_at", "updated_at" ] }, "WebhookSubscriptionUpdate": { "type": "object", "properties": { "event_types": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ] } }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "active": { "type": "boolean" } } }, "WebhookSubscriptionUpdateResponse": { "type": "object", "properties": { "status": { "enum": [ "ACTIVE", "DISABLED_BY_FAILURES", "DISABLED_BY_USER" ], "type": "string" }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "ORDER_CREATED", "ORDER_STATUS_CHANGED" ] } }, "disabled_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "status", "headers", "metadata", "id", "name", "url", "event_types", "disabled_at", "created_at", "updated_at" ] } } } }