Api de Movimentação de Pedidos

A API de Movimentação de Pedidos permite consultar o histórico de movimentações dos pedidos de uma estrutura autorizada.

Use a API para:

buscar movimentações de pedidos em um período;
filtrar por tipo de pedido: COMERCIAL ou POS_VENDA;
consultar todos os pedidos da estrutura ou somente uma lista de pedidos;
receber os dados em JSON ou CSV.

Endereço

POST https://api.xeotech.com.br/api/v1/pedidos/movimentacao/{token}

O token é informado na URL. Não envie o token dentro do payload.

Para localizar seu token no Xeotech, acesse a página Meu token.

Autorização

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 estrutura usada na consulta é obtida pelo vínculo do usuário autenticado. O cliente não informa estruturaId no payload.

A consulta sempre aplica a estrutura do usuário:

eu.estrutura_id = estruturaIdDoUsuario

Mesmo que sejam enviados IDs de pedidos de outra estrutura, eles não serão retornados.

Payload

{
  "dataHoraInicio": "2026-09-30 09:00:00",
  "dataHoraFim": "2026-09-30 10:00:00",
  "pedidoTipo": "COMERCIAL",
  "pedidoIds": [1001, 1002],
  "formato": "json"
}

Campo	Obrigatório	Descrição
`dataHoraInicio`	Sim	Início do período no formato `yyyy-MM-dd HH:mm:ss`.
`dataHoraFim`	Sim	Fim do período no formato `yyyy-MM-dd HH:mm:ss`. Deve ser posterior ao início.
`pedidoTipo`	Sim	Aceita `COMERCIAL` ou `POS_VENDA`.
`pedidoIds`	Não	Lista de IDs de pedidos. Quando omitida ou vazia, consulta todos os pedidos da estrutura. Limite de 10.000 IDs.
`formato`	Não	Aceita `json` ou `csv`. O padrão é `json`.

Regras dos filtros

Payload	Resultado
Período + `pedidoTipo`	Todas as movimentações do período para o tipo informado, dentro da estrutura do usuário.
Período + `pedidoTipo` + `pedidoIds`	Somente as movimentações do período dos pedidos informados e pertencentes à estrutura do usuário.

O início do período é inclusivo e o fim é exclusivo:

pedido.data_hora_atualizacao >= dataHoraInicio
pedido.data_hora_atualizacao < dataHoraFim

As datas usam o fuso America/Sao_Paulo.

Exemplos cURL

JSON — todos os pedidos do período

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/movimentacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output movimentacoes-pedidos.json \
  --data '{
    "dataHoraInicio": "2026-09-30 09:00:00",
    "dataHoraFim": "2026-09-30 10:00:00",
    "pedidoTipo": "COMERCIAL",
    "formato": "json"
  }'

JSON — somente pedidos selecionados

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/movimentacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output movimentacoes-pedidos.json \
  --data '{
    "dataHoraInicio": "2026-09-30 09:00:00",
    "dataHoraFim": "2026-09-30 10:00:00",
    "pedidoTipo": "POS_VENDA",
    "pedidoIds": [1001, 1002, 1003],
    "formato": "json"
  }'

CSV

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/movimentacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output movimentacoes-pedidos.csv \
  --data '{
    "dataHoraInicio": "2026-09-30 09:00:00",
    "dataHoraFim": "2026-09-30 10:00:00",
    "pedidoTipo": "COMERCIAL",
    "pedidoIds": [1001, 1002],
    "formato": "csv"
  }'

Retorno JSON

{
  "meta": {
    "versao": "v1",
    "operacao": "movimentacao",
    "fusoHorario": "America/Sao_Paulo",
    "recebidoEm": "2026-09-30T10:00:00",
    "dataHoraInicio": "2026-09-30T09:00:00",
    "dataHoraFim": "2026-09-30T10:00:00",
    "pedidoTipo": "COMERCIAL",
    "pedidoIdsInformados": [1001, 1002]
  },
  "dados": [
    {
      "id": "123456789",
      "pedidoId": 1001,
      "euEntrouId": 20,
      "euSaiuId": 21,
      "etapaId": 8,
      "cpfCnpjCliente": "12345678000199",
      "nomeCliente": "Empresa Exemplo Ltda.",
      "numeroAtividade": "PED-1001",
      "nomeEtapa": "Em análise",
      "usuarioEntrou": "Usuário Entrada",
      "usuarioSaiu": "Usuário Saída",
      "dataHoraEntrou": "2026-09-30T09:10:00",
      "dataHoraSaiu": "2026-09-30T09:45:00",
      "tempo": "00:35:00",
      "slaHoras": 24,
      "tagsAtividade": "#PRIORIDADE,#CLIENTE",
      "movimentacao": "Avanço de etapa",
      "nomeConsultor": "Consultor Exemplo",
      "total": 149.90,
      "compromissoMensal": 99.90,
      "pedidoTipo": "COMERCIAL",
      "controlaBko": true
    }
  ],
  "totalRegistros": 1
}

