{
  "openapi": "3.0.3",
  "info": {
    "title": "API Veolog",
    "version": "1.0.0",
    "description": "API servidor a servidor com as credenciais já existentes (alias, senha e token) da conta. Todas as operações exigem AMBOS os headers no mesmo pedido. Disponível para contas ativas com cadastro completo após a liberação global. Ambiente real; sem sandbox nem tarifa API adicional. Não compartilhar credenciais no frontend, URLs, tickets ou logs."
  },
  "servers": [
    {
      "url": "https://veolog.com.br",
      "description": "Produção — use a URL canônica da Veolog"
    }
  ],
  "security": [
    {
      "UserToken": [],
      "UserSecretKey": []
    }
  ],
  "paths": {
    "/api/v1/{alias}/quotes": {
      "parameters": [
        {
          "name": "alias",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,159}$"
          },
          "description": "Alias exibido nas credenciais existentes da conta."
        }
      ],
      "post": {
        "operationId": "createQuote",
        "summary": "Calcular fretes operacionais ou de checkout",
        "description": "Um volume por requisição. Não cria envio, etiqueta, reserva ou pagamento. Reutiliza os contratos e as condições do plano vigente; as cotações seguem o consumo já previsto no plano. Budget de transportadoras de até 8 segundos. Lista vazia sem falha é 200; falha remota total é 503; resultado parcial é 200 com partial=true.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              },
              "examples": {
                "operational": {
                  "$ref": "#/components/examples/OperationalQuote"
                },
                "checkout": {
                  "$ref": "#/components/examples/CheckoutQuote"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sucesso. Exemplos são ilustrativos, sem promessa de preço ou prazo.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "no-store"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                },
                "examples": {
                  "operational": {
                    "$ref": "#/components/examples/OperationalQuoteResponse"
                  },
                  "checkout": {
                    "$ref": "#/components/examples/CheckoutQuoteResponse"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição/JSON/HTTPS inválido.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credenciais incompletas, inválidas, misturadas, rotacionadas ou revogadas.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Conta inativa ou cadastro incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Rota/envio inexistente ou indisponível para esta conta.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método incorreto; consulte Allow.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Corpo maior que 262144 bytes.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A cotação exige Content-Type application/json.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Campos/filtros inválidos ou cadastro de remetente incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Limite excedido; respeite Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "API/autenticação/transportadora temporariamente indisponível; respeite Retry-After quando presente.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{alias}/shipments": {
      "parameters": [
        {
          "name": "alias",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,159}$"
          },
          "description": "Alias exibido nas credenciais existentes da conta."
        }
      ],
      "get": {
        "operationId": "listShipments",
        "summary": "Listar os envios visíveis da conta",
        "description": "Ordenação por ID decrescente. Sem rascunhos, envios excluídos ou anonimizados por privacidade. Filtros combinados com AND, comparação exata e sensível a maiúsculas/minúsculas.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 1024
            },
            "description": "Copie next_cursor sem interpretar. Preserve filtros e conta da consulta anterior."
          },
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "preparation",
                "transit",
                "completed"
              ]
            }
          },
          {
            "name": "situation",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "preparing",
                "ready_to_print",
                "preparing_label",
                "awaiting_carrier",
                "needs_correction",
                "awaiting_payment",
                "payment_required",
                "label_issue",
                "ready_to_post",
                "posting_expired",
                "cancellation_attention",
                "cancellation_requested",
                "in_transit",
                "awaiting_pickup",
                "delivery_not_completed",
                "delivery_suspended",
                "damaged",
                "delivered",
                "returned",
                "canceled"
              ]
            }
          },
          {
            "name": "tracking_code",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          },
          {
            "name": "source_system",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          },
          {
            "name": "source_ref",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sucesso. Exemplos são ilustrativos, sem promessa de preço ou prazo.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "no-store"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentListResponse"
                },
                "examples": {
                  "example": {
                    "$ref": "#/components/examples/ShipmentList"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição/JSON/HTTPS inválido.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credenciais incompletas, inválidas, misturadas, rotacionadas ou revogadas.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Conta inativa ou cadastro incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Rota/envio inexistente ou indisponível para esta conta.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método incorreto; consulte Allow.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Campos/filtros inválidos ou cadastro de remetente incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Limite excedido; respeite Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "API/autenticação/transportadora temporariamente indisponível; respeite Retry-After quando presente.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{alias}/shipments/{id}": {
      "parameters": [
        {
          "name": "alias",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,159}$"
          },
          "description": "Alias exibido nas credenciais existentes da conta."
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,18}$"
          },
          "description": "ID retornado pela lista de envios; tratar como string."
        }
      ],
      "get": {
        "operationId": "getShipment",
        "summary": "Consultar um envio da conta",
        "description": "Retorna dados operacionais e municípios/CEPs. Não retorna dados pessoais de remetente/destinatário nem documentos ou URLs de etiqueta.",
        "responses": {
          "200": {
            "description": "Sucesso. Exemplos são ilustrativos, sem promessa de preço ou prazo.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "no-store"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentResponse"
                },
                "examples": {
                  "example": {
                    "$ref": "#/components/examples/ShipmentDetail"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição/JSON/HTTPS inválido.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credenciais incompletas, inválidas, misturadas, rotacionadas ou revogadas.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Conta inativa ou cadastro incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Rota/envio inexistente ou indisponível para esta conta.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método incorreto; consulte Allow.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Limite excedido; respeite Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "API/autenticação/transportadora temporariamente indisponível; respeite Retry-After quando presente.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{alias}/shipments/{id}/tracking": {
      "parameters": [
        {
          "name": "alias",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,159}$"
          },
          "description": "Alias exibido nas credenciais existentes da conta."
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,18}$"
          },
          "description": "ID retornado pela lista de envios; tratar como string."
        }
      ],
      "get": {
        "operationId": "getTracking",
        "summary": "Consultar o histórico persistido da etiqueta atual",
        "description": "Leitura local, sem disparar consulta à transportadora. Eventos por data e ID decrescentes; sem rastreio disponível retorna events=[] e valores null. Paginação fica dentro de data.pagination. Histórico de etiquetas anteriores não é retornado.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 1024
            },
            "description": "Copie next_cursor sem interpretar. Preserve filtros e conta da consulta anterior."
          }
        ],
        "responses": {
          "200": {
            "description": "Sucesso. Exemplos são ilustrativos, sem promessa de preço ou prazo.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "no-store"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingResponse"
                },
                "examples": {
                  "example": {
                    "$ref": "#/components/examples/Tracking"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição/JSON/HTTPS inválido.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credenciais incompletas, inválidas, misturadas, rotacionadas ou revogadas.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Conta inativa ou cadastro incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Rota/envio inexistente ou indisponível para esta conta.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método incorreto; consulte Allow.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Identidade de rastreio mudou durante a leitura; refaça a consulta sem cursor.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Campos/filtros inválidos ou cadastro de remetente incompleto.",
            "headers": {},
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Limite excedido; respeite Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "API/autenticação/transportadora temporariamente indisponível; respeite Retry-After quando presente.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Segundos até uma nova tentativa; 503 pode omitir este header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "UserToken": {
        "type": "apiKey",
        "in": "header",
        "name": "User-Token",
        "description": "Token vit_ das credenciais de API existentes."
      },
      "UserSecretKey": {
        "type": "apiKey",
        "in": "header",
        "name": "User-Secret-Key",
        "description": "Senha API vps_; não é senha de login."
      }
    },
    "schemas": {
      "QuoteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "origin_zipcode",
          "dest_zipcode",
          "weight_g",
          "length_cm",
          "width_cm",
          "height_cm",
          "format",
          "declared_value_cents",
          "document_type"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "enum": [
              "operational",
              "checkout"
            ],
            "description": "operational retorna preço/prazo operacional; checkout também aplica as regras de frete da conta."
          },
          "origin_zipcode": {
            "type": "string",
            "pattern": "^[0-9]{8}$",
            "description": "CEP de origem com 8 dígitos; 00000000 não é aceito."
          },
          "dest_zipcode": {
            "type": "string",
            "pattern": "^[0-9]{8}$",
            "description": "CEP de destino com 8 dígitos; 00000000 não é aceito."
          },
          "weight_g": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000000000
          },
          "length_cm": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 10000
          },
          "width_cm": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 10000
          },
          "height_cm": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 10000
          },
          "format": {
            "type": "string",
            "enum": [
              "box",
              "envelope",
              "roll"
            ]
          },
          "declared_value_cents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 999999999,
            "description": "Valor em centavos de real; 1990 = R$ 19,90."
          },
          "document_type": {
            "type": "string",
            "enum": [
              "nfe",
              "content_declaration"
            ]
          },
          "extras": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "pattern": "^[a-zA-Z0-9_.-]+$"
            },
            "description": "Códigos de serviços adicionais. Omitir mantém os padrões da conta; [] remove os adicionais padrão nesta cotação."
          },
          "nfe_key": {
            "type": "string",
            "pattern": "^[0-9]{44}$",
            "description": "Opcional na cotação. Exige chave fiscal válida e document_type=nfe."
          },
          "carriers": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "string",
              "maxLength": 40,
              "pattern": "^[a-z0-9][a-z0-9_-]*$"
            },
            "description": "Slugs de transportadoras; omitir consulta as elegíveis da conta."
          },
          "checkout": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cart_total_cents",
              "product_skus"
            ],
            "properties": {
              "cart_total_cents": {
                "type": "integer",
                "minimum": 0,
                "maximum": 999999999,
                "description": "Valor em centavos de real; 1990 = R$ 19,90."
              },
              "product_skus": {
                "type": "array",
                "maxItems": 500,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                }
              },
              "coupon_code": {
                "type": "string",
                "maxLength": 100
              }
            }
          }
        },
        "oneOf": [
          {
            "properties": {
              "purpose": {
                "enum": [
                  "operational"
                ]
              }
            },
            "not": {
              "required": [
                "checkout"
              ]
            }
          },
          {
            "properties": {
              "purpose": {
                "enum": [
                  "checkout"
                ]
              }
            },
            "required": [
              "checkout"
            ]
          }
        ]
      },
      "Price": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount_cents",
          "delivery_days"
        ],
        "properties": {
          "amount_cents": {
            "type": "integer",
            "minimum": 0
          },
          "delivery_days": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Rate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rate_id",
          "carrier",
          "service",
          "contract_origin",
          "currency",
          "operational"
        ],
        "properties": {
          "rate_id": {
            "type": "string",
            "description": "Referência efêmera da resposta; não reserva preço nem autoriza emissão."
          },
          "carrier": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "slug",
              "name"
            ],
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "service": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "name"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "contract_origin": {
            "type": "string",
            "enum": [
              "veolog",
              "cliente"
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "BRL"
            ]
          },
          "operational": {
            "$ref": "#/components/schemas/Price"
          },
          "checkout": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "amount_cents",
              "delivery_days"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "amount_cents": {
                "type": "integer",
                "minimum": 0
              },
              "delivery_days": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      },
      "Warning": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "QuoteData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "rates",
          "warnings",
          "partial"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "enum": [
              "operational",
              "checkout"
            ]
          },
          "rates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rate"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Warning"
            }
          },
          "partial": {
            "type": "boolean",
            "description": "Há resultados incompletos por indisponibilidade/timeout de transportadora."
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "data"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/QuoteData"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "next_cursor",
          "has_more"
        ],
        "properties": {
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "Shipment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "code",
          "source",
          "carrier",
          "service",
          "stage",
          "situation",
          "tracking_code",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[1-9][0-9]*$"
          },
          "code": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "system",
              "reference"
            ],
            "properties": {
              "system": {
                "type": "string",
                "nullable": true
              },
              "reference": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "carrier": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "slug",
              "name"
            ],
            "properties": {
              "slug": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "service": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "name"
            ],
            "properties": {
              "code": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "stage": {
            "type": "string",
            "enum": [
              "preparation",
              "transit",
              "completed"
            ]
          },
          "situation": {
            "type": "string",
            "enum": [
              "preparing",
              "ready_to_print",
              "preparing_label",
              "awaiting_carrier",
              "needs_correction",
              "awaiting_payment",
              "payment_required",
              "label_issue",
              "ready_to_post",
              "posting_expired",
              "cancellation_attention",
              "cancellation_requested",
              "in_transit",
              "awaiting_pickup",
              "delivery_not_completed",
              "delivery_suspended",
              "damaged",
              "delivered",
              "returned",
              "canceled"
            ]
          },
          "tracking_code": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "Region": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "postal_code",
          "city",
          "state"
        ],
        "properties": {
          "postal_code": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Package": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "weight_g",
          "length_cm",
          "width_cm",
          "height_cm"
        ],
        "properties": {
          "weight_g": {
            "type": "number",
            "nullable": true
          },
          "length_cm": {
            "type": "number",
            "nullable": true
          },
          "width_cm": {
            "type": "number",
            "nullable": true
          },
          "height_cm": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "ShipmentDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "code",
          "source",
          "carrier",
          "service",
          "stage",
          "situation",
          "tracking_code",
          "created_at",
          "updated_at",
          "origin",
          "destination",
          "package"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[1-9][0-9]*$"
          },
          "code": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "system",
              "reference"
            ],
            "properties": {
              "system": {
                "type": "string",
                "nullable": true
              },
              "reference": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "carrier": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "slug",
              "name"
            ],
            "properties": {
              "slug": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "service": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "name"
            ],
            "properties": {
              "code": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "stage": {
            "type": "string",
            "enum": [
              "preparation",
              "transit",
              "completed"
            ]
          },
          "situation": {
            "type": "string",
            "enum": [
              "preparing",
              "ready_to_print",
              "preparing_label",
              "awaiting_carrier",
              "needs_correction",
              "awaiting_payment",
              "payment_required",
              "label_issue",
              "ready_to_post",
              "posting_expired",
              "cancellation_attention",
              "cancellation_requested",
              "in_transit",
              "awaiting_pickup",
              "delivery_not_completed",
              "delivery_suspended",
              "damaged",
              "delivered",
              "returned",
              "canceled"
            ]
          },
          "tracking_code": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "origin": {
            "$ref": "#/components/schemas/Region"
          },
          "destination": {
            "$ref": "#/components/schemas/Region"
          },
          "package": {
            "$ref": "#/components/schemas/Package"
          }
        }
      },
      "ShipmentListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "data",
          "pagination"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shipment"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "ShipmentResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "data"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/ShipmentDetail"
          }
        }
      },
      "TrackingEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "status",
          "description",
          "location",
          "event_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "in_transit",
              "delivered",
              "returned",
              "not_delivered",
              "delivery_suspended",
              "damaged",
              "canceled",
              null
            ]
          },
          "description": {
            "type": "string",
            "description": "Resumo padronizado da Veolog conforme status; nunca reproduz o texto livre da transportadora, que pode conter dados pessoais. Status desconhecido usa Atualização de rastreamento.",
            "example": "Em trânsito"
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "Município/UF quando identificável com segurança; caso contrário null."
          },
          "event_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "TrackingData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tracking_code",
          "status",
          "last_event_at",
          "events",
          "pagination"
        ],
        "properties": {
          "tracking_code": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "in_transit",
              "delivered",
              "returned",
              "not_delivered",
              "delivery_suspended",
              "damaged",
              "canceled",
              null
            ]
          },
          "last_event_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrackingEvent"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "TrackingResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "data"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/TrackingData"
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "error"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "examples": {
      "OperationalQuote": {
        "summary": "Cotação operacional — dados fictícios",
        "value": {
          "purpose": "operational",
          "origin_zipcode": "01310100",
          "dest_zipcode": "20040002",
          "weight_g": 1000,
          "length_cm": 20,
          "width_cm": 15,
          "height_cm": 10,
          "format": "box",
          "declared_value_cents": 15000,
          "document_type": "content_declaration"
        }
      },
      "CheckoutQuote": {
        "summary": "Cotação para checkout — dados fictícios",
        "value": {
          "purpose": "checkout",
          "origin_zipcode": "01310100",
          "dest_zipcode": "20040002",
          "weight_g": 1000,
          "length_cm": 20,
          "width_cm": 15,
          "height_cm": 10,
          "format": "box",
          "declared_value_cents": 15000,
          "document_type": "content_declaration",
          "checkout": {
            "cart_total_cents": 15000,
            "product_skus": [
              "CAMISETA-AZUL-M"
            ],
            "coupon_code": ""
          }
        }
      },
      "OperationalQuoteResponse": {
        "value": {
          "request_id": "f875e9ea022597f7c9267fe13f5134a07",
          "data": {
            "purpose": "operational",
            "rates": [
              {
                "rate_id": "rate_168e95b3a2f432cfa47c5b3ef512456c",
                "carrier": {
                  "slug": "correios",
                  "name": "Correios"
                },
                "service": {
                  "code": "03298",
                  "name": "PAC"
                },
                "contract_origin": "veolog",
                "currency": "BRL",
                "operational": {
                  "amount_cents": 1840,
                  "delivery_days": 5
                }
              }
            ],
            "warnings": [],
            "partial": false
          }
        }
      },
      "CheckoutQuoteResponse": {
        "value": {
          "request_id": "f875e9ea022597f7c9267fe13f5134a07",
          "data": {
            "purpose": "checkout",
            "rates": [
              {
                "rate_id": "rate_168e95b3a2f432cfa47c5b3ef512456c",
                "carrier": {
                  "slug": "correios",
                  "name": "Correios"
                },
                "service": {
                  "code": "03298",
                  "name": "PAC"
                },
                "contract_origin": "veolog",
                "currency": "BRL",
                "operational": {
                  "amount_cents": 1840,
                  "delivery_days": 5
                },
                "checkout": {
                  "name": "Entrega econômica",
                  "amount_cents": 1500,
                  "delivery_days": 6
                }
              }
            ],
            "warnings": [],
            "partial": false
          }
        }
      },
      "ShipmentList": {
        "value": {
          "request_id": "f875e9ea022597f7c9267fe13f5134a07",
          "data": [
            {
              "id": "12345",
              "code": "VEO12345",
              "source": {
                "system": "manual",
                "reference": null
              },
              "carrier": {
                "slug": "correios",
                "name": "Correios"
              },
              "service": {
                "code": "03298",
                "name": "PAC"
              },
              "stage": "transit",
              "situation": "in_transit",
              "tracking_code": "AA123456789BR",
              "created_at": "2026-10-08T09:00:00-03:00",
              "updated_at": "2026-10-08T12:00:00-03:00"
            }
          ],
          "pagination": {
            "next_cursor": null,
            "has_more": false
          }
        }
      },
      "ShipmentDetail": {
        "value": {
          "request_id": "f875e9ea022597f7c9267fe13f5134a07",
          "data": {
            "id": "12345",
            "code": "VEO12345",
            "source": {
              "system": "manual",
              "reference": null
            },
            "carrier": {
              "slug": "correios",
              "name": "Correios"
            },
            "service": {
              "code": "03298",
              "name": "PAC"
            },
            "stage": "transit",
            "situation": "in_transit",
            "tracking_code": "AA123456789BR",
            "created_at": "2026-10-08T09:00:00-03:00",
            "updated_at": "2026-10-08T12:00:00-03:00",
            "origin": {
              "postal_code": "01310100",
              "city": "São Paulo",
              "state": "SP"
            },
            "destination": {
              "postal_code": "20040002",
              "city": "Rio de Janeiro",
              "state": "RJ"
            },
            "package": {
              "weight_g": 1000,
              "length_cm": 20,
              "width_cm": 15,
              "height_cm": 10
            }
          }
        }
      },
      "Tracking": {
        "value": {
          "request_id": "f875e9ea022597f7c9267fe13f5134a07",
          "data": {
            "tracking_code": "AA123456789BR",
            "status": "in_transit",
            "last_event_at": "2026-10-08T12:00:00-03:00",
            "events": [
              {
                "id": "991",
                "status": "in_transit",
                "description": "Em trânsito",
                "location": "São Paulo/SP",
                "event_at": "2026-10-08T12:00:00-03:00"
              }
            ],
            "pagination": {
              "next_cursor": null,
              "has_more": false
            }
          }
        }
      }
    }
  }
}
