# 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.