Api Movimentação de Etapa de Atividade

A API de movimentação de etapa permite mover uma ou várias atividades para outra etapa do funil, respeitando as mesmas regras de segurança, permissões, hierarquia e histórico utilizadas no Xeotech.

Essa operação não altera diretamente o pedido sem controle. Ela executa o processo de movimentação, registra o histórico e valida as regras da atividade.

Endereço

POST https://api.xeotech.com.br/api/v1/pedidos/alterar-etapa/{token}

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

Autorização e estrutura

O token precisa pertencer a um usuário ativo, com vínculo ativo em uma estrutura ativa. A estrutura é obtida automaticamente pelo vínculo do usuário; não é possível informar estruturaId no payload.

A etapa de destino é localizada pelo Xeotech usando:

• estrutura do usuário do token;
• tipo do pedido informado;
• nome exato da etapa;
• origem padrão do pedido, atualmente 5;
• etapa ativa.

Payload

{
  "numerosAtividades": ["49565585", "49565586"],
  "pedidoTipo": "COMERCIAL",
  "nomeEtapa": "ATIVO"
}

Campo	Obrigatório	Descrição
numerosAtividades	Sim	Lista com 1 a 50 números de atividades. Envie os números como texto, mesmo quando forem numéricos. Não pode haver repetição.
pedidoTipo	Sim	Aceita COMERCIAL ou POS_VENDA.
nomeEtapa	Sim	Nome exato da etapa ativa cadastrada para o tipo de pedido e estrutura do token.

O payload aceita somente esses três campos. Campos desconhecidos, números vazios, duplicados ou acima de 50 atividades são rejeitados.

Header obrigatório

Idempotency-Key: alteracao-etapa-20261001-0001

A chave deve conter de 16 a 64 caracteres usando letras, números, hífen ou sublinhado.

Use a mesma chave somente para repetir exatamente a mesma operação. A chave é controlada por usuário, atividade e payload. Não reutilize uma chave para outra etapa ou outro pedido.

Regras de processamento

• Cada atividade é processada em uma transação independente.
• Uma falha em uma atividade não impede o processamento das demais.
• A atividade precisa pertencer à estrutura do token e ser acessível pela hierarquia do usuário.
• Se a etapa atual não estiver no Kanban do solicitante, é necessária a permissão MOVER_SEM_ESTAR_NO_KANBAN.
• Se a etapa de destino não estiver no Kanban do solicitante, é necessária a permissão MOVER_ATIVIDADE_FORA_KANBAN.
• Para sair de uma etapa não editável, é sempre necessária a permissão ATIVIDADE_MOVER_NAO_EDITAVEIS, mesmo que a etapa esteja no Kanban.
• Para entrar em uma etapa não editável fora do Kanban, também é necessária a permissão MOVER_ATIVIDADE_PARA_NAO_EDITAVEIS. Quando o destino está no Kanban, essa permissão específica é dispensada.
• Se a atividade já estiver na etapa informada, o resultado será SEM_ALTERACAO.
• A movimentação registra o status e o histórico da atividade.
• Se a etapa de destino atualizar a data de referência, os itens do pedido terão a data atualizada conforme a regra do sistema.
• Se houver formulário ativo vinculado à etapa atual, a API recusa a operação. Nesse caso, a movimentação deve ser feita pela tela do Xeotech.
• Negociações vinculadas podem ser movimentadas quando atendem às regras de sincronização, hierarquia, permissões e formulário. As mesmas validações de Kanban são aplicadas usando o tipo da negociação vinculada; se ela for recusada, a alteração do pedido principal também é revertida.

Permissões

Permissão	Quando é necessária
PAINEL_ATIVIDADE_ETAPA_CHANGE	Obrigatória em todas as chamadas, inclusive para uma única atividade. A permissão KANBAN_ETAPA_CHANGE sozinha não autoriza esta API.
ATIVIDADE_ALTERACAO_EM_LOTE	Obrigatória quando o payload contém mais de uma atividade.
ATIVIDADE_MOVER_NAO_EDITAVEIS	Necessária para sair de uma etapa não editável.
MOVER_ATIVIDADE_PARA_NAO_EDITAVEIS	Necessária para entrar em uma etapa não editável que não esteja no Kanban do solicitante.
MOVER_SEM_ESTAR_NO_KANBAN	Necessária quando a etapa atual da atividade não está no Kanban do solicitante.
MOVER_ATIVIDADE_FORA_KANBAN	Necessária quando a etapa de destino não está no Kanban do solicitante.
IGNORAR_HIERARQUIA	Permite ignorar a validação de hierarquia, conforme as regras do usuário.

