🔒

Autenticação necessária

Esta API utiliza Bearer Token no header Authorization.
Consulte o tutorial completo antes de fazer sua primeira chamada:
Como autenticar nas APIs do CV CRM (v3+ — Bearer Token)

Altera a situação do lead. Para cancelar, informe a situação de cancelamento do
workflow junto de idMotivoCancelamento (e, quando exigidos pelo motivo,
idSubmotivoCancelamento e descricaoMotivoCancelamento).

Disponível para os painéis Gestor, Imobiliária e Corretor. No painel Gestor exige a
permissão "Modificar situação" (comercial|leads|3) no perfil do usuário.

Transições permitidas

A situação de destino precisa estar ativa no workflow de leads e a transição
"situação atual → situação informada" precisa estar cadastrada e ativa no workflow
(Configurações > Workflow de leads). Transições fora dessa matriz são recusadas com
422 — a API não libera "pulo de etapa". Além da matriz, a própria situação atual do
lead define quais painéis podem alterar a situação (ação "Alterar situação" do
workflow, configurada por painel): se o painel autenticado não tiver essa ação
liberada na situação atual do lead, a chamada retorna 403.

Os pré-requisitos configurados na transição continuam valendo (ex.: "ter gestor
vinculado", "ter corretor vinculado", "ter próxima ação agendada"); quando não são
atendidos, a resposta é 422 com a mensagem do pré-requisito que faltou.

A situação marcada como "Início" no workflow segue as mesmas regras: é a situação em que
o lead nasce e só é alcançável por esta rota se existir uma transição ativa da situação
atual do lead para ela.

Cancelamento

idMotivoCancelamento, idSubmotivoCancelamento e descricaoMotivoCancelamento só são
aceitos quando a situação informada é a situação de cancelamento do workflow; enviá-los
para qualquer outra situação retorna 422.

Esta API não cadastra motivo nem submotivo de cancelamento — os dois são cadastros
pré-existentes, informados por id:

• idMotivoCancelamento é obrigatório no cancelamento e precisa ser um motivo já
  cadastrado, ativo no sistema e ativo no painel. Consulte os ids disponíveis em
  GET /api/v4/comercial/motivos-cancelamento-lead.
• idSubmotivoCancelamento é opcional e precisa ser um submotivo ativo do motivo
  informado — um submotivo de outro motivo é recusado com 422.
• descricaoMotivoCancelamento é obrigatória quando o motivo cadastrado exige descrição,
  e o motivo pode também exigir submotivo — nos dois casos a resposta é 422.

Reativação

Mover um lead que está na situação de cancelamento para uma situação não cancelada é uma
reativação. Envie reativarLead: false para bloqueá-la: nesse caso a chamada retorna
422 em vez de reativar o lead. O padrão é true (reativação permitida).

Efeitos colaterais

A alteração de situação é auditável (quem, quando, de/para, motivo) e dispara os mesmos
efeitos da tela do lead: histórico do lead, tempo de conversão, ações do workflow,
webhooks de alteração de situação, eventos de automação e integrações (RD Station e
SharpSpring).

Mudanças em relação à v1

• A alteração de situação e o cancelamento saem do endpoint monolítico
  POST /api/v1/comercial/leads (que salva o lead inteiro) para esta rota dedicada.
• As transições passam a ser sempre validadas contra a matriz do workflow e contra a
  permissão por painel da situação atual — na v1 a verificação era opcional
  (verificar_relacionamento).
• O motivo de cancelamento passa a ser sempre informado por id (idMotivoCancelamento).
  A v1 aceitava motivo_cancelamento por nome e cadastrava um motivo novo quando o
  nome não existia; a v4 não cria cadastros secundários e recusa id inexistente com
  422.