O objeto dados utiliza os 22 campos do PedidoStatusDTO. Campos sem valor podem retornar null.

Campo	Descrição
`id`	Identificador gerado para a linha retornada.
`pedidoId`	ID do pedido.
`euEntrouId` / `euSaiuId`	IDs dos vínculos de estrutura dos usuários que entraram e saíram.
`etapaId` / `nomeEtapa`	Etapa relacionada à movimentação.
`cpfCnpjCliente` / `nomeCliente`	Identificação do cliente.
`numeroAtividade`	Número da atividade/pedido.
`usuarioEntrou` / `usuarioSaiu`	Usuários associados à entrada e à saída.
`dataHoraEntrou` / `dataHoraSaiu`	Datas e horas da movimentação.
`tempo` / `slaHoras`	Tempo calculado e SLA da etapa.
`tagsAtividade` / `movimentacao`	Tags e descrição da movimentação.
`nomeConsultor`	Consultor associado ao pedido.
`total` / `compromissoMensal`	Valores financeiros do pedido.
`pedidoTipo` / `controlaBko`	Tipo de pedido e indicador de controle BKO.

O campo id retornado pela consulta não deve ser usado como chave permanente de upsert. Para uma cópia local, use uma chave composta com os campos de negócio necessários, como pedidoId, etapaId, dataHoraEntrou, dataHoraSaiu e movimentacao.

Retorno CSV

O CSV usa UTF-8 com BOM, separador ;, cabeçalho e quebra de linha CRLF.

id;pedidoId;euEntrouId;euSaiuId;etapaId;cpfCnpjCliente;nomeCliente;numeroAtividade;nomeEtapa;usuarioEntrou;usuarioSaiu;dataHoraEntrou;dataHoraSaiu;tempo;slaHoras;tagsAtividade;movimentacao;nomeConsultor;total;compromissoMensal;pedidoTipo;controlaBko

Datas e horas seguem o formato ISO no JSON e são gravadas como texto no CSV. Valores nulos geram células vazias.

Limites e guard

A API de movimentação utiliza os mesmos limites da API de produção, com guard próprio para os pedidos:

Regra	Limite padrão
Execuções simultâneas globais	2
Execuções simultâneas por estrutura	1
Intervalo mínimo após uma execução	120 segundos
Execuções por estrutura	3 a cada 10 minutos
Tentativas por token	20 a cada 60 segundos
Tentativas globais	600 a cada 60 segundos
Autenticações simultâneas	8
Registros por resposta	1.000.000
Tamanho máximo do payload	16 KiB
IDs no campo `pedidoIds`	10.000

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

HTTP	Código	Situação
`400`	`PAYLOAD_INVALIDO`	Campo ausente, data inválida, lista inválida ou tipo de pedido incorreto.
`401`	`TOKEN_INVALIDO`	Token inexistente ou inválido.
`403`	`ACESSO_NEGADO`	Usuário ou estrutura inativos.
`413`	`PAYLOAD_GRANDE`	Payload acima de 16 KiB.
`422`	`LIMITE_REGISTROS`	Resultado acima de 1.000.000 de movimentações.
`429`	`LIMITE_API`	Guard ocupado, cooldown ou excesso de tentativas.

Exemplo:

{
  "codigo": "LIMITE_API",
  "mensagem": "Aguarde entre exportações da API.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}

Boas práticas

Use intervalos consecutivos sem sobreposição quando a consulta for controlada pelo período.
Use JSON quando a integração precisar preservar tipos e datas.
Use CSV para planilhas e ferramentas de análise.
Respeite o header Retry-After em respostas 429.
Não registre o token completo em logs.
Não use o campo id da resposta como identificador permanente.

Api de Carga da Produção

Api do Relatório de exportação

Api de Movimentação de Pedidos

Api Consulta Pedido

Api Movimentação de Etapa de Atividade

Api de Movimentação de Pedidos

Endereço

Autorização

Payload

Regras dos filtros

Exemplos cURL

JSON — todos os pedidos do período

JSON — somente pedidos selecionados

CSV

Retorno JSON

Retorno CSV

Limites e guard

Respostas de erro

Boas práticas