As permissões de Kanban e de etapas não editáveis são cumulativas. Por exemplo, mover uma atividade de uma etapa não editável fora do Kanban para outro destino não editável fora do Kanban exige as quatro permissões específicas, além das permissões gerais da operação.

Exemplo cURL

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/alterar-etapa/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: alteracao-etapa-20261001-0001' \
  --data '{
    "numerosAtividades": ["49565585", "49565586"],
    "pedidoTipo": "COMERCIAL",
    "nomeEtapa": "ATIVO"
  }'

Retorno

A resposta informa o resultado individual de cada atividade. O HTTP 200 indica que o lote foi processado; verifique os campos sucessos, falhas e resultados.

{
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000",
  "total": 2,
  "sucessos": 1,
  "falhas": 1,
  "resultados": [
    {
      "numeroAtividade": "49565585",
      "pedidoId": 49565585,
      "sucesso": true,
      "codigo": "ETAPA_ALTERADA",
      "mensagem": "Etapa alterada com sucesso."
    },
    {
      "numeroAtividade": "49565586",
      "pedidoId": null,
      "sucesso": false,
      "codigo": "FORMULARIO_VINCULADO",
      "mensagem": "Esta atividade possui formulário vinculado à etapa atual. Realize a movimentação pela tela do sistema."
    }
  ]
}

Campo	Descrição
requestId	Identificador da requisição para rastreamento no suporte.
total	Total de atividades recebidas.
sucessos	Quantidade de atividades alteradas ou processadas sem erro.
falhas	Quantidade de atividades recusadas ou com erro.
numeroAtividade	Número enviado no payload.
pedidoId	ID interno do pedido, quando localizado.
sucesso	Indica se a atividade foi processada com sucesso.
codigo	Código estável do resultado, como ETAPA_ALTERADA, SEM_ALTERACAO ou FORMULARIO_VINCULADO.
mensagem	Descrição do resultado.

Limites e guard

A alteração de etapa reutiliza o pedidoApiGuard da API de pedidos. Os limites são aplicados antes da autenticação e durante o processamento.

Regra	Limite padrão
Execuções simultâneas globais	2
Execuções simultâneas por estrutura	1
Intervalo mínimo após 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
Tamanho máximo do payload	16 KiB
Atividades por requisição	50

Quando um limite for atingido, a API retorna 429 e informa o tempo de espera no header Retry-After. O guard em memória é controlado por instância da aplicação; a idempotência é garantida pelo banco de dados.

Principais erros

HTTP	Código	Situação
400	PAYLOAD_INVALIDO ou CHAVE_INVALIDA	Payload inválido ou ausência de uma chave de idempotência válida.
401	TOKEN_INVALIDO	Token inexistente ou inválido.
403	ACESSO_NEGADO ou SEM_PERMISSAO	Usuário, vínculo, estrutura ou permissão indisponível.
404	PEDIDO_NAO_ENCONTRADO	Atividade não encontrada na estrutura e no tipo informados.
409	IDEMPOTENCIA_CONFLITO ou NUMERO_AMBIGUO	Chave reutilizada com outro payload ou número não exclusivo.
413	PAYLOAD_GRANDE	Payload acima de 16 KiB.
422	ETAPA_INVALIDA ou FORMULARIO_VINCULADO	Etapa inexistente, ambígua, inativa ou bloqueada por formulário.
429	LIMITE_API	Guard ocupado, cooldown ou excesso de tentativas.

Falhas específicas de uma atividade são retornadas dentro de resultados, com HTTP 200 para o lote. Isso inclui ETAPA_ATUAL_FORA_KANBAN, ETAPA_DESTINO_FORA_KANBAN, SEM_PERMISSAO, FORMULARIO_VINCULADO e demais recusas da atividade. Os números HTTP da tabela representam as categorias de erro; não substituem a análise de cada resultado.

Boas práticas

• Envie números de atividade como texto para preservar compatibilidade com números antigos.
• Use uma chave de idempotência única para cada operação nova.
• Em caso de timeout, repita a requisição com a mesma chave e o mesmo payload.
• Analise o resultado de cada atividade, mesmo quando o HTTP for 200.
• Respeite o header Retry-After nas respostas 429.
• Não registre o token completo nos logs.