{
    "openapi": "3.0.0",
    "info": {
        "title": "qore/api",
        "description": "Qore B2B REST API",
        "version": "2.24.0"
    },
    "paths": {
        "/v2/addresses/check": {
            "post": {
                "tags": [
                    "Addresses"
                ],
                "summary": "Verify a postal address",
                "description": "Checks an address against a geocoder (default) or the GLS Italia street registry (`provider: \"gls\"`, Italian addresses only, requires GLS configured on the channel). The response shape is the same for both: `coordinates` is filled by the geocoder, `delivery` and `candidates` by GLS. An address that cannot be matched is not an error \u2014 it returns 200 with `match.status = NONE`. Every accepted request is billed, whatever the outcome.",
                "operationId": "post_api_addresses_check",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AddressCheckRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Verification result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AddressCheckResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized - missing or invalid token"
                    },
                    "403": {
                        "description": "Insufficient scope, product `checkAddress` not owned, or address check not enabled on the channel"
                    },
                    "422": {
                        "description": "Validation error, or the requested provider cannot serve this address (gls outside Italy, or GLS not configured on the channel)"
                    },
                    "429": {
                        "description": "Too Many Requests - rate limit exceeded"
                    },
                    "502": {
                        "description": "The address check provider is unreachable or answered unreadably"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/auth/token": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "Obtain JWT token",
                "description": "Exchange an API key for a JWT bearer token valid for 24 hours.",
                "operationId": "post_api_auth_token",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/TokenRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful authentication",
                        "headers": {
                            "X-Auth-Cache": {
                                "description": "Cache status (HIT or MISS)",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TokenResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing request body or malformed JSON"
                    },
                    "401": {
                        "description": "Invalid or inactive API key"
                    },
                    "422": {
                        "description": "Validation failed: apiKey is missing, empty or not a string"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/v2/couriers/efficiency-index": {
            "post": {
                "tags": [
                    "Couriers"
                ],
                "summary": "Score courier efficiency for a destination CAP",
                "description": "Returns, for each requested courier, a 0-100 efficiency index on the lane towards the given Italian CAP, with its speed/consistency/reliability sub-scores and a rank (best-first). The origin is resolved from the request `originCap` when provided, otherwise from the authenticated company seat (CAP + macro-area). `couriers` is optional: when omitted, the shipping-enabled couriers of the authenticated channel are scored. Requested couriers whose lane cell is suppressed (sample < 20) or has no usable speed are still returned, marked `insufficient_data` with a null rank.",
                "operationId": "post_api_couriers_efficiency_index",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CourierEfficiencyRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Efficiency-index ranking (best-first), with insufficient-data couriers appended.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CourierEfficiencyResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized - missing or invalid token"
                    },
                    "403": {
                        "description": "Forbidden - insufficient scope"
                    },
                    "422": {
                        "description": "Validation error (e.g. invalid destCap/originCap), or no couriers to score (none provided and the channel has no shipping-enabled couriers)"
                    },
                    "429": {
                        "description": "Too Many Requests - rate limit exceeded"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/couriers/delivery-times": {
            "post": {
                "tags": [
                    "Couriers"
                ],
                "summary": "Compare courier delivery times for a destination CAP",
                "description": "Returns the fastest courier towards the given Italian CAP, ordered by lead time. The origin is resolved from the request `originCap` when provided, otherwise from the authenticated company seat (CAP + macro-area). `couriers` is optional: when omitted, the shipping-enabled couriers of the authenticated channel are compared. By default (`detail: \"summary\"`) the response is slim: the `best` courier plus a `ranking` of the couriers with data and only the essential metrics. Pass `detail: \"full\"` for the complete ranking with all percentiles, grain, weight band and the couriers with insufficient data.",
                "operationId": "post_api_couriers_delivery_times",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/DeliveryTimesRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Delivery-time comparison. Shape depends on the request `detail`: DeliveryTimeSummaryResponse for \"summary\" (default), DeliveryTimeComparisonResponse for \"full\".",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/DeliveryTimeSummaryResponse"
                                        },
                                        {
                                            "$ref": "#/components/schemas/DeliveryTimeComparisonResponse"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized - missing or invalid token"
                    },
                    "403": {
                        "description": "Forbidden - insufficient scope"
                    },
                    "422": {
                        "description": "Validation error (e.g. invalid destCap/originCap), or no couriers to compare (none provided and the channel has no shipping-enabled couriers)"
                    },
                    "429": {
                        "description": "Too Many Requests - rate limit exceeded"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/jobs/{jobId}": {
            "get": {
                "tags": [
                    "Jobs"
                ],
                "summary": "Get job status",
                "description": "Retrieve the status and progress of an async job.",
                "operationId": "get_api_jobs_get",
                "parameters": [
                    {
                        "name": "jobId",
                        "in": "path",
                        "description": "The job ID",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Job status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "jobId": {
                                            "type": "string"
                                        },
                                        "type": {
                                            "type": "string"
                                        },
                                        "status": {
                                            "type": "string",
                                            "enum": [
                                                "pending",
                                                "processing",
                                                "completed",
                                                "failed"
                                            ]
                                        },
                                        "totalItems": {
                                            "type": "integer"
                                        },
                                        "processedItems": {
                                            "type": "integer"
                                        },
                                        "failedItems": {
                                            "type": "integer"
                                        },
                                        "result": {
                                            "type": "object",
                                            "nullable": true
                                        },
                                        "error": {
                                            "description": "Failure reason (populated only when status is failed)",
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "createdAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "completedAt": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Job not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/parcels": {
            "get": {
                "tags": [
                    "Parcels"
                ],
                "summary": "List parcels by order",
                "description": "Retrieve all parcels associated with a specific order.",
                "operationId": "get_api_parcels_list",
                "parameters": [
                    {
                        "name": "orderReference",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "orderOrigin",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 0,
                            "exclusiveMinimum": true
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100,
                            "minimum": 0,
                            "exclusiveMinimum": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of parcels",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ParcelPaginatedResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden - the required product (api-parcels) is not owned by the company, or the API key is temporarily suspended after repeated rate limit violations (see 429)."
                    },
                    "422": {
                        "description": "Validation error"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Parcels"
                ],
                "summary": "Create new parcels",
                "description": "Creates one or more parcels associated with an order.",
                "operationId": "post_api_parcels_create",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ParcelRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Parcels created successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/ParcelResponse"
                                    }
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Parcels processing asynchronously",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AsyncJobResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden - the required product (api-parcels) is not owned by the company, or the API key is temporarily suspended after repeated rate limit violations (see 429)."
                    },
                    "409": {
                        "description": "Conflict - An order with the same channel, origin and reference already exists"
                    },
                    "429": {
                        "description": "Too Many Requests - the channel rate limit was exceeded. The limit is a per-channel token bucket: the bucket size is the burst allowance, and it refills one whole cycle at a time (the full per-minute amount at once, not progressively), so a rejected caller waits for the next cycle. The platform defaults are a bucket of 300 with 150 tokens per minute, but a channel may have its own values: read the limit from the headers rather than assuming it. Ignoring this response and keeping the requests coming leads to a temporary suspension of the API key, returned as 403 and not as 429.",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying (RFC 6585)",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Bucket size (max tokens)",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Tokens left in the bucket; always 0 on this response",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Reset": {
                                "description": "Unix timestamp at which the bucket refills",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Parcels"
                ],
                "summary": "Delete parcels by order",
                "description": "Delete all parcels associated with a specific order.",
                "operationId": "delete_api_parcels_delete_by_order",
                "parameters": [
                    {
                        "name": "orderReference",
                        "in": "query",
                        "description": "The external order reference",
                        "required": true,
                        "schema": {
                            "description": "The external order reference",
                            "type": "string",
                            "example": "ORD-12345"
                        },
                        "example": "ORD-12345"
                    },
                    {
                        "name": "orderOrigin",
                        "in": "query",
                        "description": "The order origin channel",
                        "required": true,
                        "schema": {
                            "description": "The order origin channel",
                            "type": "string",
                            "example": "shopify"
                        },
                        "example": "shopify"
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Parcels deleted successfully"
                    },
                    "403": {
                        "description": "Forbidden - the required product (api-parcels) is not owned by the company, or the API key is temporarily suspended after repeated rate limit violations (see 429)."
                    },
                    "404": {
                        "description": "No parcels found for the given order"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/parcels/{hash}": {
            "get": {
                "tags": [
                    "Parcels"
                ],
                "summary": "Get parcel details",
                "description": "Retrieve details of a specific parcel by its hash.",
                "operationId": "get_api_parcels_get",
                "parameters": [
                    {
                        "name": "hash",
                        "in": "path",
                        "description": "The hash key of the parcel",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": ".+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Parcel details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ParcelResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden - the required product (api-parcels) is not owned by the company, or the API key is temporarily suspended after repeated rate limit violations (see 429)."
                    },
                    "404": {
                        "description": "Parcel not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Parcels"
                ],
                "summary": "Delete a parcel",
                "description": "Deletes a specific parcel by its hash.",
                "operationId": "delete_api_parcels_delete",
                "parameters": [
                    {
                        "name": "hash",
                        "in": "path",
                        "description": "The hash key of the parcel",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Parcel deleted successfully"
                    },
                    "403": {
                        "description": "Forbidden - the required product (api-parcels) is not owned by the company, or the API key is temporarily suspended after repeated rate limit violations (see 429)."
                    },
                    "404": {
                        "description": "Parcel not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Parcels"
                ],
                "summary": "Update a parcel",
                "description": "Partially update a specific parcel by its hash.",
                "operationId": "patch_api_parcels_patch",
                "parameters": [
                    {
                        "name": "hash",
                        "in": "path",
                        "description": "The hash key of the parcel",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Fields to update",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "weightKg": {
                                        "type": "number"
                                    },
                                    "lengthCm": {
                                        "type": "number"
                                    },
                                    "widthCm": {
                                        "type": "number"
                                    },
                                    "heightCm": {
                                        "type": "number"
                                    },
                                    "originCountryIso": {
                                        "type": "string"
                                    },
                                    "contentsDescription": {
                                        "type": "string"
                                    },
                                    "clientInternalCode": {
                                        "type": "string"
                                    },
                                    "shippingNotes": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Parcel updated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ParcelResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden - the required product (api-parcels) is not owned by the company, or the API key is temporarily suspended after repeated rate limit violations (see 429)."
                    },
                    "404": {
                        "description": "Parcel not found"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/sandbox/{id}": {
            "get": {
                "tags": [
                    "Sandbox"
                ],
                "summary": "Get a Sandbox entity by ID",
                "description": "Returns a single Sandbox entity matching the provided ID.",
                "operationId": "get_api_sandbox_get",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "The ID of the Sandbox entity",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful operation",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "id": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "stringValue": {
                                            "type": "string",
                                            "example": "test value"
                                        },
                                        "intValue": {
                                            "type": "integer",
                                            "example": 123
                                        },
                                        "boolValue": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "floatValue": {
                                            "type": "number",
                                            "format": "float",
                                            "example": 10.5
                                        },
                                        "dateTimeValue": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "createdAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "updatedAt": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Sandbox entity not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Sandbox"
                ],
                "summary": "Update a Sandbox entity",
                "description": "Updates an existing Sandbox entity with the provided value.",
                "operationId": "put_api_sandbox_update",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "The ID of the Sandbox entity",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Sandbox data",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "stringValue": {
                                        "type": "string",
                                        "example": "updated value"
                                    },
                                    "intValue": {
                                        "type": "integer",
                                        "example": 456
                                    },
                                    "boolValue": {
                                        "type": "boolean",
                                        "example": false
                                    },
                                    "floatValue": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 99.99
                                    },
                                    "dateTimeValue": {
                                        "type": "string",
                                        "format": "date-time",
                                        "example": "2023-10-27 10:00:00"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Sandbox entity updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "id": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "stringValue": {
                                            "type": "string",
                                            "example": "updated value"
                                        },
                                        "intValue": {
                                            "type": "integer",
                                            "example": 456
                                        },
                                        "boolValue": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "floatValue": {
                                            "type": "number",
                                            "format": "float",
                                            "example": 99.99
                                        },
                                        "dateTimeValue": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "createdAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "updatedAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Sandbox entity not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Sandbox"
                ],
                "summary": "Delete a Sandbox entity",
                "description": "Deletes a Sandbox entity by ID.",
                "operationId": "delete_api_sandbox_delete",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "The ID of the Sandbox entity",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Sandbox entity deleted"
                    },
                    "404": {
                        "description": "Sandbox entity not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Sandbox"
                ],
                "summary": "Partially update a Sandbox entity",
                "description": "Updates specific fields of an existing Sandbox entity.",
                "operationId": "patch_api_sandbox_patch",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "The ID of the Sandbox entity",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Sandbox data to patch",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "stringValue": {
                                        "type": "string",
                                        "example": "patched value",
                                        "nullable": true
                                    },
                                    "intValue": {
                                        "type": "integer",
                                        "example": 789,
                                        "nullable": true
                                    },
                                    "boolValue": {
                                        "type": "boolean",
                                        "example": true,
                                        "nullable": true
                                    },
                                    "floatValue": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 55.55,
                                        "nullable": true
                                    },
                                    "dateTimeValue": {
                                        "type": "string",
                                        "format": "date-time",
                                        "example": "2023-10-27 10:00:00",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Sandbox entity updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "id": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "stringValue": {
                                            "type": "string",
                                            "example": "patched value"
                                        },
                                        "intValue": {
                                            "type": "integer",
                                            "example": 789
                                        },
                                        "boolValue": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "floatValue": {
                                            "type": "number",
                                            "format": "float",
                                            "example": 55.55
                                        },
                                        "dateTimeValue": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "createdAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "updatedAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Sandbox entity not found"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/sandbox": {
            "get": {
                "tags": [
                    "Sandbox"
                ],
                "summary": "Get a list of Sandbox entities",
                "description": "Returns a paginated list of Sandbox entities.",
                "operationId": "get_api_sandbox_list",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "The page number",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "The number of items per page",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 20
                        }
                    },
                    {
                        "name": "updatedAfter",
                        "in": "query",
                        "description": "Filter by updated_at >= date",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "updatedBefore",
                        "in": "query",
                        "description": "Filter by updated_at <= date",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "updatedAfterDateTime",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "title": "Convert updatedAfter string to DateTimeImmutable.",
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                        }
                    },
                    {
                        "name": "updatedBeforeDateTime",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "title": "Convert updatedBefore string to DateTimeImmutable.",
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Converts 1-indexed page number to 0-indexed database offset.\nFormula: (page - 1) * limit",
                        "required": true,
                        "schema": {
                            "title": "Calculate SQL OFFSET from page number.",
                            "description": "Converts 1-indexed page number to 0-indexed database offset.\nFormula: (page - 1) * limit",
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful operation",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "id": {
                                                        "type": "integer",
                                                        "example": 1
                                                    },
                                                    "stringValue": {
                                                        "type": "string",
                                                        "example": "test value"
                                                    },
                                                    "intValue": {
                                                        "type": "integer",
                                                        "example": 123
                                                    },
                                                    "boolValue": {
                                                        "type": "boolean",
                                                        "example": true
                                                    },
                                                    "floatValue": {
                                                        "type": "number",
                                                        "format": "float",
                                                        "example": 10.5
                                                    },
                                                    "dateTimeValue": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "createdAt": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "updatedAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        },
                                        "total": {
                                            "type": "integer",
                                            "example": 100
                                        },
                                        "page": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "limit": {
                                            "type": "integer",
                                            "example": 20
                                        },
                                        "pages": {
                                            "type": "integer",
                                            "example": 5
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Sandbox"
                ],
                "summary": "Create a new Sandbox entity",
                "description": "Creates a new Sandbox entity with the provided value.",
                "operationId": "post_api_sandbox_create",
                "requestBody": {
                    "description": "Sandbox data",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "stringValue": {
                                        "type": "string",
                                        "example": "new value"
                                    },
                                    "intValue": {
                                        "type": "integer",
                                        "example": 123
                                    },
                                    "boolValue": {
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "floatValue": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 10.5
                                    },
                                    "dateTimeValue": {
                                        "type": "string",
                                        "format": "date-time",
                                        "example": "2023-10-27 10:00:00"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Sandbox entity created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "id": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "stringValue": {
                                            "type": "string",
                                            "example": "new value"
                                        },
                                        "intValue": {
                                            "type": "integer",
                                            "example": 123
                                        },
                                        "boolValue": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "floatValue": {
                                            "type": "number",
                                            "format": "float",
                                            "example": 10.5
                                        },
                                        "dateTimeValue": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "createdAt": {
                                            "type": "string",
                                            "format": "date-time"
                                        },
                                        "updatedAt": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/couriers": {
            "get": {
                "tags": [
                    "Couriers"
                ],
                "summary": "List couriers.",
                "operationId": "get_app_courier_index",
                "parameters": [
                    {
                        "name": "countries",
                        "in": "query",
                        "description": "Comma separated country codes (e.g. it,es). Mutually exclusive with `code`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "description": "Filter by specific courier code (e.g. BRT). Mutually exclusive with `countries`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "hasLabels",
                        "in": "query",
                        "description": "Filter by label generation support (true/false)",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns list of couriers",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/CourierResponseDto"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v2/couriers/{code}": {
            "get": {
                "tags": [
                    "Couriers"
                ],
                "summary": "Get courier details.",
                "operationId": "get_app_courier_show",
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "description": "Courier Code (e.g. BRT)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns single courier details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CourierResponseDto"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Courier not found"
                    }
                }
            }
        },
        "/v2/labels/confirm": {
            "post": {
                "tags": [
                    "Labels"
                ],
                "summary": "Confirm a batch of labels (CloseWorkDay) for the given courier.",
                "description": "Either `labelIds` or `labelCreationDate` must be provided, not both.\nReturns 201 + Location header pointing to the manifest endpoint.",
                "operationId": "post_api_labels_confirm",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ConfirmRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Transmission created \u2014 some or all shipments confirmed",
                        "headers": {
                            "Location": {
                                "description": "URL to download the manifest PDF",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ConfirmResponse"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "No new transmission created \u2014 all shipments already confirmed or non-existent (transmissionId is null)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ConfirmResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Unknown courier or no confirm client available"
                    },
                    "422": {
                        "description": "Validation error or courier not configured for channel"
                    }
                }
            }
        },
        "/v2/transmissions/{id}/manifest": {
            "get": {
                "tags": [
                    "Labels"
                ],
                "summary": "Generate and return the manifest PDF for a transmission.",
                "description": "The PDF is generated on-the-fly from the live shipment data.",
                "operationId": "get_api_transmissions_manifest",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Manifest PDF as base64-encoded string",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ManifestResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Transmission not found"
                    }
                }
            }
        },
        "/v2/labels": {
            "post": {
                "tags": [
                    "Labels"
                ],
                "summary": "Create a shipping label for an order.",
                "description": "Calls the carrier API and persists the resulting label (trackingNumbers + PDF/ZPL).\nIdempotent: if a label for the same reference already exists, returns it with isExisting=true.",
                "operationId": "post_api_labels_create",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LabelCreateRequestDto"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Label created successfully",
                        "headers": {
                            "Location": {
                                "description": "URL of the created label resource",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LabelCreateResponseDto"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Existing label returned (isExisting=true)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LabelCreateResponseDto"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Unknown courier or client not available"
                    },
                    "422": {
                        "description": "Validation error or courier not configured for channel"
                    }
                }
            }
        },
        "/v2/orders": {
            "get": {
                "tags": [
                    "Orders"
                ],
                "summary": "List orders for the authenticated channel.",
                "description": "If `source` and `reference` are both provided, performs an exact lookup by natural key.\nOtherwise returns a paginated list sorted by creation date descending.",
                "operationId": "get_api_orders_list",
                "parameters": [
                    {
                        "name": "source",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "shopify"
                        }
                    },
                    {
                        "name": "reference",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "ORD-2024-001"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 50,
                            "maximum": 100,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list of orders",
                        "headers": {
                            "X-Page": {
                                "description": "Current page",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-Limit": {
                                "description": "Items per page",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-Total-Count": {
                                "description": "Total number of orders",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/OrderResponse"
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Order not found (when filtering by source + reference)"
                    }
                }
            },
            "post": {
                "tags": [
                    "Orders"
                ],
                "summary": "Create a new order.",
                "description": "Returns 409 Conflict if an order with the same source + reference already exists.",
                "operationId": "post_api_orders_create",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderCreateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Order created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Order with same source + reference already exists"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v2/orders/{id}": {
            "get": {
                "tags": [
                    "Orders"
                ],
                "summary": "Get a single order by its internal Qapla' ID.",
                "operationId": "get_api_orders_show",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Order details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Order not found"
                    }
                }
            },
            "put": {
                "tags": [
                    "Orders"
                ],
                "summary": "Full replacement of an existing order (PUT semantics).",
                "description": "Requires reference and source in the body to confirm the natural key being replaced.",
                "operationId": "put_api_orders_update",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderPutRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Order updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Order not found"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Orders"
                ],
                "summary": "Soft-delete an order.",
                "operationId": "delete_api_orders_delete",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Order deleted"
                    },
                    "404": {
                        "description": "Order not found"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Orders"
                ],
                "summary": "Partial update of an existing order (PATCH semantics).",
                "description": "Only the fields present in the request body are modified.\nMissing fields are preserved as-is.",
                "operationId": "patch_api_orders_patch",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderPatchRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Order patched",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Order not found"
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/v2/shipments": {
            "get": {
                "tags": [
                    "Shipments"
                ],
                "summary": "Search shipments",
                "description": "Paginated listing of the authenticated channel. All filters combine with AND semantics. Use updatedAfter to poll only shipments whose tracking status changed.",
                "operationId": "get_api_shipments_search",
                "parameters": [
                    {
                        "name": "trackingNumber",
                        "in": "query",
                        "description": "Exact tracking number",
                        "required": false,
                        "schema": {
                            "description": "Exact tracking number",
                            "type": "string",
                            "example": "1Z0V5V416840696736",
                            "nullable": true,
                            "maxLength": 50
                        },
                        "example": "1Z0V5V416840696736"
                    },
                    {
                        "name": "orderReference",
                        "in": "query",
                        "description": "Exact order reference",
                        "required": false,
                        "schema": {
                            "description": "Exact order reference",
                            "type": "string",
                            "example": "ORD-2026-123",
                            "nullable": true,
                            "maxLength": 255
                        },
                        "example": "ORD-2026-123"
                    },
                    {
                        "name": "custom1",
                        "in": "query",
                        "description": "Exact custom attribute 1",
                        "required": false,
                        "schema": {
                            "description": "Exact custom attribute 1",
                            "type": "string",
                            "nullable": true,
                            "maxLength": 255
                        }
                    },
                    {
                        "name": "custom2",
                        "in": "query",
                        "description": "Exact custom attribute 2",
                        "required": false,
                        "schema": {
                            "description": "Exact custom attribute 2",
                            "type": "string",
                            "nullable": true,
                            "maxLength": 255
                        }
                    },
                    {
                        "name": "custom3",
                        "in": "query",
                        "description": "Exact custom attribute 3",
                        "required": false,
                        "schema": {
                            "description": "Exact custom attribute 3",
                            "type": "string",
                            "nullable": true,
                            "maxLength": 255
                        }
                    },
                    {
                        "name": "shipDateFrom",
                        "in": "query",
                        "description": "Ship date from, inclusive (YYYY-MM-DD)",
                        "required": false,
                        "schema": {
                            "description": "Ship date from, inclusive (YYYY-MM-DD)",
                            "type": "string",
                            "example": "2026-08-01",
                            "nullable": true
                        },
                        "example": "2026-08-01"
                    },
                    {
                        "name": "shipDateTo",
                        "in": "query",
                        "description": "Ship date to, inclusive (YYYY-MM-DD)",
                        "required": false,
                        "schema": {
                            "description": "Ship date to, inclusive (YYYY-MM-DD)",
                            "type": "string",
                            "example": "2026-08-04",
                            "nullable": true
                        },
                        "example": "2026-08-04"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "description": "Comma-separated list of tracking status values (see TrackingStatus)",
                        "required": false,
                        "schema": {
                            "description": "Comma-separated list of tracking status values (see TrackingStatus)",
                            "type": "string",
                            "pattern": "\\d+(,\\d+)*",
                            "example": "3,4,99",
                            "nullable": true
                        },
                        "example": "3,4,99"
                    },
                    {
                        "name": "updatedAfter",
                        "in": "query",
                        "description": "Only shipments whose tracking status changed at or after this moment (YYYY-MM-DD HH:MM:SS). Shipments never updated are excluded.",
                        "required": false,
                        "schema": {
                            "description": "Only shipments whose tracking status changed at or after this moment (YYYY-MM-DD HH:MM:SS). Shipments never updated are excluded.",
                            "type": "string",
                            "example": "2026-08-03 00:00:00",
                            "nullable": true
                        },
                        "example": "2026-08-03 00:00:00"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number (1-based)",
                        "required": false,
                        "schema": {
                            "description": "Page number (1-based)",
                            "type": "integer",
                            "example": 1,
                            "default": 1,
                            "minimum": 0,
                            "exclusiveMinimum": true
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Items per page (max 100)",
                        "required": false,
                        "schema": {
                            "description": "Items per page (max 100)",
                            "type": "integer",
                            "example": 20,
                            "default": 20,
                            "maximum": 100,
                            "minimum": 0,
                            "exclusiveMinimum": true
                        },
                        "example": 20
                    },
                    {
                        "name": "sortBy",
                        "in": "query",
                        "description": "Sort order",
                        "required": false,
                        "schema": {
                            "description": "Sort order",
                            "type": "string",
                            "example": "id_desc",
                            "default": "id_desc",
                            "enum": [
                                "id_desc",
                                "id_asc",
                                "shipDate_desc",
                                "shipDate_asc"
                            ]
                        },
                        "example": "id_desc"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One page of shipments",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/ShipmentSummary"
                                            }
                                        },
                                        "total": {
                                            "type": "integer",
                                            "example": 42
                                        },
                                        "page": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "limit": {
                                            "type": "integer",
                                            "example": 20
                                        },
                                        "pages": {
                                            "type": "integer",
                                            "example": 3
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Missing scope or channel context"
                    },
                    "422": {
                        "description": "Invalid query parameters (RFC 7807 with violations)"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Shipments"
                ],
                "summary": "Create shipments in bulk (max 100, synchronous)",
                "description": "Creates up to 100 shipments. Static payload violations reject the whole request with 422; business rejections (unknown courier, unsupported language, invalid origin, duplicates, box registry violations) are reported per item and the response is 207 Multi-Status. Duplicates are detected on (channel, courier, trackingNumber).",
                "operationId": "post_api_shipments_create",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ShipmentBulkCreateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "All shipments created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShipmentBulkCreateResponse"
                                }
                            }
                        }
                    },
                    "207": {
                        "description": "Some or all shipments rejected (see items[].errors)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShipmentBulkCreateResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Missing scope or channel context"
                    },
                    "422": {
                        "description": "Payload validation failed (RFC 7807 with violations)"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/shipments/{id}": {
            "get": {
                "tags": [
                    "Shipments"
                ],
                "summary": "Get shipment details",
                "operationId": "get_api_shipments_show",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Shipment details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShipmentDetail"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Missing scope or channel context"
                    },
                    "404": {
                        "description": "Shipment not found (or not owned by the authenticated channel)"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/shipments/import": {
            "post": {
                "tags": [
                    "Shipments"
                ],
                "summary": "Import shipments in bulk (max 5000, asynchronous)",
                "description": "Queues a background import job and returns 202. Poll GET /jobs/{jobId} for progress and the per-item result (successes compact, errors detailed). Items already imported are reported as DUPLICATE_SHIPMENT if the job is retried after a crash.",
                "operationId": "post_api_shipments_import",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ShipmentImportRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Import job accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShipmentImportAcceptedResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Missing scope or channel context"
                    },
                    "422": {
                        "description": "Payload validation failed (RFC 7807 with violations)"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/shipments/{id}/notifications": {
            "post": {
                "tags": [
                    "Shipments"
                ],
                "summary": "Send a transactional email to the recipient for a merchant-defined event",
                "description": "Fires the transactional email configured on the channel for the given `event` (a code you define, e.g. `order_preparing`), on a shipment Qapla' already knows. The template is the one saved on the channel for the \"API notification\" message status with the event code as origin; if the event has no template of its own, the channel's default template for that status is used. Language defaults to the shipment's. Optional `variables.custom1..3` override the shipment's custom fields **in this message only** (`[*CUSTOM1*]`\u2026). Delivery is asynchronous through Qapla's email engine: a 202 means the message was accepted, the proof of sending is the email log of the shipment. The same shipment + event pair is accepted once every 24 hours.",
                "operationId": "post_api_shipments_notification",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ShipmentNotificationRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Notification accepted and handed over for delivery",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShipmentNotificationResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request - missing body or malformed JSON"
                    },
                    "401": {
                        "description": "Unauthorized - missing or invalid token"
                    },
                    "403": {
                        "description": "Forbidden - insufficient scope or channel context missing"
                    },
                    "404": {
                        "description": "Shipment not found (or not owned by the authenticated channel)"
                    },
                    "409": {
                        "description": "Conflict - the channel has no active email integration (messages cannot be delivered), or the same shipment + event was already accepted in the last 24 hours (the previous notificationId is in the problem detail)"
                    },
                    "422": {
                        "description": "Validation error (event code, variables, language), shipment without a recipient email, or no template configured on the channel for this event/language"
                    },
                    "429": {
                        "description": "Too Many Requests - rate limit exceeded"
                    },
                    "503": {
                        "description": "Delivery engine unavailable - the message was not handed over, retry later"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/shipments/{id}/stock-release": {
            "post": {
                "tags": [
                    "Shipments"
                ],
                "summary": "Request a stock release for a shipment held in depot",
                "description": "Registers and transmits a stock-release request to the courier (redeliver, redeliver_new_address, return_to_sender).",
                "operationId": "post_api_shipments_stock_release",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "\\d+"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/StockReleaseRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Request accepted and transmitted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/StockReleaseResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden - channel context missing"
                    },
                    "404": {
                        "description": "Shipment not found (or not owned by the authenticated channel)"
                    },
                    "409": {
                        "description": "Shipment is not held in depot (no giacenza to release)"
                    },
                    "422": {
                        "description": "Validation error or carrier rejected the request"
                    }
                },
                "security": [
                    {
                        "Bearer": []
                    }
                ]
            }
        },
        "/v2/health": {
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "Health Check",
                "description": "Deep health check that verifies Database and Redis connectivity",
                "operationId": "get_prefixed_health_check",
                "responses": {
                    "200": {
                        "description": "All systems operational"
                    },
                    "503": {
                        "description": "Service unavailable - one or more checks failed"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "ConfirmRequest": {
                "description": "Payload for closing the carrier working day and confirming a batch of labels.",
                "required": [
                    "courier"
                ],
                "properties": {
                    "courier": {
                        "description": "Carrier code (e.g. GLS_ITA, GENERIC)",
                        "type": "string",
                        "example": "GLS_ITA",
                        "default": ""
                    },
                    "labelIds": {
                        "description": "List of internal label IDs to confirm. Mutually exclusive with labelCreationDate.",
                        "type": "array",
                        "items": {
                            "type": "integer"
                        },
                        "example": [
                            101,
                            102,
                            103
                        ],
                        "nullable": true,
                        "minItems": 1
                    },
                    "labelCreationDate": {
                        "description": "Confirm all labels created on this date (YYYY-MM-DD). Mutually exclusive with labelIds.",
                        "type": "string",
                        "example": "2025-03-15",
                        "nullable": true
                    },
                    "pickupDate": {
                        "description": "Pickup date requested to carrier (YYYY-MM-DD). Carrier-specific.",
                        "type": "string",
                        "example": "2025-03-16",
                        "nullable": true
                    },
                    "pickupTime": {
                        "description": "Pickup time requested to carrier (HH:MM). Requires pickupDate. Carrier-specific.",
                        "type": "string",
                        "example": "09:30",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ConfirmResponse": {
                "properties": {
                    "transmissionId": {
                        "description": "Transmission record ID. Null when all shipments were already confirmed or non-existent.",
                        "type": "integer",
                        "example": 42,
                        "nullable": true
                    },
                    "transmissionNumber": {
                        "description": "Human-readable transmission number (e.g. 00001-25). Null when no transmission was created.",
                        "type": "string",
                        "example": "00001-25",
                        "nullable": true
                    },
                    "successCount": {
                        "description": "Number of shipments successfully confirmed",
                        "type": "integer",
                        "example": 10,
                        "default": 0
                    },
                    "alreadyConfirmedIds": {
                        "description": "Label IDs that were already confirmed before this call (idempotency info)",
                        "type": "array",
                        "items": {
                            "type": "integer"
                        },
                        "default": []
                    },
                    "nonExistentIds": {
                        "description": "Label IDs not found or not belonging to this channel/courier",
                        "type": "array",
                        "items": {
                            "type": "integer"
                        },
                        "default": []
                    },
                    "errors": {
                        "description": "Per-shipment errors returned by the carrier",
                        "type": "array",
                        "items": {
                            "properties": {
                                "shipmentId": {
                                    "type": "integer"
                                },
                                "message": {
                                    "type": "string"
                                }
                            }
                        },
                        "default": []
                    }
                },
                "type": "object"
            },
            "ManifestResponse": {
                "properties": {
                    "transmissionId": {
                        "description": "Transmission record ID",
                        "type": "integer",
                        "example": 42,
                        "default": 0
                    },
                    "transmissionNumber": {
                        "description": "Human-readable transmission number",
                        "type": "string",
                        "example": "00001-25",
                        "default": ""
                    },
                    "courierCode": {
                        "description": "Courier code",
                        "type": "string",
                        "example": "GLS_ITA",
                        "default": ""
                    },
                    "fileName": {
                        "description": "Suggested filename for the PDF",
                        "type": "string",
                        "example": "GLS_ITA-Manifest_00001-25.pdf",
                        "default": ""
                    },
                    "manifest": {
                        "description": "Base64-encoded PDF content of the manifest",
                        "type": "string",
                        "default": ""
                    }
                },
                "type": "object"
            },
            "OrderConsigneeDto": {
                "description": "Recipient address and contact details",
                "properties": {
                    "name": {
                        "description": "Consignee full name",
                        "type": "string",
                        "example": "Barbara Gordon",
                        "nullable": true,
                        "default": null
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via Manin, 8",
                        "nullable": true,
                        "default": null
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Vigonza",
                        "nullable": true,
                        "default": null
                    },
                    "state": {
                        "description": "Province/State code",
                        "type": "string",
                        "example": "PD",
                        "nullable": true,
                        "default": null
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "35010",
                        "nullable": true,
                        "default": null
                    },
                    "country": {
                        "description": "Country ISO 3166-1 alpha-2 code",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "default": null,
                        "maxLength": 2
                    },
                    "email": {
                        "description": "Email address",
                        "type": "string",
                        "example": "batgirl@qapla.it",
                        "nullable": true,
                        "default": null
                    },
                    "phone": {
                        "description": "Phone number",
                        "type": "string",
                        "example": "3473425220",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderMonetaryDto": {
                "description": "Monetary values and payment details",
                "required": [
                    "isCod"
                ],
                "properties": {
                    "paymentMethod": {
                        "description": "Payment method label",
                        "type": "string",
                        "example": "pp_hosted",
                        "nullable": true,
                        "default": null
                    },
                    "isCod": {
                        "description": "Is Cash on Delivery",
                        "type": "boolean",
                        "example": false
                    },
                    "codPaymentOption": {
                        "description": "COD payment option",
                        "type": "string",
                        "example": null,
                        "nullable": true,
                        "default": null
                    },
                    "value": {
                        "description": "Order value amount",
                        "type": "string",
                        "example": "109.25",
                        "nullable": true,
                        "default": null
                    },
                    "shippingCost": {
                        "description": "Shipping cost paid by customer",
                        "type": "number",
                        "format": "float",
                        "example": 9.35,
                        "nullable": true,
                        "default": null
                    },
                    "currency": {
                        "description": "Currency ISO 4217 code",
                        "type": "string",
                        "example": "EUR",
                        "default": "EUR"
                    },
                    "shippingInsurance": {
                        "description": "Shipping insurance amount",
                        "type": "string",
                        "example": "300.99",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderPlanningDto": {
                "description": "Delivery planning and scheduling details",
                "properties": {
                    "deliveryOptions": {
                        "description": "Delivery options (e.g. A,P)",
                        "type": "string",
                        "example": "A,P",
                        "nullable": true,
                        "default": null
                    },
                    "requestedDeliveryDate": {
                        "description": "Requested delivery date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2020-09-01",
                        "nullable": true,
                        "default": null
                    },
                    "latestShipDate": {
                        "description": "Latest ship date. Either a plain date (YYYY-MM-DD, midnight Europe/Rome) or an ISO 8601 date-time with offset (YYYY-MM-DDThh:mm:ss\u00b1hh:mm or Z), stored as Europe/Rome wall-clock. Always returned as YYYY-MM-DD.",
                        "type": "string",
                        "example": "2026-04-03T15:00:00+02:00",
                        "nullable": true,
                        "default": null
                    },
                    "latestDeliveryDate": {
                        "description": "Latest delivery date. Either a plain date (YYYY-MM-DD, midnight Europe/Rome) or an ISO 8601 date-time with offset (YYYY-MM-DDThh:mm:ss\u00b1hh:mm or Z), stored as Europe/Rome wall-clock. Always returned as YYYY-MM-DD.",
                        "type": "string",
                        "example": "2026-04-05T15:00:00+02:00",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderCustomAttributesDto": {
                "description": "Custom merchant-defined attributes",
                "properties": {
                    "custom1": {
                        "description": "Custom attribute 1",
                        "type": "string",
                        "example": "custom value 1",
                        "nullable": true,
                        "default": null
                    },
                    "custom2": {
                        "description": "Custom attribute 2",
                        "type": "string",
                        "example": "custom value 2",
                        "nullable": true,
                        "default": null
                    },
                    "custom3": {
                        "description": "Custom attribute 3",
                        "type": "string",
                        "example": "custom value 3",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderParcelDto": {
                "description": "Physical parcel dimensions and weight",
                "properties": {
                    "weight": {
                        "description": "Parcel weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 1.5,
                        "nullable": true,
                        "default": null,
                        "minimum": 0
                    },
                    "length": {
                        "description": "Parcel length in cm",
                        "type": "number",
                        "format": "float",
                        "example": 12,
                        "nullable": true,
                        "default": null,
                        "minimum": 0
                    },
                    "width": {
                        "description": "Parcel width in cm",
                        "type": "number",
                        "format": "float",
                        "example": 20,
                        "nullable": true,
                        "default": null,
                        "minimum": 0
                    },
                    "height": {
                        "description": "Parcel height in cm",
                        "type": "number",
                        "format": "float",
                        "example": 7,
                        "nullable": true,
                        "default": null,
                        "minimum": 0
                    },
                    "boxCode": {
                        "description": "Box code used for this parcel",
                        "type": "string",
                        "example": "BOX-A",
                        "nullable": true,
                        "default": null
                    },
                    "content": {
                        "description": "Parcel content description",
                        "type": "string",
                        "example": "Fragile items",
                        "nullable": true,
                        "default": null
                    },
                    "originCountry": {
                        "description": "Origin country for customs (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderItemDto": {
                "description": "A single order line item",
                "required": [
                    "isReturnable"
                ],
                "properties": {
                    "sku": {
                        "description": "Product SKU",
                        "type": "string",
                        "example": "BAR-301",
                        "nullable": true,
                        "default": null
                    },
                    "name": {
                        "description": "Product name/description",
                        "type": "string",
                        "example": "Barrette di Crusca d'Avena",
                        "nullable": true,
                        "default": null
                    },
                    "quantity": {
                        "description": "Quantity ordered",
                        "type": "integer",
                        "example": 1,
                        "nullable": true,
                        "default": null
                    },
                    "weight": {
                        "description": "Unit weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 1.5,
                        "nullable": true,
                        "default": null
                    },
                    "url": {
                        "description": "Product URL",
                        "type": "string",
                        "example": "https://www.example.it/product",
                        "nullable": true,
                        "default": null
                    },
                    "imageUrl": {
                        "description": "Product image URL",
                        "type": "string",
                        "example": "https://www.example.it/img/product.jpg",
                        "nullable": true,
                        "default": null
                    },
                    "price": {
                        "description": "Unit price",
                        "type": "number",
                        "format": "float",
                        "example": 6.35,
                        "nullable": true,
                        "default": null
                    },
                    "total": {
                        "description": "Total row price (qty * price)",
                        "type": "number",
                        "format": "float",
                        "example": 6.35,
                        "nullable": true,
                        "default": null
                    },
                    "isReturnable": {
                        "description": "Is item returnable",
                        "type": "boolean",
                        "example": true
                    },
                    "notes": {
                        "description": "Item notes",
                        "type": "string",
                        "example": "Product note",
                        "nullable": true,
                        "default": null
                    },
                    "customsCode": {
                        "description": "Customs HS code",
                        "type": "string",
                        "example": "6204.62.00",
                        "nullable": true,
                        "default": null
                    },
                    "originCountry": {
                        "description": "Origin country ISO 3166-1 alpha-2",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "default": null
                    },
                    "netWeight": {
                        "description": "Net weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 1.4,
                        "nullable": true,
                        "default": null
                    },
                    "unitOfMeasurement": {
                        "description": "Unit of measurement",
                        "type": "string",
                        "example": "kg",
                        "nullable": true,
                        "default": null
                    },
                    "parcelId": {
                        "description": "ID of the parcel containing this item",
                        "type": "string",
                        "example": "parcel-1",
                        "nullable": true,
                        "default": null
                    },
                    "transparencyCodes": {
                        "description": "Array of Amazon transparency codes",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "ABC123XXX"
                        },
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderResponse": {
                "description": "Full Order resource payload",
                "required": [
                    "id",
                    "channelId",
                    "reference",
                    "source"
                ],
                "properties": {
                    "id": {
                        "description": "Internal Qapla' ID",
                        "type": "integer",
                        "example": 123456
                    },
                    "channelId": {
                        "description": "Channel ID",
                        "type": "integer",
                        "example": 987
                    },
                    "reference": {
                        "description": "Order reference (human readable)",
                        "type": "string",
                        "example": "BAT-234241299"
                    },
                    "orderId": {
                        "description": "Platform numeric/internal Order ID",
                        "type": "string",
                        "example": "234241222",
                        "nullable": true
                    },
                    "source": {
                        "description": "Origin platform or source",
                        "type": "string",
                        "example": "magento2"
                    },
                    "courierId": {
                        "description": "Courier ID (0 = not assigned)",
                        "type": "integer",
                        "example": 0,
                        "default": 0
                    },
                    "courierService": {
                        "description": "Courier service/contract code",
                        "type": "string",
                        "example": "P46",
                        "nullable": true
                    },
                    "senderId": {
                        "description": "Sender ID from the channel dictionary (null = not assigned)",
                        "type": "integer",
                        "example": 12,
                        "nullable": true
                    },
                    "status": {
                        "description": "Current order status",
                        "type": "string",
                        "example": "Processato",
                        "nullable": true
                    },
                    "createdAt": {
                        "description": "Order creation date (ISO 8601)",
                        "type": "string",
                        "example": "2018-04-01T22:38:18+01:00",
                        "nullable": true
                    },
                    "updatedAt": {
                        "description": "Order last update date (ISO 8601)",
                        "type": "string",
                        "example": "2018-04-01T22:40:41+01:00",
                        "nullable": true
                    },
                    "isReturnable": {
                        "description": "Is the order returnable",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "notes": {
                        "description": "General order notes",
                        "type": "string",
                        "example": "Consegnare solo se in costume",
                        "nullable": true
                    },
                    "content": {
                        "description": "Content description",
                        "type": "string",
                        "example": "The goods",
                        "nullable": true
                    },
                    "tag": {
                        "description": "Tag string",
                        "type": "string",
                        "example": "blue",
                        "nullable": true
                    },
                    "pickupDate": {
                        "description": "Pickup date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2020-08-30",
                        "nullable": true
                    },
                    "pickupTime": {
                        "description": "Pickup time (HH:MM)",
                        "type": "string",
                        "example": "14:00",
                        "nullable": true
                    },
                    "pickupPoint": {
                        "description": "Pickup Point ID",
                        "type": "string",
                        "example": "0201",
                        "nullable": true
                    },
                    "consignee": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderConsigneeDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Consignee details"
                    },
                    "monetary": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderMonetaryDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Monetary values and payments"
                    },
                    "planning": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPlanningDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Planning and delivery dates"
                    },
                    "customAttributes": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderCustomAttributesDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Custom merchant attributes"
                    },
                    "totalWeight": {
                        "description": "Total weight of all parcels in kg",
                        "type": "number",
                        "format": "float",
                        "example": 1.5,
                        "default": 0
                    },
                    "parcelsCount": {
                        "description": "Total count of physical parcels",
                        "type": "integer",
                        "example": 1,
                        "default": 0
                    },
                    "firstParcelLength": {
                        "description": "First parcel length in cm",
                        "type": "number",
                        "format": "float",
                        "example": 12,
                        "nullable": true
                    },
                    "firstParcelWidth": {
                        "description": "First parcel width in cm",
                        "type": "number",
                        "format": "float",
                        "example": 20,
                        "nullable": true
                    },
                    "firstParcelHeight": {
                        "description": "First parcel height in cm",
                        "type": "number",
                        "format": "float",
                        "example": 7,
                        "nullable": true
                    },
                    "parcels": {
                        "description": "Physical parcels (reconstructed from stored aggregate data; weight is evenly distributed for multi-parcel orders; dimensions are available for the first parcel only)",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderParcelDto"
                        },
                        "default": []
                    },
                    "items": {
                        "description": "Order line items",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItemDto"
                        },
                        "default": []
                    }
                },
                "type": "object"
            },
            "LabelConsigneeDto": {
                "description": "Recipient address for the shipment",
                "required": [
                    "name",
                    "street",
                    "city",
                    "state",
                    "postcode",
                    "country"
                ],
                "properties": {
                    "name": {
                        "description": "Recipient full name",
                        "type": "string",
                        "example": "Mario Rossi",
                        "maxLength": 100
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via Roma 1",
                        "maxLength": 255
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Milano",
                        "maxLength": 100
                    },
                    "state": {
                        "description": "Province/State code (2 chars for IT)",
                        "type": "string",
                        "example": "MI",
                        "maxLength": 10
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "20100",
                        "maxLength": 20
                    },
                    "country": {
                        "description": "Country ISO 3166-1 alpha-2",
                        "type": "string",
                        "example": "IT",
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "email": {
                        "description": "Recipient email",
                        "type": "string",
                        "example": "mario.rossi@example.com",
                        "nullable": true
                    },
                    "phone": {
                        "description": "Recipient phone number",
                        "type": "string",
                        "example": "3331234567",
                        "nullable": true,
                        "maxLength": 50
                    }
                },
                "type": "object"
            },
            "LabelMonetaryDto": {
                "description": "Monetary and payment details for the shipment",
                "properties": {
                    "isCod": {
                        "description": "Whether the shipment is cash-on-delivery (COD)",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "amount": {
                        "description": "COD amount (required when isCod=true)",
                        "type": "number",
                        "format": "float",
                        "example": 49.99,
                        "nullable": true,
                        "minimum": 0
                    },
                    "codPaymentOption": {
                        "description": "COD payment method code (carrier-specific)",
                        "type": "string",
                        "example": "CONT",
                        "nullable": true,
                        "maxLength": 20
                    },
                    "shippingInsurance": {
                        "description": "Additional insurance value",
                        "type": "number",
                        "format": "float",
                        "example": 150,
                        "nullable": true,
                        "minimum": 0
                    },
                    "currency": {
                        "description": "Currency ISO 4217",
                        "type": "string",
                        "example": "EUR",
                        "default": "EUR",
                        "maxLength": 3,
                        "minLength": 3
                    }
                },
                "type": "object"
            },
            "LabelPlanningDto": {
                "description": "Delivery planning options for the shipment",
                "properties": {
                    "deliveryOptions": {
                        "description": "Delivery option codes (comma-separated, carrier-specific)",
                        "type": "string",
                        "example": "31,39",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "requestedDeliveryDate": {
                        "description": "Requested delivery date (Y-m-d)",
                        "type": "string",
                        "example": "2024-12-31",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "LabelCustomAttributesDto": {
                "description": "Custom fields for the shipment",
                "properties": {
                    "custom1": {
                        "description": "Custom field 1",
                        "type": "string",
                        "example": null,
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom2": {
                        "description": "Custom field 2",
                        "type": "string",
                        "example": null,
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom3": {
                        "description": "Custom field 3",
                        "type": "string",
                        "example": null,
                        "nullable": true,
                        "maxLength": 255
                    }
                },
                "type": "object"
            },
            "LabelParcelDto": {
                "description": "Dati di un singolo collo per la creazione dell'etichetta",
                "properties": {
                    "weight": {
                        "description": "Peso del collo in kg",
                        "type": "number",
                        "format": "float",
                        "example": 1.5,
                        "default": 1,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "length": {
                        "description": "Lunghezza in cm",
                        "type": "number",
                        "format": "float",
                        "example": 30,
                        "nullable": true,
                        "minimum": 0
                    },
                    "width": {
                        "description": "Larghezza in cm",
                        "type": "number",
                        "format": "float",
                        "example": 20,
                        "nullable": true,
                        "minimum": 0
                    },
                    "height": {
                        "description": "Altezza in cm",
                        "type": "number",
                        "format": "float",
                        "example": 10,
                        "nullable": true,
                        "minimum": 0
                    },
                    "boxCode": {
                        "description": "Codice scatola predefinita (da aziendeAnagraficaScatole)",
                        "type": "string",
                        "example": "BOX-S",
                        "nullable": true,
                        "maxLength": 50
                    }
                },
                "type": "object"
            },
            "LabelRowDto": {
                "description": "Riga ordine (articolo) associata alla spedizione",
                "required": [
                    "sku",
                    "name",
                    "qty"
                ],
                "properties": {
                    "sku": {
                        "description": "SKU articolo",
                        "type": "string",
                        "example": "ABC-123",
                        "maxLength": 100
                    },
                    "name": {
                        "description": "Descrizione articolo",
                        "type": "string",
                        "example": "T-Shirt Rossa M",
                        "maxLength": 255
                    },
                    "qty": {
                        "description": "Quantit\u00e0",
                        "type": "integer",
                        "example": 2,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "price": {
                        "description": "Prezzo unitario",
                        "type": "number",
                        "format": "float",
                        "example": 19.99,
                        "nullable": true,
                        "minimum": 0
                    },
                    "total": {
                        "description": "Totale riga",
                        "type": "number",
                        "format": "float",
                        "example": 39.98,
                        "nullable": true,
                        "minimum": 0
                    },
                    "weight": {
                        "description": "Peso articolo in kg",
                        "type": "number",
                        "format": "float",
                        "example": 0.3,
                        "nullable": true,
                        "minimum": 0
                    },
                    "netWeight": {
                        "description": "Peso netto in kg (per dogana)",
                        "type": "number",
                        "format": "float",
                        "example": 0.25,
                        "nullable": true,
                        "minimum": 0
                    },
                    "customsCode": {
                        "description": "Codice doganale (HS Code)",
                        "type": "string",
                        "example": "61091000",
                        "nullable": true,
                        "maxLength": 20
                    },
                    "originCountry": {
                        "description": "Paese di origine (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "CN",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "unitOfMeasurement": {
                        "description": "Unit\u00e0 di misura",
                        "type": "string",
                        "example": "PCE",
                        "nullable": true,
                        "maxLength": 10
                    },
                    "parcelId": {
                        "description": "ID collo a cui appartiene l'articolo",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "LabelSenderDto": {
                "description": "Custom sender address for the shipment",
                "properties": {
                    "code": {
                        "description": "Sender code (key in channel config)",
                        "type": "string",
                        "example": "WAREHOUSE_A",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "businessName": {
                        "description": "Business name",
                        "type": "string",
                        "example": "Acme Srl",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via Industria 10",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Bologna",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "state": {
                        "description": "Province/State code (2 chars)",
                        "type": "string",
                        "example": "BO",
                        "nullable": true,
                        "maxLength": 10
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "40100",
                        "nullable": true,
                        "maxLength": 20
                    },
                    "country": {
                        "description": "Country ISO 3166-1 alpha-2",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "email": {
                        "description": "Sender email",
                        "type": "string",
                        "example": "spedizioni@acme.it",
                        "nullable": true
                    },
                    "phone": {
                        "description": "Sender phone number",
                        "type": "string",
                        "example": "0512345678",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "referent": {
                        "description": "Referent person name",
                        "type": "string",
                        "example": "Mario Rossi",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "isDefault": {
                        "description": "If true, set as default sender for the channel",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    }
                },
                "type": "object"
            },
            "LabelCreateRequestDto": {
                "description": "Request payload for creating a carrier shipping label",
                "required": [
                    "courier",
                    "reference",
                    "source",
                    "consignee",
                    "monetary",
                    "planning",
                    "customAttributes",
                    "sender"
                ],
                "properties": {
                    "courier": {
                        "description": "Qapla' carrier code (e.g. GLS_ITA, BRT, DHL). Use GENERIC for local testing.",
                        "type": "string",
                        "example": "GLS_ITA",
                        "maxLength": 50
                    },
                    "courierService": {
                        "description": "Carrier service/contract code (e.g. GLS contract code)",
                        "type": "string",
                        "example": "12345",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "reference": {
                        "description": "Unique order reference from the client",
                        "type": "string",
                        "example": "ORD-2024-001",
                        "maxLength": 50
                    },
                    "source": {
                        "description": "Source/origin platform (magento, shopify, amazon, api, etc.)",
                        "type": "string",
                        "example": "shopify",
                        "maxLength": 50
                    },
                    "consignee": {
                        "$ref": "#/components/schemas/LabelConsigneeDto"
                    },
                    "weight": {
                        "description": "Total weight in kg (used as single parcel fallback when parcels[] is not set)",
                        "type": "number",
                        "format": "float",
                        "example": 2.5,
                        "nullable": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "content": {
                        "description": "Shipment content description (customs)",
                        "type": "string",
                        "example": "Clothing",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "pickupDate": {
                        "description": "Requested pickup date (Y-m-d)",
                        "type": "string",
                        "example": "2024-12-28",
                        "nullable": true
                    },
                    "monetary": {
                        "$ref": "#/components/schemas/LabelMonetaryDto"
                    },
                    "planning": {
                        "$ref": "#/components/schemas/LabelPlanningDto"
                    },
                    "customAttributes": {
                        "$ref": "#/components/schemas/LabelCustomAttributesDto"
                    },
                    "parcels": {
                        "description": "Parcel list with weight/dimensions. If omitted, a single parcel is derived from the top-level weight field.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/LabelParcelDto"
                        },
                        "nullable": true
                    },
                    "rows": {
                        "description": "Order line items",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/LabelRowDto"
                        },
                        "nullable": true
                    },
                    "sender": {
                        "$ref": "#/components/schemas/LabelSenderDto"
                    },
                    "sandbox": {
                        "description": "If true, runs in sandbox mode (no real carrier call)",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    }
                },
                "type": "object"
            },
            "LabelCreateResponseDto": {
                "description": "Response to a carrier label creation request",
                "required": [
                    "id",
                    "trackingNumbers",
                    "courier",
                    "reference",
                    "labels",
                    "labelFormat"
                ],
                "properties": {
                    "id": {
                        "description": "Label record ID (aziendeCanaliSpedizioni.id)",
                        "type": "integer",
                        "example": 98765
                    },
                    "trackingNumbers": {
                        "description": "One or more tracking numbers returned by the carrier. First entry is primary. Some carriers (e.g. GLS international) return multiple entries for different network legs.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "number": {
                                    "type": "string",
                                    "example": "GG123456789"
                                },
                                "description": {
                                    "type": "string",
                                    "example": "GLS_ITA"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "courier": {
                        "description": "Carrier code",
                        "type": "string",
                        "example": "GLS_ITA"
                    },
                    "reference": {
                        "description": "Order reference",
                        "type": "string",
                        "example": "ORD-2024-001"
                    },
                    "labels": {
                        "description": "Labels in base64 (PDF) or raw ZPL string. One entry per parcel.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "labelFormat": {
                        "description": "Label format",
                        "type": "string",
                        "example": "PDF",
                        "enum": [
                            "PDF",
                            "ZPL"
                        ]
                    },
                    "extShipmentId": {
                        "description": "External shipment ID (carrier-specific), present only if available",
                        "type": "string",
                        "example": null,
                        "nullable": true
                    },
                    "isExisting": {
                        "description": "True if the order was already shipped and an existing label is being returned",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    }
                },
                "type": "object"
            },
            "StockReleaseRequest": {
                "description": "Ask the courier to act on a shipment held in depot (giacenza).",
                "required": [
                    "action",
                    "address"
                ],
                "properties": {
                    "action": {
                        "description": "Canonical action",
                        "type": "string",
                        "example": "redeliver",
                        "default": "",
                        "enum": [
                            "redeliver",
                            "redeliver_new_address",
                            "return_to_sender"
                        ]
                    },
                    "notes": {
                        "description": "Free-text note for the courier (optional)",
                        "type": "string",
                        "example": "Ring the bell twice",
                        "nullable": true
                    },
                    "redeliveryDate": {
                        "description": "Requested redelivery date, ISO format (YYYY-MM-DD). Only allowed for redeliver and redeliver_new_address. GLS Italy requires a redelivery date: when omitted it defaults to the next Italian working day. Ignored by couriers that do not support it.",
                        "type": "string",
                        "example": "2026-07-15",
                        "nullable": true
                    },
                    "address": {
                        "$ref": "#/components/schemas/StockReleaseAddress"
                    }
                },
                "type": "object"
            },
            "StockReleaseResponse": {
                "description": "Stock-release acceptance result.",
                "required": [
                    "courierOutcome",
                    "releaseId"
                ],
                "properties": {
                    "status": {
                        "description": "Always \"sent\" \u2014 the request was accepted and transmitted",
                        "type": "string",
                        "example": "sent",
                        "default": "sent"
                    },
                    "courierOutcome": {
                        "description": "Courier outcome",
                        "type": "string",
                        "example": "ok",
                        "enum": [
                            "ok",
                            "error",
                            "pending"
                        ]
                    },
                    "message": {
                        "description": "Courier outcome message, when available",
                        "type": "string",
                        "example": "OK",
                        "nullable": true
                    },
                    "releaseId": {
                        "description": "Internal id of the stored release request",
                        "type": "integer",
                        "example": 12345
                    }
                },
                "type": "object"
            },
            "StockReleaseAddress": {
                "description": "New delivery address (required for redeliver_new_address).",
                "properties": {
                    "name": {
                        "description": "Recipient name",
                        "type": "string",
                        "example": "Mario Rossi",
                        "default": ""
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via Roma 1",
                        "default": ""
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Milano",
                        "default": ""
                    },
                    "zip": {
                        "description": "ZIP / postal code",
                        "type": "string",
                        "example": "20100",
                        "default": ""
                    },
                    "province": {
                        "description": "Province code",
                        "type": "string",
                        "example": "MI",
                        "default": ""
                    },
                    "phone": {
                        "description": "Contact phone (optional)",
                        "type": "string",
                        "example": "+39061234567",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ShipmentNotificationRequest": {
                "description": "Send the recipient a transactional email for an event only the merchant's system knows about.",
                "required": [
                    "event"
                ],
                "properties": {
                    "event": {
                        "description": "Event code, lowercase letters/digits/_/- (2-25 chars). It selects the template configured for this event on the channel; `default` and `amazon` are reserved.",
                        "type": "string",
                        "pattern": "[a-z0-9][a-z0-9_-]{1,24}",
                        "example": "order_preparing",
                        "default": ""
                    },
                    "variables": {
                        "title": "Whatever the JSON carried: the callback below is the type check (the mapper does not\nenforce the value types of an untyped object), and the service reads only the three keys.",
                        "description": "Optional per-message values for the [*CUSTOM1*]..[*CUSTOM3*] template variables (max 255 chars each). Defaults to the shipment's own custom fields; never stored.",
                        "type": "object",
                        "example": {
                            "custom1": "PR-2026-0917",
                            "custom2": "Giulia"
                        },
                        "nullable": true
                    },
                    "language": {
                        "description": "Language code of the template to use (it, en, de, fr, es, pt, zh, ru, ja, cs, ro, hu, ar, sk, pl, ko, nl). Defaults to the shipment language.",
                        "type": "string",
                        "example": "it",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    }
                },
                "type": "object"
            },
            "ShipmentNotificationResponse": {
                "description": "Notification accepted for delivery.",
                "required": [
                    "notificationId",
                    "shipmentId",
                    "event"
                ],
                "properties": {
                    "notificationId": {
                        "description": "Notification id (uuid) \u2014 also the Pub/Sub envelope id",
                        "type": "string",
                        "example": "8c1e2f40-\u2026"
                    },
                    "shipmentId": {
                        "description": "Shipment id the notification refers to",
                        "type": "integer",
                        "example": 149112040
                    },
                    "event": {
                        "description": "Event code as sent",
                        "type": "string",
                        "example": "order_preparing"
                    },
                    "status": {
                        "description": "Always \"accepted\": delivery is asynchronous",
                        "type": "string",
                        "example": "accepted",
                        "default": "accepted"
                    }
                },
                "type": "object"
            },
            "TrackingStatusEnum": {
                "type": "integer",
                "enum": [
                    0,
                    1,
                    2,
                    3,
                    4,
                    5,
                    6,
                    8,
                    10,
                    20,
                    50,
                    95,
                    99
                ]
            },
            "ShipmentSummary": {
                "description": "Shipment (list projection)",
                "required": [
                    "consignee",
                    "monetary",
                    "customAttributes"
                ],
                "properties": {
                    "id": {
                        "description": "Shipment id",
                        "type": "integer",
                        "example": 123456,
                        "default": 0
                    },
                    "trackingNumber": {
                        "description": "Courier tracking number",
                        "type": "string",
                        "example": "1Z0V5V416840696736",
                        "default": ""
                    },
                    "trackingUrl": {
                        "description": "Public tracking page URL. Null when the tracking token is not available.",
                        "type": "string",
                        "example": "https://tracking.qapla.it/27e7cefc0e1e4e5e9c8b7a6d5f4e3d2c",
                        "nullable": true
                    },
                    "courier": {
                        "description": "Canonical courier code",
                        "type": "string",
                        "example": "UPS",
                        "default": ""
                    },
                    "courierName": {
                        "description": "Canonical courier name",
                        "type": "string",
                        "example": "UPS",
                        "nullable": true
                    },
                    "status": {
                        "$ref": "#/components/schemas/TrackingStatusEnum"
                    },
                    "statusDescription": {
                        "description": "Tracking status description, localized in the shipment language",
                        "type": "string",
                        "example": "In transit",
                        "nullable": true
                    },
                    "statusDetail": {
                        "description": "Tracking status detail id (0 = none)",
                        "type": "integer",
                        "example": 0,
                        "default": 0
                    },
                    "statusDetailDescription": {
                        "description": "Tracking status detail description, localized",
                        "type": "string",
                        "example": "Held in depot",
                        "nullable": true
                    },
                    "statusDate": {
                        "description": "Date of the last tracking event as reported by the courier",
                        "type": "string",
                        "example": "2026-08-03 18:30:00",
                        "nullable": true
                    },
                    "statusUpdatedAt": {
                        "description": "When the tracking status last changed on Qapla. Filterable via updatedAfter.",
                        "type": "string",
                        "example": "2026-08-03 18:35:12",
                        "nullable": true
                    },
                    "statusPlace": {
                        "description": "Place of the last tracking event",
                        "type": "string",
                        "example": "Milano",
                        "nullable": true
                    },
                    "shipDate": {
                        "description": "Ship date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-01",
                        "nullable": true
                    },
                    "orderReference": {
                        "description": "Merchant order reference",
                        "type": "string",
                        "example": "ORD-2026-123",
                        "nullable": true
                    },
                    "platformOrderId": {
                        "description": "Order id on the source platform",
                        "type": "string",
                        "example": "10001234",
                        "nullable": true
                    },
                    "orderDate": {
                        "description": "Order date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-01",
                        "nullable": true
                    },
                    "tag": {
                        "description": "Free-text tag",
                        "type": "string",
                        "example": "priority",
                        "nullable": true
                    },
                    "note": {
                        "description": "Free-text note",
                        "type": "string",
                        "example": "Fragile",
                        "nullable": true
                    },
                    "origin": {
                        "description": "Source platform of the order",
                        "type": "string",
                        "example": "magento",
                        "nullable": true
                    },
                    "isReturn": {
                        "description": "Whether this shipment is a return",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "consignee": {
                        "$ref": "#/components/schemas/Consignee"
                    },
                    "monetary": {
                        "$ref": "#/components/schemas/Monetary"
                    },
                    "customAttributes": {
                        "$ref": "#/components/schemas/CustomAttributes"
                    }
                },
                "type": "object"
            },
            "ShipmentDetail": {
                "description": "Shipment (full projection)",
                "required": [
                    "planning",
                    "consignee",
                    "monetary",
                    "customAttributes"
                ],
                "properties": {
                    "planning": {
                        "$ref": "#/components/schemas/Planning"
                    },
                    "parcels": {
                        "description": "Parcels of the shipment",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentParcel"
                        },
                        "default": []
                    },
                    "orderItems": {
                        "description": "Order lines of the shipment",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentOrderItemResponse"
                        },
                        "default": []
                    },
                    "history": {
                        "description": "Tracking history, most recent first",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/TrackingHistoryEvent"
                        },
                        "default": []
                    },
                    "notifications": {
                        "description": "Notifications sent for this shipment",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/NotificationLog"
                        },
                        "default": []
                    },
                    "id": {
                        "description": "Shipment id",
                        "type": "integer",
                        "example": 123456,
                        "default": 0
                    },
                    "trackingNumber": {
                        "description": "Courier tracking number",
                        "type": "string",
                        "example": "1Z0V5V416840696736",
                        "default": ""
                    },
                    "trackingUrl": {
                        "description": "Public tracking page URL. Null when the tracking token is not available.",
                        "type": "string",
                        "example": "https://tracking.qapla.it/27e7cefc0e1e4e5e9c8b7a6d5f4e3d2c",
                        "nullable": true
                    },
                    "courier": {
                        "description": "Canonical courier code",
                        "type": "string",
                        "example": "UPS",
                        "default": ""
                    },
                    "courierName": {
                        "description": "Canonical courier name",
                        "type": "string",
                        "example": "UPS",
                        "nullable": true
                    },
                    "status": {
                        "$ref": "#/components/schemas/TrackingStatusEnum"
                    },
                    "statusDescription": {
                        "description": "Tracking status description, localized in the shipment language",
                        "type": "string",
                        "example": "In transit",
                        "nullable": true
                    },
                    "statusDetail": {
                        "description": "Tracking status detail id (0 = none)",
                        "type": "integer",
                        "example": 0,
                        "default": 0
                    },
                    "statusDetailDescription": {
                        "description": "Tracking status detail description, localized",
                        "type": "string",
                        "example": "Held in depot",
                        "nullable": true
                    },
                    "statusDate": {
                        "description": "Date of the last tracking event as reported by the courier",
                        "type": "string",
                        "example": "2026-08-03 18:30:00",
                        "nullable": true
                    },
                    "statusUpdatedAt": {
                        "description": "When the tracking status last changed on Qapla. Filterable via updatedAfter.",
                        "type": "string",
                        "example": "2026-08-03 18:35:12",
                        "nullable": true
                    },
                    "statusPlace": {
                        "description": "Place of the last tracking event",
                        "type": "string",
                        "example": "Milano",
                        "nullable": true
                    },
                    "shipDate": {
                        "description": "Ship date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-01",
                        "nullable": true
                    },
                    "orderReference": {
                        "description": "Merchant order reference",
                        "type": "string",
                        "example": "ORD-2026-123",
                        "nullable": true
                    },
                    "platformOrderId": {
                        "description": "Order id on the source platform",
                        "type": "string",
                        "example": "10001234",
                        "nullable": true
                    },
                    "orderDate": {
                        "description": "Order date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-01",
                        "nullable": true
                    },
                    "tag": {
                        "description": "Free-text tag",
                        "type": "string",
                        "example": "priority",
                        "nullable": true
                    },
                    "note": {
                        "description": "Free-text note",
                        "type": "string",
                        "example": "Fragile",
                        "nullable": true
                    },
                    "origin": {
                        "description": "Source platform of the order",
                        "type": "string",
                        "example": "magento",
                        "nullable": true
                    },
                    "isReturn": {
                        "description": "Whether this shipment is a return",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "consignee": {
                        "$ref": "#/components/schemas/Consignee"
                    },
                    "monetary": {
                        "$ref": "#/components/schemas/Monetary"
                    },
                    "customAttributes": {
                        "$ref": "#/components/schemas/CustomAttributes"
                    }
                },
                "type": "object"
            },
            "Consignee": {
                "description": "Shipment recipient",
                "properties": {
                    "name": {
                        "description": "Full name",
                        "type": "string",
                        "example": "Mario Rossi",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via Roma 1",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Milano",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "20100",
                        "nullable": true,
                        "maxLength": 20
                    },
                    "state": {
                        "description": "State / province",
                        "type": "string",
                        "example": "MI",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "country": {
                        "description": "Country (ISO 3166-1 alpha-2). Defaults to IT when omitted.",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "email": {
                        "description": "Email address (enables email notifications)",
                        "type": "string",
                        "example": "mario.rossi@example.com",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "phone": {
                        "description": "Phone number (enables SMS notifications)",
                        "type": "string",
                        "example": "+393331234567",
                        "nullable": true,
                        "maxLength": 50
                    }
                },
                "type": "object"
            },
            "Monetary": {
                "description": "Monetary information",
                "properties": {
                    "totalValue": {
                        "description": "Total order value",
                        "type": "number",
                        "format": "float",
                        "example": 150,
                        "nullable": true,
                        "minimum": 0
                    },
                    "codAmount": {
                        "description": "Cash on delivery amount. A value greater than zero marks the shipment as COD.",
                        "type": "number",
                        "format": "float",
                        "example": 0,
                        "nullable": true,
                        "minimum": 0
                    },
                    "shippingCost": {
                        "description": "Shipping cost paid by the customer",
                        "type": "number",
                        "format": "float",
                        "example": 8,
                        "nullable": true,
                        "minimum": 0
                    },
                    "currency": {
                        "description": "Currency (ISO 4217). Only EUR is currently supported.",
                        "type": "string",
                        "example": "EUR",
                        "default": "EUR",
                        "enum": [
                            "EUR"
                        ]
                    }
                },
                "type": "object"
            },
            "Planning": {
                "description": "Delivery planning",
                "properties": {
                    "deliveryDate": {
                        "description": "Expected delivery date. Either a plain date (YYYY-MM-DD, midnight Europe/Rome) or an ISO 8601 date-time with offset (YYYY-MM-DDThh:mm:ss\u00b1hh:mm or Z), stored as Europe/Rome wall-clock. Always returned as YYYY-MM-DD.",
                        "type": "string",
                        "example": "2026-08-10T15:00:00+02:00",
                        "nullable": true
                    },
                    "latestShipDate": {
                        "description": "Latest useful ship date. Either a plain date (YYYY-MM-DD, midnight Europe/Rome) or an ISO 8601 date-time with offset (YYYY-MM-DDThh:mm:ss\u00b1hh:mm or Z), stored as Europe/Rome wall-clock. Always returned as YYYY-MM-DD.",
                        "type": "string",
                        "example": "2026-08-06T15:00:00+02:00",
                        "nullable": true
                    },
                    "latestDeliveryDate": {
                        "description": "Latest useful delivery date. Either a plain date (YYYY-MM-DD, midnight Europe/Rome) or an ISO 8601 date-time with offset (YYYY-MM-DDThh:mm:ss\u00b1hh:mm or Z), stored as Europe/Rome wall-clock. Always returned as YYYY-MM-DD.",
                        "type": "string",
                        "example": "2026-08-12T15:00:00+02:00",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "CustomAttributes": {
                "description": "Merchant-defined custom attributes",
                "properties": {
                    "custom1": {
                        "description": "Custom field 1",
                        "type": "string",
                        "example": "info1",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom2": {
                        "description": "Custom field 2",
                        "type": "string",
                        "example": "info2",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom3": {
                        "description": "Custom field 3",
                        "type": "string",
                        "example": "info3",
                        "nullable": true,
                        "maxLength": 255
                    }
                },
                "type": "object"
            },
            "ShipmentCreateRequest": {
                "description": "Shipment to create",
                "required": [
                    "trackingNumber",
                    "courier",
                    "shipDate",
                    "consignee",
                    "monetary",
                    "planning",
                    "customAttributes"
                ],
                "properties": {
                    "trackingNumber": {
                        "description": "Courier tracking number",
                        "type": "string",
                        "example": "1Z0V5V416840696736",
                        "default": "",
                        "maxLength": 50
                    },
                    "courier": {
                        "description": "Courier code, name, or channel-specific transcoding. Courier variants must be enabled for the channel.",
                        "type": "string",
                        "example": "UPS",
                        "default": "",
                        "maxLength": 50
                    },
                    "shipDate": {
                        "description": "Ship date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-04",
                        "default": ""
                    },
                    "orderReference": {
                        "description": "Merchant order reference",
                        "type": "string",
                        "example": "ORD-2026-123",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "orderDate": {
                        "description": "Order date (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-01",
                        "nullable": true
                    },
                    "platformOrderId": {
                        "description": "Order id on the source platform",
                        "type": "string",
                        "example": "10001234",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "origin": {
                        "description": "Source platform of the order (must exist in the platform registry)",
                        "type": "string",
                        "example": "magento",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "language": {
                        "description": "Notification language (ISO 639-1). Must be a supported language.",
                        "type": "string",
                        "example": "it",
                        "nullable": true,
                        "default": "it",
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "tag": {
                        "description": "Free-text tag",
                        "type": "string",
                        "example": "priority",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "note": {
                        "description": "Free-text note",
                        "type": "string",
                        "example": "Fragile",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "isRealTrackingNumber": {
                        "description": "False when the tracking number is a placeholder not yet assigned by the courier",
                        "type": "boolean",
                        "example": true,
                        "default": true
                    },
                    "isReturnable": {
                        "description": "Whether the shipment can be returned",
                        "type": "boolean",
                        "example": true,
                        "default": true
                    },
                    "commercialContactEmail": {
                        "description": "Email of the commercial contact for this order",
                        "type": "string",
                        "example": "sales@merchant.com",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "consignee": {
                        "$ref": "#/components/schemas/Consignee"
                    },
                    "monetary": {
                        "$ref": "#/components/schemas/Monetary"
                    },
                    "planning": {
                        "$ref": "#/components/schemas/Planning"
                    },
                    "customAttributes": {
                        "$ref": "#/components/schemas/CustomAttributes"
                    },
                    "parcels": {
                        "description": "Parcels of the shipment",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentParcelInput"
                        },
                        "nullable": true,
                        "maxItems": 100
                    },
                    "orderItems": {
                        "description": "Order lines of the shipment",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentOrderItem"
                        },
                        "nullable": true,
                        "maxItems": 500
                    }
                },
                "type": "object"
            },
            "ShipmentParcelInput": {
                "description": "Parcel of a shipment (request)",
                "properties": {
                    "id": {
                        "description": "Client-side parcel identifier, referenced by orderItems[].parcelId",
                        "type": "string",
                        "example": "P1",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "trackingNumber": {
                        "description": "Parcel-specific tracking number, when the courier assigns one per parcel",
                        "type": "string",
                        "example": "1Z0V5V416840696737",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "weight": {
                        "description": "Weight in kg. Always required.",
                        "type": "number",
                        "format": "float",
                        "example": 1.25,
                        "nullable": true,
                        "maximum": 100000,
                        "exclusiveMaximum": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "length": {
                        "description": "Length in cm. Required when boxCode is not provided.",
                        "type": "number",
                        "format": "float",
                        "example": 40,
                        "nullable": true,
                        "maximum": 100000,
                        "exclusiveMaximum": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "width": {
                        "description": "Width in cm. Required when boxCode is not provided.",
                        "type": "number",
                        "format": "float",
                        "example": 30,
                        "nullable": true,
                        "maximum": 100000,
                        "exclusiveMaximum": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "height": {
                        "description": "Height in cm. Required when boxCode is not provided.",
                        "type": "number",
                        "format": "float",
                        "example": 20,
                        "nullable": true,
                        "maximum": 100000,
                        "exclusiveMaximum": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "boxCode": {
                        "description": "Code of a box from the company box registry (provides dimensions)",
                        "type": "string",
                        "example": "BOX-S",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "content": {
                        "description": "Free-text description of the parcel content",
                        "type": "string",
                        "example": "Shoes",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "originCountry": {
                        "description": "Origin country of the goods (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    }
                },
                "type": "object"
            },
            "ShipmentOrderItem": {
                "description": "Order line of a shipment",
                "required": [
                    "sku",
                    "name"
                ],
                "properties": {
                    "sku": {
                        "description": "Product SKU",
                        "type": "string",
                        "example": "SKU-001",
                        "default": "",
                        "maxLength": 100
                    },
                    "name": {
                        "description": "Product name",
                        "type": "string",
                        "example": "Running shoes",
                        "default": "",
                        "maxLength": 255
                    },
                    "quantity": {
                        "description": "Quantity",
                        "type": "integer",
                        "example": 2,
                        "default": 1,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "price": {
                        "description": "Unit price",
                        "type": "number",
                        "format": "float",
                        "example": 49.9,
                        "nullable": true,
                        "minimum": 0
                    },
                    "total": {
                        "description": "Line total (price x quantity)",
                        "type": "number",
                        "format": "float",
                        "example": 99.8,
                        "nullable": true,
                        "minimum": 0
                    },
                    "weight": {
                        "description": "Gross weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 0.8,
                        "nullable": true,
                        "minimum": 0
                    },
                    "netWeight": {
                        "description": "Net weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 0.7,
                        "nullable": true,
                        "minimum": 0
                    },
                    "unitOfMeasurement": {
                        "description": "Unit of measurement",
                        "type": "string",
                        "example": "pcs",
                        "nullable": true,
                        "maxLength": 10
                    },
                    "url": {
                        "description": "Product page URL",
                        "type": "string",
                        "example": "https://shop.example.com/p/sku-001",
                        "nullable": true
                    },
                    "imageUrl": {
                        "description": "Product image URL",
                        "type": "string",
                        "example": "https://shop.example.com/img/sku-001.jpg",
                        "nullable": true
                    },
                    "isReturnable": {
                        "description": "Whether the item can be returned",
                        "type": "boolean",
                        "example": true,
                        "default": true
                    },
                    "customsCode": {
                        "description": "Customs (HS) code",
                        "type": "string",
                        "example": "6403.99",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "originCountry": {
                        "description": "Origin country of the item (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "parcelId": {
                        "description": "Id of the parcel containing this item (parcels[].id)",
                        "type": "string",
                        "example": "P1",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "transparencyCodes": {
                        "description": "Amazon transparency codes",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "nullable": true
                    },
                    "notes": {
                        "description": "Free-text notes",
                        "type": "string",
                        "example": "Gift wrap",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom1": {
                        "description": "Custom field 1",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom2": {
                        "description": "Custom field 2",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom3": {
                        "description": "Custom field 3",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom4": {
                        "description": "Custom field 4",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom5": {
                        "description": "Custom field 5",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    }
                },
                "type": "object"
            },
            "ShipmentParcel": {
                "description": "Parcel of a shipment",
                "properties": {
                    "id": {
                        "description": "Client-side parcel identifier",
                        "type": "string",
                        "example": "P1",
                        "nullable": true
                    },
                    "trackingNumber": {
                        "description": "Parcel-specific tracking number",
                        "type": "string",
                        "example": "1Z0V5V416840696737",
                        "nullable": true
                    },
                    "weight": {
                        "description": "Weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 1.25,
                        "nullable": true
                    },
                    "length": {
                        "description": "Length in cm",
                        "type": "number",
                        "format": "float",
                        "example": 40,
                        "nullable": true
                    },
                    "width": {
                        "description": "Width in cm",
                        "type": "number",
                        "format": "float",
                        "example": 30,
                        "nullable": true
                    },
                    "height": {
                        "description": "Height in cm",
                        "type": "number",
                        "format": "float",
                        "example": 20,
                        "nullable": true
                    },
                    "boxCode": {
                        "description": "Box registry code used at creation",
                        "type": "string",
                        "example": "BOX-S",
                        "nullable": true
                    },
                    "content": {
                        "description": "Parcel content description",
                        "type": "string",
                        "example": "Shoes",
                        "nullable": true
                    },
                    "originCountry": {
                        "description": "Origin country of the goods (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "IT",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ShipmentOrderItemResponse": {
                "description": "Order line of a shipment",
                "properties": {
                    "sku": {
                        "description": "Product SKU",
                        "type": "string",
                        "example": "SKU-001",
                        "nullable": true
                    },
                    "name": {
                        "description": "Product name",
                        "type": "string",
                        "example": "Running shoes",
                        "nullable": true
                    },
                    "quantity": {
                        "description": "Quantity",
                        "type": "integer",
                        "example": 2,
                        "default": 1
                    },
                    "price": {
                        "description": "Unit price",
                        "type": "number",
                        "format": "float",
                        "example": 49.9,
                        "nullable": true
                    },
                    "total": {
                        "description": "Line total",
                        "type": "number",
                        "format": "float",
                        "example": 99.8,
                        "nullable": true
                    },
                    "weight": {
                        "description": "Gross weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 0.8,
                        "nullable": true
                    },
                    "netWeight": {
                        "description": "Net weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 0.7,
                        "nullable": true
                    },
                    "unitOfMeasurement": {
                        "description": "Unit of measurement",
                        "type": "string",
                        "example": "pcs",
                        "nullable": true
                    },
                    "url": {
                        "description": "Product page URL",
                        "type": "string",
                        "nullable": true
                    },
                    "imageUrl": {
                        "description": "Product image URL",
                        "type": "string",
                        "nullable": true
                    },
                    "isReturnable": {
                        "description": "Whether the item can be returned",
                        "type": "boolean",
                        "example": true,
                        "default": true
                    },
                    "customsCode": {
                        "description": "Customs (HS) code",
                        "type": "string",
                        "example": "6403.99",
                        "nullable": true
                    },
                    "originCountry": {
                        "description": "Origin country (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "IT",
                        "nullable": true
                    },
                    "parcelId": {
                        "description": "Id of the parcel containing this item",
                        "type": "string",
                        "example": "P1",
                        "nullable": true
                    },
                    "notes": {
                        "description": "Free-text notes",
                        "type": "string",
                        "nullable": true
                    },
                    "custom1": {
                        "description": "Custom field 1",
                        "type": "string",
                        "nullable": true
                    },
                    "custom2": {
                        "description": "Custom field 2",
                        "type": "string",
                        "nullable": true
                    },
                    "custom3": {
                        "description": "Custom field 3",
                        "type": "string",
                        "nullable": true
                    },
                    "custom4": {
                        "description": "Custom field 4",
                        "type": "string",
                        "nullable": true
                    },
                    "custom5": {
                        "description": "Custom field 5",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "TrackingHistoryEvent": {
                "description": "Tracking history event",
                "properties": {
                    "date": {
                        "description": "Event date (YYYY-MM-DD HH:MM:SS)",
                        "type": "string",
                        "example": "2026-08-02 10:00:00",
                        "default": ""
                    },
                    "courierStatus": {
                        "description": "Raw courier status",
                        "type": "string",
                        "example": "Delivered",
                        "nullable": true
                    },
                    "place": {
                        "description": "Event place",
                        "type": "string",
                        "example": "Milano",
                        "nullable": true
                    },
                    "status": {
                        "description": "Mapped Qapla status description",
                        "type": "string",
                        "example": "In transit",
                        "nullable": true
                    },
                    "statusCode": {
                        "description": "Mapped Qapla status code",
                        "type": "string",
                        "example": "IN_TRANSIT",
                        "nullable": true
                    },
                    "statusDetail": {
                        "description": "Status detail description",
                        "type": "string",
                        "example": "Held in depot",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "NotificationLog": {
                "description": "Notification sent for a shipment",
                "properties": {
                    "type": {
                        "description": "Notification type",
                        "type": "string",
                        "example": "email",
                        "nullable": true,
                        "enum": [
                            "email",
                            "sms",
                            "webhook"
                        ]
                    },
                    "result": {
                        "description": "Outcome",
                        "type": "string",
                        "example": "OK",
                        "nullable": true,
                        "enum": [
                            "OK",
                            "KO"
                        ]
                    },
                    "date": {
                        "description": "Sent at (YYYY-MM-DD HH:MM:SS)",
                        "type": "string",
                        "example": "2026-08-02 10:05:00",
                        "nullable": true
                    },
                    "recipient": {
                        "description": "Recipient (email address, phone number or URL)",
                        "type": "string",
                        "example": "user@example.com",
                        "nullable": true
                    },
                    "shipmentStatus": {
                        "description": "Shipment status at notification time",
                        "type": "string",
                        "example": "In transit",
                        "nullable": true
                    },
                    "error": {
                        "description": "Error detail, when the outcome is KO",
                        "type": "string",
                        "example": "SMTP error",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ShipmentError": {
                "description": "Per-item error of a bulk creation",
                "required": [
                    "code",
                    "message"
                ],
                "properties": {
                    "code": {
                        "description": "Machine-readable error code",
                        "type": "string",
                        "example": "INVALID_COURIER"
                    },
                    "message": {
                        "description": "Human-readable message",
                        "type": "string",
                        "example": "Invalid courier code: 'XYZ'"
                    },
                    "field": {
                        "description": "Field the error refers to, when applicable",
                        "type": "string",
                        "example": "courier",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "ShipmentCreateResult": {
                "description": "Per-item outcome of a bulk creation",
                "required": [
                    "status",
                    "trackingNumber",
                    "success"
                ],
                "properties": {
                    "status": {
                        "description": "Item outcome",
                        "type": "string",
                        "example": "success",
                        "enum": [
                            "success",
                            "error"
                        ]
                    },
                    "trackingNumber": {
                        "description": "Tracking number of the request item",
                        "type": "string",
                        "example": "1Z0V5V416840696736"
                    },
                    "id": {
                        "description": "Id of the created shipment",
                        "type": "integer",
                        "example": 123456,
                        "nullable": true,
                        "default": null
                    },
                    "trackingUrl": {
                        "description": "Public tracking page URL of the created shipment",
                        "type": "string",
                        "example": "https://tracking.qapla.it/27e7cefc0e1e4e5e9c8b7a6d5f4e3d2c",
                        "nullable": true,
                        "default": null
                    },
                    "errors": {
                        "description": "Errors, present when status is error",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentError"
                        },
                        "default": []
                    },
                    "success": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "ShipmentBatchSummary": {
                "description": "Summary of a bulk creation",
                "required": [
                    "totalRequested",
                    "totalSuccess",
                    "totalFailed"
                ],
                "properties": {
                    "totalRequested": {
                        "description": "Shipments in the request",
                        "type": "integer",
                        "example": 10
                    },
                    "totalSuccess": {
                        "description": "Shipments created",
                        "type": "integer",
                        "example": 9
                    },
                    "totalFailed": {
                        "description": "Shipments rejected",
                        "type": "integer",
                        "example": 1
                    }
                },
                "type": "object"
            },
            "AddressCheckRequest": {
                "description": "Verify a postal address against a geocoder or the GLS street registry.",
                "required": [
                    "address"
                ],
                "properties": {
                    "address": {
                        "$ref": "#/components/schemas/AddressCheckInput"
                    },
                    "provider": {
                        "description": "Backend to query. `gls` is Italy-only and requires GLS to be configured on the channel.",
                        "type": "string",
                        "example": "geocode",
                        "default": "geocode",
                        "enum": [
                            "geocode",
                            "gls"
                        ]
                    }
                },
                "type": "object"
            },
            "AddressCheckResponse": {
                "description": "Address verification result",
                "required": [
                    "provider",
                    "match"
                ],
                "properties": {
                    "provider": {
                        "description": "Provider that answered",
                        "type": "string",
                        "example": "geocode",
                        "enum": [
                            "geocode",
                            "gls"
                        ]
                    },
                    "match": {
                        "$ref": "#/components/schemas/AddressCheckMatch"
                    },
                    "formatted": {
                        "description": "Single-line normalised address, when the provider returns one",
                        "type": "string",
                        "example": "Via Roma, 1, 20121 Milano MI, Italia",
                        "nullable": true
                    },
                    "components": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddressCheckComponents"
                            }
                        ],
                        "nullable": true
                    },
                    "coordinates": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddressCheckCoordinates"
                            }
                        ],
                        "nullable": true
                    },
                    "candidates": {
                        "description": "Alternative addresses proposed by the provider when the submitted one is not conformant",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/AddressCheckComponents"
                        },
                        "default": []
                    },
                    "delivery": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AddressCheckDelivery"
                            }
                        ],
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "AddressCheckInput": {
                "description": "Address to verify",
                "required": [
                    "street",
                    "city"
                ],
                "properties": {
                    "street": {
                        "description": "Street address, house number included",
                        "type": "string",
                        "example": "Via Roma 1",
                        "default": "",
                        "maxLength": 255
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Milano",
                        "default": "",
                        "maxLength": 255
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "20121",
                        "nullable": true,
                        "maxLength": 20
                    },
                    "state": {
                        "description": "State / province",
                        "type": "string",
                        "example": "MI",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "country": {
                        "description": "Country (ISO 3166-1 alpha-2). Defaults to IT when omitted.",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    }
                },
                "type": "object"
            },
            "AddressCheckComponents": {
                "description": "Normalised address parts",
                "properties": {
                    "street": {
                        "description": "Street address, house number included",
                        "type": "string",
                        "example": "Via Roma, 1",
                        "nullable": true
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Milano",
                        "nullable": true
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "20121",
                        "nullable": true
                    },
                    "state": {
                        "description": "State / province",
                        "type": "string",
                        "example": "MI",
                        "nullable": true
                    },
                    "region": {
                        "description": "Administrative region, when the provider knows it",
                        "type": "string",
                        "example": "Lombardia",
                        "nullable": true
                    },
                    "country": {
                        "description": "Country (ISO 3166-1 alpha-2)",
                        "type": "string",
                        "example": "IT",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "AddressCheckMatch": {
                "description": "Match quality",
                "required": [
                    "status"
                ],
                "properties": {
                    "status": {
                        "description": "FULL when confidence >= 90, WARNING when >= 80, NONE below that or when nothing matched",
                        "type": "string",
                        "example": "FULL",
                        "enum": [
                            "FULL",
                            "WARNING",
                            "NONE"
                        ]
                    },
                    "confidence": {
                        "description": "Confidence 0-100. Comparable across providers. Null when nothing matched.",
                        "type": "number",
                        "format": "float",
                        "example": 96.4,
                        "nullable": true
                    },
                    "partial": {
                        "description": "True when the provider matched only part of the address",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    }
                },
                "type": "object"
            },
            "AddressCheckCoordinates": {
                "description": "Geographic coordinates",
                "required": [
                    "latitude",
                    "longitude"
                ],
                "properties": {
                    "latitude": {
                        "description": "Latitude",
                        "type": "number",
                        "format": "float",
                        "example": 45.4642
                    },
                    "longitude": {
                        "description": "Longitude",
                        "type": "number",
                        "format": "float",
                        "example": 9.19
                    }
                },
                "type": "object"
            },
            "AddressCheckDelivery": {
                "description": "Courier delivery constraints",
                "properties": {
                    "restrictedTrafficZone": {
                        "description": "Address is inside a restricted traffic zone (ZTL)",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "difficultArea": {
                        "description": "Address is a difficult location (localit\u00e0 disagiata): a surcharge usually applies",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "branch": {
                        "description": "Courier branch serving the address",
                        "type": "string",
                        "example": "MI",
                        "nullable": true
                    },
                    "zone": {
                        "description": "Courier delivery zone",
                        "type": "string",
                        "example": "01",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "OrderSenderDto": {
                "description": "Sender identification and address details",
                "required": [
                    "isDefault"
                ],
                "properties": {
                    "code": {
                        "description": "Sender short code (e.g., FEDO) \u2014 used to resolve the sender ID",
                        "type": "string",
                        "example": "FEDO",
                        "nullable": true,
                        "default": null
                    },
                    "businessName": {
                        "description": "Business name",
                        "type": "string",
                        "example": "Fed\u00f2 snc",
                        "nullable": true,
                        "default": null
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via I Maggio, 11",
                        "nullable": true,
                        "default": null
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Vedano Olona",
                        "nullable": true,
                        "default": null
                    },
                    "state": {
                        "description": "Province/State code",
                        "type": "string",
                        "example": "VA",
                        "nullable": true,
                        "default": null
                    },
                    "postcode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "21040",
                        "nullable": true,
                        "default": null
                    },
                    "country": {
                        "description": "Country ISO 3166-1 alpha-2 code",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "default": null
                    },
                    "email": {
                        "description": "Email address",
                        "type": "string",
                        "example": "evelina@fedo.it",
                        "nullable": true,
                        "default": null
                    },
                    "phone": {
                        "description": "Phone number",
                        "type": "string",
                        "example": "0332261261",
                        "nullable": true,
                        "default": null
                    },
                    "referent": {
                        "description": "Referent person name",
                        "type": "string",
                        "example": "Evelina",
                        "nullable": true,
                        "default": null
                    },
                    "isDefault": {
                        "description": "Is default sender",
                        "type": "boolean",
                        "example": false
                    }
                },
                "type": "object"
            },
            "OrderPudoDto": {
                "description": "Pick-Up Drop-Off location details",
                "properties": {
                    "id": {
                        "description": "PUDO identification code/id \u2014 persisted to pickupPoint",
                        "type": "string",
                        "example": "1234",
                        "nullable": true,
                        "default": null
                    },
                    "type": {
                        "description": "Type of PUDO (e.g., LOCKER)",
                        "type": "string",
                        "example": "LOCKER",
                        "nullable": true,
                        "default": null
                    },
                    "name": {
                        "description": "Name of the PUDO location",
                        "type": "string",
                        "example": "Bar Mario snc",
                        "nullable": true,
                        "default": null
                    },
                    "street": {
                        "description": "Street address",
                        "type": "string",
                        "example": "Via mario rossi",
                        "nullable": true,
                        "default": null
                    },
                    "city": {
                        "description": "City",
                        "type": "string",
                        "example": "Varese",
                        "nullable": true,
                        "default": null
                    },
                    "state": {
                        "description": "Province/State code",
                        "type": "string",
                        "example": "VA",
                        "nullable": true,
                        "default": null
                    },
                    "country": {
                        "description": "Country ISO 3166-1 alpha-2 code",
                        "type": "string",
                        "example": "IT",
                        "nullable": true,
                        "default": null
                    },
                    "postalCode": {
                        "description": "Postal code",
                        "type": "string",
                        "example": "21100",
                        "nullable": true,
                        "default": null
                    },
                    "description": {
                        "description": "Additional description/notes",
                        "type": "string",
                        "example": "Note",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "OrderCreateRequest": {
                "description": "Payload for creating a new order",
                "required": [
                    "reference",
                    "source"
                ],
                "properties": {
                    "reference": {
                        "description": "Order reference (human-readable ID from the platform)",
                        "type": "string",
                        "example": "ORD-2024-001",
                        "maxLength": 255
                    },
                    "source": {
                        "description": "Source/origin platform (e.g. shopify, magento, woocommerce)",
                        "type": "string",
                        "example": "shopify",
                        "maxLength": 50
                    },
                    "orderId": {
                        "description": "Platform's internal numeric/technical order ID",
                        "type": "string",
                        "example": "998877",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "courierId": {
                        "description": "Courier ID (0 = not yet assigned)",
                        "type": "integer",
                        "example": 0,
                        "default": 0,
                        "minimum": 0
                    },
                    "courierService": {
                        "description": "Courier service/contract code",
                        "type": "string",
                        "example": "EXPRESS",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "status": {
                        "description": "Order status",
                        "type": "string",
                        "example": "processing",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "createdAt": {
                        "description": "Order creation date (ISO 8601 or Y-m-d)",
                        "type": "string",
                        "example": "2024-01-15",
                        "nullable": true
                    },
                    "notes": {
                        "description": "Order notes",
                        "type": "string",
                        "nullable": true
                    },
                    "content": {
                        "description": "Goods/content description",
                        "type": "string",
                        "example": "Clothing",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "tag": {
                        "description": "Color tag for UI grouping",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "pickupDate": {
                        "description": "Pickup date (YYYY-MM-DD)",
                        "type": "string",
                        "nullable": true
                    },
                    "pickupTime": {
                        "description": "Pickup time (HH:MM)",
                        "type": "string",
                        "nullable": true
                    },
                    "pickupPoint": {
                        "description": "Pickup point / PUDO locker ID",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "isReturnable": {
                        "description": "Whether the order supports returns",
                        "type": "boolean",
                        "example": false,
                        "default": false
                    },
                    "platformDeliveryType": {
                        "description": "Platform delivery type",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "consignee": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderConsigneeDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Recipient address"
                    },
                    "monetary": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderMonetaryDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Monetary information"
                    },
                    "planning": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPlanningDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Delivery planning"
                    },
                    "customAttributes": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderCustomAttributesDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Custom attributes"
                    },
                    "parcels": {
                        "description": "Parcels \u2014 weights and dimensions are aggregated into scalar DB fields",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderParcelDto"
                        },
                        "nullable": true,
                        "default": null
                    },
                    "items": {
                        "description": "Order line items",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItemDto"
                        },
                        "nullable": true,
                        "default": null
                    },
                    "sender": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderSenderDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Sender \u2014 code resolves the sender ID from channel dictionary"
                    },
                    "pudo": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPudoDto"
                            }
                        ],
                        "nullable": true,
                        "description": "PUDO location \u2014 only id is persisted to pickupPoint"
                    },
                    "config": {
                        "description": "JSON config blob for courier-specific settings",
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "OrderPutRequest": {
                "description": "Payload for full replacement of an existing order (PUT semantics)",
                "required": [
                    "reference",
                    "source"
                ],
                "properties": {
                    "reference": {
                        "description": "Order reference \u2014 confirms the natural key being replaced",
                        "type": "string",
                        "example": "ORD-2024-001",
                        "maxLength": 255
                    },
                    "source": {
                        "description": "Source/origin platform",
                        "type": "string",
                        "example": "shopify",
                        "maxLength": 50
                    },
                    "orderId": {
                        "description": "Platform's internal numeric/technical order ID",
                        "type": "string",
                        "example": "998877",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "courierId": {
                        "description": "Courier ID (0 = not assigned)",
                        "type": "integer",
                        "example": 0,
                        "default": 0,
                        "minimum": 0
                    },
                    "courierService": {
                        "description": "Courier service/contract code",
                        "type": "string",
                        "example": "EXPRESS",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "status": {
                        "description": "Order status",
                        "type": "string",
                        "example": "processing",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "createdAt": {
                        "description": "Order creation date (ISO 8601 or Y-m-d)",
                        "type": "string",
                        "example": "2024-01-15",
                        "nullable": true
                    },
                    "notes": {
                        "description": "Order notes",
                        "type": "string",
                        "nullable": true
                    },
                    "content": {
                        "description": "Goods/content description",
                        "type": "string",
                        "example": "Clothing",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "tag": {
                        "description": "Color tag for UI grouping",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "pickupDate": {
                        "description": "Pickup date (YYYY-MM-DD)",
                        "type": "string",
                        "nullable": true
                    },
                    "pickupTime": {
                        "description": "Pickup time (HH:MM)",
                        "type": "string",
                        "nullable": true
                    },
                    "pickupPoint": {
                        "description": "Pickup point / PUDO locker ID",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "isReturnable": {
                        "description": "Whether the order supports returns",
                        "type": "boolean",
                        "example": false,
                        "nullable": true
                    },
                    "platformDeliveryType": {
                        "description": "Platform delivery type",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "consignee": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderConsigneeDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Recipient address"
                    },
                    "monetary": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderMonetaryDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Monetary information"
                    },
                    "planning": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPlanningDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Delivery planning"
                    },
                    "customAttributes": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderCustomAttributesDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Custom attributes"
                    },
                    "parcels": {
                        "description": "Parcels",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderParcelDto"
                        },
                        "nullable": true,
                        "default": null
                    },
                    "items": {
                        "description": "Order line items",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItemDto"
                        },
                        "nullable": true,
                        "default": null
                    },
                    "sender": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderSenderDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Sender"
                    },
                    "pudo": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPudoDto"
                            }
                        ],
                        "nullable": true,
                        "description": "PUDO location"
                    },
                    "config": {
                        "description": "JSON config blob for courier-specific settings",
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "OrderPatchRequest": {
                "description": "Payload for partial update of an existing order (PATCH semantics)",
                "properties": {
                    "reference": {
                        "description": "Order reference",
                        "type": "string",
                        "example": "ORD-2024-001",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "source": {
                        "description": "Source/origin platform",
                        "type": "string",
                        "example": "shopify",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "orderId": {
                        "description": "Platform's internal numeric/technical order ID",
                        "type": "string",
                        "example": "998877",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "courierId": {
                        "description": "Courier ID",
                        "type": "integer",
                        "example": 42,
                        "nullable": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "courierService": {
                        "description": "Courier service/contract code",
                        "type": "string",
                        "example": "EXPRESS",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "status": {
                        "description": "Order status",
                        "type": "string",
                        "example": "processing",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "createdAt": {
                        "description": "Order creation date (ISO 8601 or Y-m-d)",
                        "type": "string",
                        "example": "2024-01-15",
                        "nullable": true
                    },
                    "notes": {
                        "description": "Order notes",
                        "type": "string",
                        "nullable": true
                    },
                    "content": {
                        "description": "Goods/content description",
                        "type": "string",
                        "example": "Clothing",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "tag": {
                        "description": "Color tag for UI grouping",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "pickupDate": {
                        "description": "Pickup date (YYYY-MM-DD)",
                        "type": "string",
                        "nullable": true
                    },
                    "pickupTime": {
                        "description": "Pickup time (HH:MM)",
                        "type": "string",
                        "nullable": true
                    },
                    "pickupPoint": {
                        "description": "Pickup point / PUDO locker ID",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "isReturnable": {
                        "description": "Whether the order supports returns",
                        "type": "boolean",
                        "nullable": true
                    },
                    "platformDeliveryType": {
                        "description": "Platform delivery type",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "consignee": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderConsigneeDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Recipient address"
                    },
                    "monetary": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderMonetaryDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Monetary information"
                    },
                    "planning": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPlanningDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Delivery planning"
                    },
                    "customAttributes": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderCustomAttributesDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Custom attributes"
                    },
                    "parcels": {
                        "description": "Parcels",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderParcelDto"
                        },
                        "nullable": true,
                        "default": null
                    },
                    "items": {
                        "description": "Order line items",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItemDto"
                        },
                        "nullable": true,
                        "default": null
                    },
                    "sender": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderSenderDto"
                            }
                        ],
                        "nullable": true,
                        "description": "Sender"
                    },
                    "pudo": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/OrderPudoDto"
                            }
                        ],
                        "nullable": true,
                        "description": "PUDO location"
                    },
                    "config": {
                        "description": "JSON config blob for courier-specific settings",
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "DeliveryTimesRequest": {
                "required": [
                    "destCap"
                ],
                "properties": {
                    "destCap": {
                        "description": "Destination Italian postal code (5 digits)",
                        "type": "string",
                        "pattern": "\\d{5}",
                        "example": "20100"
                    },
                    "couriers": {
                        "description": "Courier codes to compare. Optional: if omitted (or empty), the shipping-enabled couriers of the authenticated channel are used.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "BRT",
                            "GLS",
                            "TNT"
                        ],
                        "default": [],
                        "maxItems": 50
                    },
                    "weightKg": {
                        "description": "Optional parcel weight in kg; selects the matching weight band for a weight-specific estimate",
                        "type": "number",
                        "format": "float",
                        "example": 3.5,
                        "nullable": true,
                        "default": null,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "originCap": {
                        "description": "Optional origin postal code (5 digits). When provided it is used for the finest origin_cap_dest* grains; when omitted, the authenticated company seat CAP is used.",
                        "type": "string",
                        "pattern": "\\d{5}",
                        "example": "20121",
                        "nullable": true,
                        "default": null
                    },
                    "detail": {
                        "description": "Response verbosity: \"summary\" (default) returns the best courier plus a slim ranking; \"full\" returns the complete ranking with all percentiles, grain and insufficient-data couriers",
                        "type": "string",
                        "example": "summary",
                        "default": "summary",
                        "enum": [
                            "summary",
                            "full"
                        ]
                    }
                },
                "type": "object"
            },
            "DeliveryTimeEntryDto": {
                "required": [
                    "courierCode",
                    "status"
                ],
                "properties": {
                    "position": {
                        "description": "Ranking position (1 = fastest); null for couriers with insufficient data",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    },
                    "courierCode": {
                        "description": "Courier code",
                        "type": "string",
                        "example": "BRT"
                    },
                    "status": {
                        "description": "Row status",
                        "type": "string",
                        "example": "ok",
                        "enum": [
                            "ok",
                            "insufficient_data"
                        ]
                    },
                    "level": {
                        "description": "Benchmark grain used for this courier",
                        "type": "string",
                        "example": "origin_cap_dest_weight",
                        "nullable": true,
                        "enum": [
                            "origin_cap_dest_weight",
                            "origin_cap_dest",
                            "area_cap_weight",
                            "cap_weight",
                            "area_cap",
                            "cap"
                        ]
                    },
                    "weightBand": {
                        "description": "Weight band of the data used; null when the estimate is weight-agnostic",
                        "type": "string",
                        "example": "2-5",
                        "nullable": true
                    },
                    "sampleSize": {
                        "description": "Sample size (deliveries in the benchmark cell, last 12 months)",
                        "type": "integer",
                        "example": 1673,
                        "nullable": true
                    },
                    "leadMedian": {
                        "description": "Median lead time in calendar days (shipped -> delivered)",
                        "type": "integer",
                        "example": 2,
                        "nullable": true
                    },
                    "leadMean": {
                        "description": "Mean lead time in calendar days (shipped -> delivered), rounded to 1 decimal; tie-breaker after the median",
                        "type": "number",
                        "format": "float",
                        "example": 2.3,
                        "nullable": true
                    },
                    "leadP90": {
                        "description": "P90 lead time in calendar days (tail reliability)",
                        "type": "integer",
                        "example": 3,
                        "nullable": true
                    },
                    "transitMedian": {
                        "description": "Median transit time in calendar days (departed -> delivered, carrier-only)",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    },
                    "transitMean": {
                        "description": "Mean transit time in calendar days (departed -> delivered, carrier-only), rounded to 1 decimal",
                        "type": "number",
                        "format": "float",
                        "example": 1.4,
                        "nullable": true
                    },
                    "transitP90": {
                        "description": "P90 transit time in calendar days",
                        "type": "integer",
                        "example": 2,
                        "nullable": true
                    },
                    "transitSampleSize": {
                        "description": "Transit sample size; typically lower than sampleSize (history ~2026+) \u2014 judge transit reliability with this",
                        "type": "integer",
                        "example": 820,
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "DeliveryTimeComparisonResponse": {
                "required": [
                    "destCap",
                    "ranking"
                ],
                "properties": {
                    "destCap": {
                        "description": "Destination postal code echoed from the request",
                        "type": "string",
                        "example": "20100"
                    },
                    "originCap": {
                        "description": "Origin postal code (authenticated company seat CAP) used for the finest origin_cap_dest* grains; null when the seat CAP is not a valid Italian CAP",
                        "type": "string",
                        "example": "20121",
                        "nullable": true
                    },
                    "originArea": {
                        "description": "Origin macro-area deduced from the authenticated company; null if not resolvable (then only postal-code-level grains are used)",
                        "type": "string",
                        "example": "NORD",
                        "nullable": true,
                        "enum": [
                            "NORD",
                            "CENTRO",
                            "SUD"
                        ]
                    },
                    "requestedWeightBand": {
                        "description": "Weight band derived from the requested weightKg; null if weightKg was omitted",
                        "type": "string",
                        "example": "2-5",
                        "nullable": true
                    },
                    "ranking": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/DeliveryTimeEntryDto"
                        }
                    }
                },
                "type": "object"
            },
            "DeliveryTimeBestDto": {
                "required": [
                    "courierCode",
                    "sampleSize"
                ],
                "properties": {
                    "courierCode": {
                        "description": "Courier code of the fastest carrier",
                        "type": "string",
                        "example": "BRT"
                    },
                    "leadMedian": {
                        "description": "Median lead time in calendar days (shipped -> delivered)",
                        "type": "integer",
                        "example": 2,
                        "nullable": true
                    },
                    "leadMean": {
                        "description": "Mean lead time in calendar days (shipped -> delivered), rounded to 1 decimal",
                        "type": "number",
                        "format": "float",
                        "example": 2.3,
                        "nullable": true
                    },
                    "transitMedian": {
                        "description": "Median transit time in calendar days (departed -> delivered, carrier-only); null when the carrier sample is too thin",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    },
                    "transitMean": {
                        "description": "Mean transit time in calendar days (departed -> delivered, carrier-only), rounded to 1 decimal; null when the carrier sample is too thin",
                        "type": "number",
                        "format": "float",
                        "example": 1.4,
                        "nullable": true
                    },
                    "sampleSize": {
                        "description": "Sample size (deliveries in the benchmark cell, last 12 months)",
                        "type": "integer",
                        "example": 1673
                    }
                },
                "type": "object"
            },
            "DeliveryTimeSummaryEntryDto": {
                "required": [
                    "position",
                    "courierCode",
                    "sampleSize"
                ],
                "properties": {
                    "position": {
                        "description": "Ranking position (1 = fastest)",
                        "type": "integer",
                        "example": 1
                    },
                    "courierCode": {
                        "description": "Courier code",
                        "type": "string",
                        "example": "BRT"
                    },
                    "leadMedian": {
                        "description": "Median lead time in calendar days (shipped -> delivered)",
                        "type": "integer",
                        "example": 2,
                        "nullable": true
                    },
                    "transitMedian": {
                        "description": "Median transit time in calendar days (departed -> delivered, carrier-only); null when the carrier sample is too thin",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    },
                    "sampleSize": {
                        "description": "Sample size (deliveries in the benchmark cell, last 12 months)",
                        "type": "integer",
                        "example": 1673
                    }
                },
                "type": "object"
            },
            "DeliveryTimeSummaryResponse": {
                "required": [
                    "destCap",
                    "ranking"
                ],
                "properties": {
                    "destCap": {
                        "description": "Destination postal code echoed from the request",
                        "type": "string",
                        "example": "20100"
                    },
                    "originCap": {
                        "description": "Origin postal code (authenticated company seat CAP) used for the finest origin_cap_dest* grains; null when the seat CAP is not a valid Italian CAP",
                        "type": "string",
                        "example": "20121",
                        "nullable": true
                    },
                    "originArea": {
                        "description": "Origin macro-area deduced from the authenticated company; null if not resolvable",
                        "type": "string",
                        "example": "NORD",
                        "nullable": true,
                        "enum": [
                            "NORD",
                            "CENTRO",
                            "SUD"
                        ]
                    },
                    "requestedWeightBand": {
                        "description": "Weight band derived from the requested weightKg; null if weightKg was omitted",
                        "type": "string",
                        "example": "2-5",
                        "nullable": true
                    },
                    "best": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/DeliveryTimeBestDto"
                            }
                        ],
                        "nullable": true,
                        "description": "The fastest courier on the lane; null when none of the requested couriers has enough data"
                    },
                    "ranking": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/DeliveryTimeSummaryEntryDto"
                        }
                    }
                },
                "type": "object"
            },
            "CourierEfficiencyRequest": {
                "required": [
                    "destCap"
                ],
                "properties": {
                    "destCap": {
                        "description": "Destination Italian postal code (5 digits)",
                        "type": "string",
                        "pattern": "\\d{5}",
                        "example": "20100"
                    },
                    "couriers": {
                        "description": "Courier codes to score. Optional: if omitted (or empty), the shipping-enabled couriers of the authenticated channel are used.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "BRT",
                            "GLS",
                            "TNT"
                        ],
                        "default": [],
                        "maxItems": 50
                    },
                    "weightKg": {
                        "description": "Optional parcel weight in kg; selects the matching weight band for a weight-specific score",
                        "type": "number",
                        "format": "float",
                        "example": 3.5,
                        "nullable": true,
                        "default": null,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "originCap": {
                        "description": "Optional origin postal code (5 digits). When provided it is used for the finest origin_cap_dest* grains; when omitted, the authenticated company seat CAP is used.",
                        "type": "string",
                        "pattern": "\\d{5}",
                        "example": "20121",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "CourierEfficiencyEntryDto": {
                "required": [
                    "courierCode",
                    "status"
                ],
                "properties": {
                    "rank": {
                        "description": "Rank by efficiency index (1 = best); ties share a rank. Null for couriers with insufficient data",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    },
                    "courierCode": {
                        "description": "Courier code",
                        "type": "string",
                        "example": "BRT"
                    },
                    "status": {
                        "description": "Row status",
                        "type": "string",
                        "example": "ok",
                        "enum": [
                            "ok",
                            "insufficient_data"
                        ]
                    },
                    "efficiencyIndex": {
                        "description": "Overall efficiency index 0-100 (higher is better), rounded to 1 decimal",
                        "type": "number",
                        "format": "float",
                        "example": 87.4,
                        "nullable": true
                    },
                    "scoreSpeed": {
                        "description": "Speed sub-score 0-100 (from the speed median), rounded to 1 decimal",
                        "type": "number",
                        "format": "float",
                        "example": 86,
                        "nullable": true
                    },
                    "scoreConsistency": {
                        "description": "Consistency sub-score 0-100 (from the p90-to-median gap), rounded to 1 decimal",
                        "type": "number",
                        "format": "float",
                        "example": 86,
                        "nullable": true
                    },
                    "scoreReliability": {
                        "description": "Reliability sub-score 0-100 (from failed/stock/exception rates), rounded to 1 decimal",
                        "type": "number",
                        "format": "float",
                        "example": 90,
                        "nullable": true
                    },
                    "level": {
                        "description": "Benchmark grain used for this courier",
                        "type": "string",
                        "example": "origin_cap_dest_weight",
                        "nullable": true,
                        "enum": [
                            "origin_cap_dest_weight",
                            "origin_cap_dest",
                            "area_cap_weight",
                            "cap_weight",
                            "area_cap",
                            "cap"
                        ]
                    },
                    "sampleSize": {
                        "description": "Sample size (deliveries in the benchmark cell)",
                        "type": "integer",
                        "example": 1673,
                        "nullable": true
                    },
                    "speedMedian": {
                        "description": "Speed median in calendar days (transit median if available, else lead median); the basis of scoreSpeed",
                        "type": "integer",
                        "example": 2,
                        "nullable": true
                    },
                    "speedP90": {
                        "description": "Speed p90 in calendar days (transit p90 if available, else lead p90); the basis of scoreConsistency",
                        "type": "integer",
                        "example": 3,
                        "nullable": true
                    },
                    "failedRate": {
                        "description": "Failed-delivery rate of the lane cell (fraction 0-1)",
                        "type": "number",
                        "format": "float",
                        "example": 0.012,
                        "nullable": true
                    },
                    "stockRate": {
                        "description": "Stock/storage rate of the lane cell (fraction 0-1)",
                        "type": "number",
                        "format": "float",
                        "example": 0.004,
                        "nullable": true
                    },
                    "exceptionRate": {
                        "description": "Exception rate of the lane cell (fraction 0-1)",
                        "type": "number",
                        "format": "float",
                        "example": 0.021,
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "CourierEfficiencyResponse": {
                "required": [
                    "destCap",
                    "ranking"
                ],
                "properties": {
                    "destCap": {
                        "description": "Destination postal code echoed from the request",
                        "type": "string",
                        "example": "20100"
                    },
                    "originCap": {
                        "description": "Origin postal code (authenticated company seat CAP) used for the finest origin_cap_dest* grains; null when the seat CAP is not a valid Italian CAP",
                        "type": "string",
                        "example": "20121",
                        "nullable": true
                    },
                    "originArea": {
                        "description": "Origin macro-area deduced from the authenticated company; null if not resolvable (then only postal-code-level grains are used)",
                        "type": "string",
                        "example": "NORD",
                        "nullable": true,
                        "enum": [
                            "NORD",
                            "CENTRO",
                            "SUD"
                        ]
                    },
                    "requestedWeightBand": {
                        "description": "Weight band derived from the requested weightKg; null if weightKg was omitted",
                        "type": "string",
                        "example": "2-5",
                        "nullable": true
                    },
                    "ranking": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CourierEfficiencyEntryDto"
                        }
                    }
                },
                "type": "object"
            },
            "TokenRequest": {
                "required": [
                    "apiKey"
                ],
                "properties": {
                    "apiKey": {
                        "description": "API Key",
                        "type": "string",
                        "example": "sk_live_abc123def456"
                    }
                },
                "type": "object"
            },
            "OrderDto": {
                "required": [
                    "reference",
                    "origin"
                ],
                "properties": {
                    "reference": {
                        "type": "string"
                    },
                    "origin": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "ParcelItemDto": {
                "required": [
                    "weightKg",
                    "lengthCm",
                    "widthCm",
                    "heightCm",
                    "originCountryIso"
                ],
                "properties": {
                    "weightKg": {
                        "type": "number",
                        "format": "float",
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "lengthCm": {
                        "type": "number",
                        "format": "float",
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "widthCm": {
                        "type": "number",
                        "format": "float",
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "heightCm": {
                        "type": "number",
                        "format": "float",
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "originCountryIso": {
                        "type": "string",
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "contentsDescription": {
                        "type": "string",
                        "nullable": true,
                        "default": null
                    },
                    "clientInternalCode": {
                        "type": "string",
                        "nullable": true,
                        "default": null
                    },
                    "shippingNotes": {
                        "type": "string",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "ParcelRequest": {
                "required": [
                    "order",
                    "parcels"
                ],
                "properties": {
                    "order": {
                        "$ref": "#/components/schemas/OrderDto"
                    },
                    "parcels": {
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/ParcelItemDto"
                                }
                            },
                            {
                                "type": "object",
                                "additionalProperties": {
                                    "$ref": "#/components/schemas/ParcelItemDto"
                                }
                            }
                        ],
                        "maxItems": 100,
                        "minItems": 1
                    },
                    "channelId": {
                        "type": "integer",
                        "nullable": true,
                        "default": null
                    },
                    "webhookUrl": {
                        "description": "Optional URL to receive a webhook notification when async processing completes",
                        "type": "string",
                        "example": "https://webhook.site/uuid",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "ParcelListRequest": {
                "required": [
                    "orderReference",
                    "orderOrigin"
                ],
                "properties": {
                    "orderReference": {
                        "type": "string"
                    },
                    "orderOrigin": {
                        "type": "string"
                    },
                    "page": {
                        "type": "integer",
                        "default": 1,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "limit": {
                        "type": "integer",
                        "default": 20,
                        "maximum": 100,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    }
                },
                "type": "object"
            },
            "ParcelDeleteByOrderRequest": {
                "required": [
                    "orderReference",
                    "orderOrigin"
                ],
                "properties": {
                    "orderReference": {
                        "description": "The external order reference",
                        "type": "string",
                        "example": "ORD-12345"
                    },
                    "orderOrigin": {
                        "description": "The order origin channel",
                        "type": "string",
                        "example": "shopify"
                    }
                },
                "type": "object"
            },
            "ParcelUpdateRequest": {
                "properties": {
                    "weightKg": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "lengthCm": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "widthCm": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "heightCm": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "originCountryIso": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 2,
                        "minLength": 2
                    },
                    "contentsDescription": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "clientInternalCode": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "shippingNotes": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    }
                },
                "type": "object"
            },
            "SandboxRequest": {
                "required": [
                    "stringValue",
                    "intValue",
                    "boolValue",
                    "floatValue"
                ],
                "properties": {
                    "stringValue": {
                        "type": "string",
                        "minLength": 3
                    },
                    "intValue": {
                        "type": "integer"
                    },
                    "boolValue": {
                        "type": "boolean"
                    },
                    "floatValue": {
                        "type": "number",
                        "format": "float"
                    },
                    "dateTimeValue": {
                        "type": "string",
                        "pattern": "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "SandboxSearchRequest": {
                "required": [
                    "offset"
                ],
                "properties": {
                    "updatedAfter": {
                        "type": "string",
                        "nullable": true,
                        "default": null
                    },
                    "updatedBefore": {
                        "type": "string",
                        "nullable": true,
                        "default": null
                    },
                    "page": {
                        "type": "integer",
                        "default": 1,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "limit": {
                        "type": "integer",
                        "default": 20,
                        "maximum": 100,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "updatedAfterDateTime": {
                        "title": "Convert updatedAfter string to DateTimeImmutable.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updatedBeforeDateTime": {
                        "title": "Convert updatedBefore string to DateTimeImmutable.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "offset": {
                        "title": "Calculate SQL OFFSET from page number.",
                        "description": "Converts 1-indexed page number to 0-indexed database offset.\nFormula: (page - 1) * limit",
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "SandboxPatchRequest": {
                "properties": {
                    "stringValue": {
                        "type": "string",
                        "nullable": true,
                        "default": null,
                        "minLength": 3
                    },
                    "intValue": {
                        "type": "integer",
                        "nullable": true,
                        "default": null
                    },
                    "boolValue": {
                        "type": "boolean",
                        "nullable": true,
                        "default": null
                    },
                    "floatValue": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "default": null
                    },
                    "dateTimeValue": {
                        "type": "string",
                        "pattern": "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}",
                        "nullable": true,
                        "default": null
                    }
                },
                "type": "object"
            },
            "ShipmentBulkCreateRequest": {
                "description": "Bulk shipment creation request",
                "required": [
                    "shipments"
                ],
                "properties": {
                    "shipments": {
                        "description": "Shipments to create (1 to 100)",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentCreateRequest"
                        },
                        "default": [],
                        "maxItems": 100,
                        "minItems": 1
                    }
                },
                "type": "object"
            },
            "ShipmentSearchRequest": {
                "properties": {
                    "trackingNumber": {
                        "description": "Exact tracking number",
                        "type": "string",
                        "example": "1Z0V5V416840696736",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "orderReference": {
                        "description": "Exact order reference",
                        "type": "string",
                        "example": "ORD-2026-123",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom1": {
                        "description": "Exact custom attribute 1",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom2": {
                        "description": "Exact custom attribute 2",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "custom3": {
                        "description": "Exact custom attribute 3",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "shipDateFrom": {
                        "description": "Ship date from, inclusive (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-01",
                        "nullable": true
                    },
                    "shipDateTo": {
                        "description": "Ship date to, inclusive (YYYY-MM-DD)",
                        "type": "string",
                        "example": "2026-08-04",
                        "nullable": true
                    },
                    "status": {
                        "description": "Comma-separated list of tracking status values (see TrackingStatus)",
                        "type": "string",
                        "pattern": "\\d+(,\\d+)*",
                        "example": "3,4,99",
                        "nullable": true
                    },
                    "updatedAfter": {
                        "description": "Only shipments whose tracking status changed at or after this moment (YYYY-MM-DD HH:MM:SS). Shipments never updated are excluded.",
                        "type": "string",
                        "example": "2026-08-03 00:00:00",
                        "nullable": true
                    },
                    "page": {
                        "description": "Page number (1-based)",
                        "type": "integer",
                        "example": 1,
                        "default": 1,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "limit": {
                        "description": "Items per page (max 100)",
                        "type": "integer",
                        "example": 20,
                        "default": 20,
                        "maximum": 100,
                        "minimum": 0,
                        "exclusiveMinimum": true
                    },
                    "sortBy": {
                        "description": "Sort order",
                        "type": "string",
                        "example": "id_desc",
                        "default": "id_desc",
                        "enum": [
                            "id_desc",
                            "id_asc",
                            "shipDate_desc",
                            "shipDate_asc"
                        ]
                    }
                },
                "type": "object"
            },
            "ShipmentImportRequest": {
                "description": "Asynchronous shipment import request",
                "required": [
                    "shipments"
                ],
                "properties": {
                    "shipments": {
                        "description": "Shipments to import (1 to 5000)",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentCreateRequest"
                        },
                        "default": [],
                        "maxItems": 5000,
                        "minItems": 1
                    },
                    "webhookUrl": {
                        "description": "URL notified when the import completes",
                        "type": "string",
                        "example": "https://merchant.example.com/webhooks/qapla-import",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "TokenResponse": {
                "required": [
                    "token",
                    "scopes",
                    "token_type",
                    "expires_in",
                    "rate_limit",
                    "cache"
                ],
                "properties": {
                    "token": {
                        "description": "JWT Token",
                        "type": "string",
                        "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                    },
                    "scopes": {
                        "description": "List of granted scopes",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "token_type": {
                        "description": "Token type",
                        "type": "string",
                        "example": "Bearer"
                    },
                    "expires_in": {
                        "description": "Expiration time in seconds",
                        "type": "integer",
                        "example": 86400
                    },
                    "rate_limit": {
                        "description": "Rate limit granted to this channel: refill_rate is the number of tokens restored per minute, bucket_size the burst capacity. One request consumes one token.",
                        "properties": {
                            "refill_rate": {
                                "type": "integer",
                                "example": 150
                            },
                            "bucket_size": {
                                "type": "integer",
                                "example": 300
                            }
                        },
                        "type": "object",
                        "additionalProperties": {
                            "type": "integer"
                        }
                    },
                    "cache": {
                        "description": "Indicates if the token was retrieved from cache",
                        "type": "boolean",
                        "example": true
                    }
                },
                "type": "object"
            },
            "ParcelResponse": {
                "required": [
                    "parcelHash",
                    "parcelNumber",
                    "label",
                    "weightKg",
                    "createdAt"
                ],
                "properties": {
                    "parcelHash": {
                        "description": "Parcel hash",
                        "type": "string",
                        "example": "abc123def456"
                    },
                    "parcelNumber": {
                        "description": "Parcel number",
                        "type": "integer",
                        "example": 1
                    },
                    "label": {
                        "description": "Label URLs",
                        "type": "object",
                        "example": {
                            "pdf": "https://api.qapla.dev/labels/123.pdf",
                            "zpl": "https://api.qapla.dev/labels/123.zpl"
                        }
                    },
                    "originCountryIso": {
                        "description": "Origin country ISO code",
                        "type": "string",
                        "example": "IT",
                        "nullable": true
                    },
                    "clientInternalCode": {
                        "description": "Client internal code",
                        "type": "string",
                        "example": "INT-123",
                        "nullable": true
                    },
                    "weightKg": {
                        "description": "Weight in kg",
                        "type": "number",
                        "format": "float",
                        "example": 2.5
                    },
                    "lengthCm": {
                        "description": "Length in cm",
                        "type": "number",
                        "format": "float",
                        "example": 10,
                        "nullable": true
                    },
                    "widthCm": {
                        "description": "Width in cm",
                        "type": "number",
                        "format": "float",
                        "example": 10,
                        "nullable": true
                    },
                    "heightCm": {
                        "description": "Height in cm",
                        "type": "number",
                        "format": "float",
                        "example": 10,
                        "nullable": true
                    },
                    "contentsDescription": {
                        "description": "Contents description",
                        "type": "string",
                        "example": "Electronics",
                        "nullable": true
                    },
                    "shippingNotes": {
                        "description": "Shipping notes",
                        "type": "string",
                        "example": "Fragile",
                        "nullable": true
                    },
                    "createdAt": {
                        "description": "Creation timestamp",
                        "type": "string",
                        "format": "date-time"
                    },
                    "updatedAt": {
                        "description": "Last update timestamp",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "totalParcelCount": {
                        "description": "Total parcel count (for batch creation)",
                        "type": "integer",
                        "example": 1,
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ParcelPaginatedResponse": {
                "required": [
                    "items",
                    "total",
                    "page",
                    "limit",
                    "pages"
                ],
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ParcelResponse"
                        }
                    },
                    "total": {
                        "description": "Total number of items",
                        "type": "integer",
                        "example": 100
                    },
                    "page": {
                        "description": "Current page",
                        "type": "integer",
                        "example": 1
                    },
                    "limit": {
                        "description": "Items per page",
                        "type": "integer",
                        "example": 20
                    },
                    "pages": {
                        "description": "Total pages",
                        "type": "integer",
                        "example": 5
                    }
                },
                "type": "object"
            },
            "AsyncJobResponse": {
                "required": [
                    "jobId",
                    "status",
                    "statusUrl",
                    "hashes",
                    "totalParcels"
                ],
                "properties": {
                    "jobId": {
                        "description": "Job ID",
                        "type": "string",
                        "example": "job_12345"
                    },
                    "status": {
                        "description": "Job status",
                        "type": "string",
                        "example": "processing"
                    },
                    "statusUrl": {
                        "description": "Status URL",
                        "type": "string",
                        "example": "/jobs/job_12345"
                    },
                    "hashes": {
                        "description": "List of pre-generated parcel hashes",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "totalParcels": {
                        "description": "Total number of parcels",
                        "type": "integer",
                        "example": 10
                    }
                },
                "type": "object"
            },
            "CourierResponseDto": {
                "required": [
                    "code",
                    "name",
                    "country"
                ],
                "properties": {
                    "code": {
                        "description": "Courier Code",
                        "type": "string",
                        "example": "ARAMEX"
                    },
                    "name": {
                        "description": "Courier Name",
                        "type": "string",
                        "example": "Aramex"
                    },
                    "country": {
                        "description": "Country code or \"global\"",
                        "type": "string",
                        "example": "global"
                    },
                    "website": {
                        "description": "Official website",
                        "type": "string",
                        "example": "http://www.aramex.com",
                        "nullable": true
                    },
                    "trackingUrl": {
                        "description": "Public Tracking URL",
                        "type": "string",
                        "example": "https://www.aramex.com/track?id=[TRACKING_NUMBER]",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ShipmentBulkCreateResponse": {
                "description": "Bulk shipment creation response",
                "required": [
                    "summary",
                    "items",
                    "failures"
                ],
                "properties": {
                    "summary": {
                        "$ref": "#/components/schemas/ShipmentBatchSummary"
                    },
                    "items": {
                        "description": "Per-item outcomes, in request order",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ShipmentCreateResult"
                        }
                    },
                    "failures": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "ShipmentImportAcceptedResponse": {
                "description": "Accepted shipment import job",
                "required": [
                    "jobId",
                    "status",
                    "statusUrl",
                    "totalShipments"
                ],
                "properties": {
                    "jobId": {
                        "description": "Job id",
                        "type": "string",
                        "example": "a3f2c1d4e5b6978811223344556677aa"
                    },
                    "status": {
                        "description": "Job status",
                        "type": "string",
                        "example": "processing"
                    },
                    "statusUrl": {
                        "description": "Polling URL",
                        "type": "string",
                        "example": "/jobs/a3f2c1d4e5b6978811223344556677aa"
                    },
                    "totalShipments": {
                        "description": "Number of shipments queued",
                        "type": "integer",
                        "example": 2500
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "Bearer": {
                "type": "http",
                "bearerFormat": "JWT",
                "scheme": "bearer"
            }
        }
    },
    "security": [
        {
            "Bearer": []
        }
    ],
    "tags": [
        {
            "name": "Addresses",
            "description": "Postal address verification"
        },
        {
            "name": "Authentication",
            "description": "Authentication management"
        },
        {
            "name": "Couriers",
            "description": "Couriers operations"
        },
        {
            "name": "Jobs",
            "description": "Async background job status polling"
        },
        {
            "name": "Labels",
            "description": "Shipping label generation and confirmation"
        },
        {
            "name": "Orders",
            "description": "Orders management"
        },
        {
            "name": "Parcels",
            "description": "Parcels operations"
        },
        {
            "name": "Sandbox",
            "description": "Sandbox environment"
        },
        {
            "name": "Shipments",
            "description": "Shipment management"
        },
        {
            "name": "System",
            "description": "System health and diagnostics"
        }
    ]
}