# Api Consulta Pedido

A API de Consulta de Pedido permite buscar os dados completos de um pedido pertencente à estrutura autorizada pelo token.

Use esta API para consultar:

- dados comerciais e financeiros do pedido;
- cliente associado, sem credenciais sensíveis;
- etapa atual, origem e consultor;
- itens do pedido e dados públicos do produto.

## Endereço

```
GET https://api.xeotech.com.br/api/v1/pedidos/{pedidoId}/{token}
```

O `pedidoId` é o identificador interno do pedido. O token é informado na URL e não deve ser enviado em cabeçalho ou payload.

Para localizar seu token no Xeotech, acesse a página [Meu token](https://ajuda.xeotech.com.br/books/apis-de-integracao/page/meu-token-para-proprietarios).

## Autorização e segurança

O token precisa pertencer a um usuário ativo. O usuário também precisa possuir um vínculo ativo com uma estrutura ativa.

A API obtém a estrutura diretamente do usuário autenticado. O cliente não envia `estruturaId`.

```
pedido.id = pedidoId
AND estrutura_usuario.estrutura_id = estruturaIdDoUsuario
```

Se o pedido não existir ou pertencer a outra estrutura, a API retorna `404`. Essa resposta evita revelar a existência de pedidos de outras estruturas.

## Payload

O GET não possui payload. Todos os dados necessários estão na URL:

<table id="bkmrk-parametros-consulta-pedido"><thead><tr class="header"><th>Parâmetro</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`pedidoId`</td><td>Sim</td><td>ID interno numérico do pedido.</td></tr><tr class="even"><td>`token`</td><td>Sim</td><td>Novo token de integração do usuário, informado na URL.</td></tr></tbody></table>

## Exemplo cURL

```
curl --fail-with-body --location \
  --request GET \
  'https://api.xeotech.com.br/api/v1/pedidos/123456/SEU_TOKEN' \
  --header 'Accept: application/json' \
  --output pedido-123456.json
```

## Retorno JSON

O retorno utiliza o formato `PedidoApiDTO`. A entidade JPA não é serializada diretamente.

```
{
  "id": 123456,
  "numero": "49565585",
  "pedidoTipo": "COMERCIAL",
  "tipoNegociacao": "NOVO",
  "dataCadastro": "2026-09-30",
  "dataHoraAtualizacao": "2026-09-30T14:32:10",
  "dataHoraUltimaMov": "2026-09-30T14:31:55",
  "total": 149.90,
  "compromissoMensal": 99.90,
  "nomeConsultorOperadora": "Consultor Exemplo",
  "numeroPedidoOrigem": null,
  "numeroPedidoVinculado": null,
  "numeroSimulacao": "SIM-10001",
  "complementos": null,
  "notasFiscais": null,
  "loginOperadora": null,
  "percentualTroca": null,
  "tags": "#PRIORIDADE",
  "clusterOrigem": null,
  "cotacao": null,
  "codigoPortabilidade": null,
  "observacaoProposta": null,
  "dataRetornoFuturo": null,
  "percentualDesconto": null,
  "observacao": null,
  "aparelhoCartaoCredito": false,
  "cliente": {
    "id": 9876,
    "cpfCnpj": "12345678000199",
    "nome": "Empresa Exemplo Ltda.",
    "cep": "89800000",
    "logradouro": "Rua Principal",
    "numero": "100",
    "complemento": null,
    "bairro": "Centro",
    "cidade": "Balneário Camboriú",
    "estado": "SC",
    "tags": null
  },
  "etapa": {
    "id": 44501,
    "nome": "ENVIADO BKO",
    "ativo": true,
    "sincronizavel": true,
    "editavel": false,
    "pedidoTipo": "COMERCIAL",
    "slaHoras": 0
  },
  "usuarioProprietario": {
    "id": 321,
    "nome": "Consultor Exemplo",
    "login": "consultor",
    "tags": "#PRIORIDADE,#VIP",
    "equipe": {
      "id": 12,
      "nome": "Equipe Comercial"
    },
    "ativo": true
  },
  "itens": [
    {  
      "id": 629534248,
      "numero": "47991370111",
      "quantidade": 1,
      "valorUnitario": 99.99,
      "dataReferencia": "2026-09-30",
      "dataPortabilidade": "2026-09-30",
      "dataInstalacao": "2026-09-30",
      "cepInstalacao": "88330484",
      "logradouroInstalacao": "R 1822",
      "numeroInstalacao": "400",
      "bairroInstalacao": "Centro",
      "complInstalacao": "sl 1901",
      "cidadeInstalacao": "Balneario Camboriu",
      "estadoInstalacao": "SC",
      "operadoraCedente": "TIM",
      "nomeCedente": "Sebastião Barbosa",
      "cpfCnpjCedente": "45935282917",
      "telefoneCedente": "47991917979",
      "emailCedente": "xeotechoficial@gmail.com",
      "produto": {
        "id": 18272,
        "nome": "iPHONE 18",
        "descricao": "iPHONE 18",
        "valor": 12319.00,
        "categoria": "APARELHO"
      }
    }      
  ]
}
```

## Campos do pedido

<table id="bkmrk-campos-pedido-consulta-tabela"><thead><tr class="header"><th>Grupo</th><th>Campos</th></tr></thead><tbody><tr class="odd"><td>Identificação</td><td>`id`, `numero`, `pedidoTipo`, `tipoNegociacao`, `numeroPedidoOrigem`, `numeroPedidoVinculado`, `numeroSimulacao`</td></tr><tr class="even"><td>Datas</td><td>`dataCadastro`, `dataHoraAtualizacao`, `dataHoraOperadora`, `dataHoraUltimaMov`, `dataRetornoFuturo`</td></tr><tr class="odd"><td>Valores</td><td>`total`, `compromissoMensal`, `valorFaturaOrigem`, `percentualTroca`, `percentualDesconto`</td></tr><tr class="even"><td>Operação</td><td>`nomeConsultorOperadora`, `loginOperadora`, `atividades`, `clusterOrigem`, `cotacao`, `codigoPortabilidade`, `leadSistema`</td></tr><tr class="odd"><td>Observações</td><td>`complementos`, `notasFiscais`, `observacao`, `observacaoProposta`, `tags`, `aparelhoCartaoCredito`, `revisao`</td></tr></tbody></table>

## Cliente, etapa e consultor

O objeto `cliente` retorna identificação e endereço comercial. Campos de senha, login de conta online e demais credenciais não fazem parte do retorno.

O objeto `etapa` informa somente `id`, `nome`, `ativo`, `sincronizavel`, `editavel`, `pedidoTipo` e `slaHoras`. O objeto `origem` informa a origem do pedido. O objeto `usuarioProprietario` informa o usuário proprietário, suas tags, equipe e o indicador `ativo` do vínculo com a estrutura.

## Itens e produtos

O campo `itens` retorna uma lista dos itens associados ao pedido. Os campos podem variar conforme o tipo de item, mas somente campos públicos e controlados são exportados, como:

- `id`, `numero`, `descricao`, `quantidade`;
- `valor`, `valorUnitario`, `codigo`, `nome`;
- `modelo`, `plano`, `tipo`;
- `dataReferencia`, `dataInstalacao` e dados do endereço de instalação;
- `dataPortabilidade`, `operadoraCedente`, `nomeCedente`, `cpfCnpjCedente`, `telefoneCedente` e `emailCedente`;
- objeto `produto` com `id`, `codigo`, `nome`, `descricao`, `modelo`, `tipo`, `valor`, `somaCompromissoMensal` e `categoria`.

## Limites e guard

O GET utiliza o mesmo guard da API de pedidos. Embora a consulta retorne somente um pedido, a autenticação e o controle de concorrência continuam protegidos.

<table id="bkmrk-limites-consulta-pedido"><thead><tr class="header"><th>Regra</th><th style="text-align: right;">Limite padrão</th></tr></thead><tbody><tr class="odd"><td>Execuções simultâneas globais</td><td style="text-align: right;">2</td></tr><tr class="even"><td>Execuções simultâneas por estrutura</td><td style="text-align: right;">1</td></tr><tr class="odd"><td>Intervalo mínimo após uma execução</td><td style="text-align: right;">120 segundos</td></tr><tr class="even"><td>Execuções por estrutura</td><td style="text-align: right;">3 a cada 10 minutos</td></tr><tr class="odd"><td>Tentativas por token</td><td style="text-align: right;">20 a cada 60 segundos</td></tr><tr class="even"><td>Tentativas globais</td><td style="text-align: right;">600 a cada 60 segundos</td></tr><tr class="odd"><td>Autenticações simultâneas</td><td style="text-align: right;">8</td></tr></tbody></table>

As tentativas recusadas também entram no controle. Quando um limite for atingido, a resposta será `429` com o header `Retry-After`.

## Respostas de erro

<table id="bkmrk-erros-consulta-pedido"><thead><tr class="header"><th style="text-align: right;">HTTP</th><th>Código</th><th>Situação</th></tr></thead><tbody><tr class="odd"><td style="text-align: right;">`401`</td><td>`TOKEN_INVALIDO`</td><td>Token inexistente, vazio ou inválido.</td></tr><tr class="even"><td style="text-align: right;">`403`</td><td>`ACESSO_NEGADO`</td><td>Usuário ou estrutura inativos.</td></tr><tr class="odd"><td style="text-align: right;">`404`</td><td>`PEDIDO_NAO_ENCONTRADO`</td><td>Pedido inexistente ou que não pertence à estrutura do token.</td></tr><tr class="even"><td style="text-align: right;">`429`</td><td>`LIMITE_API`</td><td>Guard ocupado, cooldown ou excesso de tentativas.</td></tr></tbody></table>

Exemplo de erro:

```
{
  "codigo": "PEDIDO_NAO_ENCONTRADO",
  "mensagem": "Pedido não encontrado para esta estrutura.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}
```

## Boas práticas

- Não registre o token completo em logs, código ou repositórios.
- Trate `404` como pedido inexistente ou não autorizado para a estrutura.
- Use o `id` do pedido como identificador da consulta local.
- Respeite o header `Retry-After` nas respostas `429`.
- Considere que campos sem valor podem retornar `null`.