---
title: "Registrar conversão do lead"
method: POST
path: "/leads/{idLead}/conversoes"
tags: ["Conversões do Lead"]
---

# Registrar conversão do lead

`POST /leads/{idLead}/conversoes`

## Request

- Base URL: `https://integracao.cvcrm.com.br/api/v4/comercial`
- URL: `https://integracao.cvcrm.com.br/api/v4/comercial/leads/{idLead}/conversoes`
- 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)

Registra uma conversão para o lead e aplica os efeitos descritos na introdução
(última conversão, bolsão, integração, fila, notificação e RD Station).

Disponível para os painéis Gestor, Imobiliária e Corretor. Exige a permissão
`comercial|leads|2` no perfil do usuário.

## Path parameters

- `idLead` integer, required

## Request body

- RegistrarLeadConversaoRequest
  - `conversao` string, required: Nome da conversão (ex.: nome da landing page ou campanha). Criado no cadastro de conversões se ainda não existir.
  - `origem` string: Código de origem da conversão cadastrado no CV. Omitido usa o painel autenticado; não cadastrado vira `ND`.
  - `integracao` 'RD' | 'SS' | 'FB': Integração de marketing de onde veio a conversão: `RD` RD Station, `SS` SharpSpring, `FB` Facebook.
  - `idIntegracao` string: Identificador do lead na base da integração. Aceita texto ou número e é gravado como texto. Tamanho máximo: 45 caracteres com `FB`, 80 com `RD`, 100 com `SS` ou sem integração; acima disso retorna `400`.
  - `idFormulario` integer: Identificador do formulário do Facebook **cadastrado no CV** (o mesmo `idformulario` da integração Facebook do CV, não o id do formulário na Meta). Só é aceito com `integracao = FB`; caso contrário retorna `422`.
  - `idMidia` integer: Identificador da mídia da conversão.
  - `idEmpreendimentos` integer[]: Empreendimentos de interesse associados à conversão.
  - `dataCadConversao` string: Data da conversão em ISO, `YYYY-MM-DD` ou `YYYY-MM-DD HH:MM:SS`. Só a data grava `00:00:00`; omitida usa a data e hora do registro.

## Response `201`

Conversão registrada. `idConversao` é o identificador do registro no histórico de conversões do lead.

- object
  - `status` string
  - `code` integer
  - `data` object
    - `idConversao` integer

## Other responses

- `400`: Corpo inválido: `conversao` ausente ou vazio após a normalização, `idMidia` não inteiro, `idFormulario` não inteiro, `idIntegracao` acima do tamanho máximo da integração, `idEmpreendimentos` que não é lista de inteiros, ou campos de texto com tipo incorreto.
- `401`: Token ausente, inválido ou expirado, ou painel não autorizado para esta rota.
- `403`: O perfil do usuário não tem a permissão `comercial|leads|2`.
- `404`: Lead inexistente, inativo ou fora do escopo do painel autenticado (Corretor e Imobiliária só acessam os leads que atendem).
- `409`: A mesma conversão (nome, mídia e origem) já foi registrada para o lead há menos de 5 minutos. Nada foi gravado.
- `422`: Requisição bem formada, recusada por regra de negócio: `dataCadConversao` fora do padrão ISO ou com data inexistente, `integracao` fora de `RD`/`SS`/`FB`, ou `idFormulario` enviado sem `integracao = FB`.
- `429`: Limite de requisições da API excedido. Repita a chamada depois.
- `500`: Falha inesperada ao registrar a conversão. Nada é gravado (a operação é transacional).

---

[API](https://skmtc.dev/cvcrm/apis/convers-es-do-lead.md) - [All operations](https://skmtc.dev/cvcrm/apis/convers-es-do-lead/llms.txt) - [OpenAPI document](https://skmtc.dev/cvcrm/apis/convers-es-do-lead/revisions/c430d729ba8f?raw)