---
title: "Alterar situação do lead"
method: PATCH
path: "/leads/{idLead}/situacao"
tags: ["Situação do Lead"]
---

# Alterar situação do lead

`PATCH /leads/{idLead}/situacao`

## Request

- Base URL: `https://integracao.cvcrm.com.br/api/v4/comercial`
- URL: `https://integracao.cvcrm.com.br/api/v4/comercial/leads/{idLead}/situacao`
- Auth: HTTP bearer

> 🔒 **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)](https://desenvolvedor.cvcrm.com.br/docs/como-autenticar-nas-apis-do-cv-crm-com-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.

## Path parameters

- `idLead` integer, required

## Request body

- object
  - `idSituacao` integer, required: Identificador da situação de destino, que precisa estar ativa no workflow de leads.
  - `idMotivoCancelamento` integer: Identificador do motivo de cancelamento, que precisa estar cadastrado e ativo (ver GET /api/v4/comercial/motivos-cancelamento-lead). Só aceito quando idSituacao é a situação de cancelamento, e obrigatório nesse caso. A API não cadastra motivos.
  - `idSubmotivoCancelamento` integer: Identificador do submotivo de cancelamento, que precisa estar cadastrado, ativo e vinculado ao motivo informado. A API não cadastra submotivos.
  - `descricaoMotivoCancelamento` string: Descrição livre do cancelamento. Obrigatória quando o motivo de cancelamento informado exige descrição.
  - `reativarLead` boolean: Quando false, impede a reativação de um lead cancelado (a chamada falha com 422 em vez de mover o lead para fora da situação de cancelamento).

## Response `200`

Situação do lead alterada

- object
  - `status` string
  - `code` integer
  - `data` object
    - `idLead` integer
    - `situacaoDe` SituacaoResumo, nullable: Situação do workflow de leads. `null` quando a situação não existe no workflow.
      - `id` integer
      - `nome` string, nullable
      - `corBg` string, nullable: Cor de fundo da situação em hexadecimal.
      - `corNome` string, nullable: Cor do nome da situação em hexadecimal.
    - `situacaoPara` SituacaoResumo, nullable: Situação do workflow de leads. `null` quando a situação não existe no workflow.
      - `id` integer
      - `nome` string, nullable
      - `corBg` string, nullable: Cor de fundo da situação em hexadecimal.
      - `corNome` string, nullable: Cor do nome da situação em hexadecimal.

## Other responses

- `400`: Payload malformado ou situação inválida: `idSituacao` ausente, não numérico ou menor que 1, `idMotivoCancelamento`/`idSubmotivoCancelamento` não numéricos ou menores que 1, ou `idSituacao` que não corresponde a uma situação ativa do workflow de leads.
- `401`: Token JWT ausente, expirado ou inválido no header Authorization.
- `403`: Usuário autenticado sem permissão para alterar a situação: no painel Gestor, perfil sem a permissão "Modificar situação" (`comercial|leads|3`); nos demais painéis, a situação atual do lead não libera a ação "Alterar situação" para o painel.
- `404`: Lead inexistente ou fora do escopo de visualização do usuário autenticado.
- `422`: Requisição bem formada, recusada por regra de negócio: transição fora da matriz do workflow, pré-requisito da transição não atendido, lead já na situação informada, campos de cancelamento enviados para uma situação não cancelada, motivo obrigatório ausente, motivo inexistente ou inativo, descrição/submotivo exigidos pelo motivo e não informados, submotivo inexistente ou de outro motivo, ou reativação bloqueada por `reativarLead: false`.
- `429`: Limite de requisições da API excedido — repita a chamada depois.
- `500`: Falha inesperada ao alterar a situação do lead.

---

[API](https://skmtc.dev/cvcrm/apis/situa-o-do-lead.md) - [All operations](https://skmtc.dev/cvcrm/apis/situa-o-do-lead/llms.txt) - [OpenAPI document](https://skmtc.dev/cvcrm/apis/situa-o-do-lead/revisions/3ebc3bdcf5f8?raw)