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.

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:

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

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.

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

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.