# Referência da API de Integração

URL base: `https://api.external.leaper.com.br`. Toda requisição precisa do cabeçalho `X-API-Key`. Autenticação, formatos, erros e casos de uso estão no [guia](https://leaper.com.br/desenvolvedores/guia/).

## Mensagens

Registre as mensagens de WhatsApp trocadas fora da Leaper.

### Registrar mensagem

`POST /v1/message`

Registra uma mensagem de WhatsApp na conversa do lead. A Leaper procura o lead pelo `phone` ou pelo `lid`:
se ele existir, a mensagem entra na conversa dele; se não existir, o lead é criado no primeiro status do funil.

- O telefone é comparado só pelos dígitos: `+55 (11) 98765-4321` e `5511987654321` são o mesmo contato. Envie sempre com DDI.
- Com `phone` e `lid`, vale o lead que tiver qualquer um dos dois. Se o lead foi encontrado pelo telefone e ainda não tinha LID, o `lid` enviado é salvo.
- Sem `message`, nada é gravado na conversa, mas o lead continua sendo encontrado ou criado.
- Reenviar a mesma mensagem com o mesmo `message_id` não a duplica na conversa.
- Um lead que veio de formulário passa a aparecer como contatado pelo WhatsApp.

**Mensagens da empresa (`from_me: true`)**: para um contato que ainda não é lead, o lead só é criado se a opção
**Criar lead ao iniciar conversa** estiver ligada nas configurações da empresa. Com ela desligada, a resposta é `200`
com `{ "lead": null }` e nada é gravado. Leads criados por mensagem da empresa ficam com origem `NO_TRACKING`.

**Origem do lead**: quando a mensagem de um contato cria o lead, os parâmetros de rastreamento definem o `source`:

| Parâmetro enviado | `source` |
|---|---|
| `ctwa_clid` | `METAADS_MSG` |
| `fbclid` | `METAADS_SITE` |
| `gclid`, `wbraid` ou `gbraid` | `GOOGLE_SITE` |
| `utm.source` com `google` | `GOOGLE_ORGANIC` |
| `utm.source` com `facebook` ou `meta` | `FACEBOOK_ORGANIC` |
| `utm.source` com `instagram` | `INSTAGRAM_ORGANIC` |
| `utm.source` com `tiktok` | `TIKTOK_ORGANIC` |
| `utm.source` com `youtube` | `YOUTUBE_ORGANIC` |
| Outro `utm.source` | `OTHER_ORGANIC` |
| Nenhum | `NO_TRACKING` |

Se o lead já existe, a origem dele não muda.

**Corpo da requisição** (JSON)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `phone` | texto ou inteiro | Sim, sem `lid` | Telefone do contato com DDI. Só os dígitos contam, e precisam ser de 8 a 15. |
| `lid` | texto | Sim, sem `phone` | Identificador do contato no WhatsApp (LID), no formato `123456789@lid`. |
| `name` | texto | Não | Nome do contato. Usado ao criar o lead. |
| `message` | texto | Não | Texto da mensagem. |
| `from_me` | booleano | Não | `true` quando a mensagem foi enviada pela empresa. Padrão: `false`. |
| `message_id` | texto | Não | Identificador da mensagem no seu sistema ou provedor de WhatsApp. Evita duplicar a mensagem quando a chamada é repetida. Até 255 caracteres. |
| `timestamp` | texto (data e hora) | Não | Data e hora da mensagem em ISO 8601, com fuso (`2026-09-11T10:30:00-03:00` ou `2026-09-11T13:30:00Z`). Sem ele, vale o horário do recebimento. |
| `ctwa_clid` | texto | Não | Identificador do clique em anúncio de clique para o WhatsApp (Meta Ads). |
| `fbclid` | texto | Não | Identificador do clique em anúncio do Meta Ads que levou a um site. |
| `gclid` | texto | Não | Identificador do clique no Google Ads. |
| `wbraid` | texto | Não | Identificador de clique do Google Ads em navegação web (iOS). |
| `gbraid` | texto | Não | Identificador de clique do Google Ads em aplicativos (iOS). |
| `utm` | objeto | Não | Parâmetros UTM do acesso. Também aceitos soltos no corpo, como `utm_source` e `utm_medium`. |
| `utm.source` | texto | Não |  |
| `utm.medium` | texto | Não |  |
| `utm.campaign` | texto | Não |  |
| `utm.term` | texto | Não |  |
| `utm.content` | texto | Não |  |

**Respostas**

| Código | Descrição |
|---|---|
| `201` | O lead foi criado e a mensagem, registrada. Corpo: [Resultado de mensagem](https://leaper.com.br/desenvolvedores/api/#resultado-de-mensagem). |
| `200` | O lead já existia e a mensagem foi registrada. Também é a resposta, com `lead: null`, quando a mensagem da empresa é ignorada. Corpo: [Resultado de mensagem](https://leaper.com.br/desenvolvedores/api/#resultado-de-mensagem). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `422` | A empresa não tem status no funil para receber o lead. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl -X POST "https://api.external.leaper.com.br/v1/message" \
  -H "X-API-Key: $LEAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511987654321",
    "name": "Marina Alves",
    "message": "Olá, quero agendar uma avaliação",
    "message_id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA",
    "timestamp": "2026-09-11T10:30:00-03:00",
    "ctwa_clid": "ARAkLgdbrocNABYQnQoGHmFy"
  }'
```

**Resposta `201`**

```json
{
  "lead": {
    "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84"
  }
}
```

**Resposta `200`** — Lead existente

```json
{
  "lead": {
    "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84"
  }
}
```

**Resposta `200`** — Mensagem ignorada

```json
{
  "lead": null
}
```

## Leads

Crie, atualize, liste e consulte leads.

### Listar leads

`GET /v1/leads`

Lista os leads da empresa, dos mais recentes para os mais antigos, com paginação por `limit` e `offset`.
Os filtros podem ser combinados. Cada item traz os blocos `lead` e `status`; `tracking` e `form_submissions` vêm só com `include`.

**Parâmetros de consulta**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `search` | texto | Não | Busca por parte do nome, do e-mail ou do telefone. |
| `status_id` | texto (uuid) | Não | `id` do status, de [Listar status do funil](https://leaper.com.br/desenvolvedores/api/#listar-status-do-funil). Não pode ser usado junto com `status`. |
| `status` | texto | Não | `code` do status, como `NEGOCIACAO`. Prefira `status_id`: o `code` muda quando o status é renomeado. |
| `source` | texto | Não | Origem do lead (veja [Origem do lead](https://leaper.com.br/desenvolvedores/api/#origem-do-lead)). Aceita também `META_ADS` e `GOOGLE_ADS`, que reúnem as origens pagas de cada plataforma. |
| `tag` | texto | Não | Leads com uma tag que contenha o texto informado. |
| `start_date` | texto | Não | Início do período, em `YYYY-MM-DD` ou `YYYY-MM-DD HH:MM:SS`, no horário de Brasília. Só a data vale a partir de 00:00:00. |
| `end_date` | texto | Não | Fim do período, no mesmo formato. Só a data vale até 23:59:59. |
| `date_field` | texto | Não | Data usada por `start_date` e `end_date`: `created_at` (entrada do lead) ou `status_changed_at` (última mudança de status). Valores: `created_at`, `status_changed_at`. Padrão: `created_at`. |
| `include` | texto | Não | Blocos opcionais, separados por vírgula: `tracking` e `form_submissions`. São os mesmos blocos de [Consultar lead](https://leaper.com.br/desenvolvedores/api/#consultar-lead). Com `include`, `limit` vale no máximo 50. Valores: `tracking`, `form_submissions`, `tracking,form_submissions`. |
| `limit` | inteiro | Não | Itens por página. No máximo 50 quando `include` é usado. Padrão: `50`. De 1 a 200. |
| `offset` | inteiro | Não | Quantos itens pular. Padrão: `0`. Mínimo: 0. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Página de leads. Corpo: [Lista de leads](https://leaper.com.br/desenvolvedores/api/#lista-de-leads). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/leads?status_id=5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21&start_date=2026-09-01&include=tracking&limit=50" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "data": [
    {
      "lead": {
        "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84",
        "name": "Marina Alves",
        "phone": "5511987654321",
        "email": "marina.alves@exemplo.com.br",
        "address": null,
        "custom_fields": [],
        "source": "METAADS_MSG",
        "tags": "prioridade-alta",
        "created_at": "2026-09-02T09:14:50-03:00",
        "updated_at": "2026-09-02T15:41:05-03:00",
        "created_from": "external_api",
        "lead_value": "3200"
      },
      "status": {
        "current": {
          "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
          "code": "NEGOCIACAO",
          "name": "Negociação",
          "changed_at": "2026-09-02T15:41:05-03:00"
        },
        "previous": {
          "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
          "code": "PROPOSTA",
          "name": "Proposta Enviada",
          "changed_at": "2026-09-02T11:22:18-03:00"
        }
      }
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}
```

### Criar lead

`POST /v1/leads`

Cria um lead no primeiro status do funil. Se a empresa tiver webhooks do evento **Novo Lead**, eles são disparados.

> [!NOTE]
> Esta rota sempre cria um lead novo, mesmo que já exista um lead com o mesmo telefone.
> Para alterar um lead existente, use [Atualizar lead](https://leaper.com.br/desenvolvedores/api/#atualizar-lead). Para mensagens de WhatsApp,
> [Registrar mensagem](https://leaper.com.br/desenvolvedores/api/#registrar-mensagem) já encontra o lead pelo telefone.

**Corpo da requisição** (JSON)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `source` | texto | Sim | Origem do lead. `TRACKING_LOST` não é aceito. |
| `client` | objeto | Sim | Dados do contato. |
| `client.name` | texto | Não | Nome. |
| `client.phone` | texto | Não | Telefone. Envie só dígitos, com DDI, como `5511987654321`. |
| `client.lid` | texto | Não | Identificador do contato no WhatsApp (LID), no formato `123456789@lid`. |
| `client.email` | texto | Não | E-mail. |
| `client.address` | texto | Não | Endereço. |
| `client.custom_fields` | lista de objetos | Não | Campos personalizados. |
| `client.custom_fields[].key` | texto | Sim | Nome do campo. |
| `client.custom_fields[].value` | texto ou número | Sim | Valor do campo. Números são gravados como texto. |
| `lead_value` | texto ou número | Não | Valor do lead, com ponto como separador decimal e sem separador de milhar, como `1500.50`. `1.500,00` é recusado e `1.500` é lido como 1,5. O prefixo `R$` é aceito. |
| `created_from` | texto | Não | Canal de entrada do lead. É o canal mostrado no painel e o que os gatilhos de conversão configurados por canal consideram. Valores: `external_api`, `whatsapp`, `forms`. Padrão: `external_api`. |
| `tags` | texto | Não | Tags do lead. |

**Respostas**

| Código | Descrição |
|---|---|
| `201` | Lead criado. Corpo: [Recurso lead](https://leaper.com.br/desenvolvedores/api/#recurso-lead). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `422` | A empresa não tem status no funil para receber o lead. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl -X POST "https://api.external.leaper.com.br/v1/leads" \
  -H "X-API-Key: $LEAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "WEBSITE",
    "client": {
      "name": "Marina Alves",
      "phone": "5511987654321",
      "email": "marina.alves@exemplo.com.br",
      "custom_fields": [
        {
          "key": "Interesse",
          "value": "Clareamento"
        }
      ]
    },
    "lead_value": "3200",
    "tags": "prioridade-alta"
  }'
```

**Resposta `201`** — Lead

```json
{
  "lead": {
    "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84",
    "name": "Marina Alves",
    "phone": "5511987654321",
    "email": "marina.alves@exemplo.com.br",
    "address": null,
    "custom_fields": [
      {
        "key": "Interesse",
        "value": "Clareamento"
      }
    ],
    "source": "METAADS_MSG",
    "tags": "prioridade-alta",
    "created_at": "2026-09-02T09:14:50-03:00",
    "updated_at": "2026-09-02T15:41:05-03:00",
    "created_from": "external_api",
    "lead_value": "3200"
  },
  "status": {
    "current": {
      "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
      "code": "NEGOCIACAO",
      "name": "Negociação",
      "changed_at": "2026-09-02T15:41:05-03:00"
    },
    "previous": {
      "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
      "code": "PROPOSTA",
      "name": "Proposta Enviada",
      "changed_at": "2026-09-02T11:22:18-03:00"
    }
  },
  "tracking": {
    "source": "METAADS_MSG",
    "source_app": "instagram",
    "source_url": "https://www.instagram.com/",
    "source_type": "ad",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "referer": null,
    "page_url": null,
    "device": null,
    "browser": null,
    "os": null,
    "click_id": "ARAkLgdbrocNABYQnQoGHmFy",
    "click_id_type": "ctwa_clid",
    "click_date": "2026-09-02T09:14:31-03:00",
    "campaign_data": {
      "ad": {
        "id": "120212847391750456",
        "name": "Carrossel — Depoimentos",
        "adset_id": "120212847391740789",
        "campaign_id": "120212847391740123"
      },
      "ad_set": {
        "id": "120212847391740789",
        "name": "Público quente",
        "campaign_id": "120212847391740123"
      },
      "campaign": {
        "id": "120212847391740123",
        "name": "Institucional | Setembro",
        "status": "ACTIVE"
      }
    },
    "form_data": null,
    "journey": null
  },
  "form_submissions": []
}
```

### Consultar lead

`GET /v1/leads/{lead_id}`

Retorna o lead com os blocos `lead`, `status`, `tracking` e `form_submissions`.

**Parâmetros de rota**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `lead_id` | texto (uuid) | Sim | `id` do lead. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Lead encontrado. Corpo: [Recurso lead](https://leaper.com.br/desenvolvedores/api/#recurso-lead). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `404` | O lead não existe ou é de outra empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/leads/b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`** — Lead

```json
{
  "lead": {
    "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84",
    "name": "Marina Alves",
    "phone": "5511987654321",
    "email": "marina.alves@exemplo.com.br",
    "address": null,
    "custom_fields": [
      {
        "key": "Interesse",
        "value": "Clareamento"
      }
    ],
    "source": "METAADS_MSG",
    "tags": "prioridade-alta",
    "created_at": "2026-09-02T09:14:50-03:00",
    "updated_at": "2026-09-02T15:41:05-03:00",
    "created_from": "external_api",
    "lead_value": "3200"
  },
  "status": {
    "current": {
      "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
      "code": "NEGOCIACAO",
      "name": "Negociação",
      "changed_at": "2026-09-02T15:41:05-03:00"
    },
    "previous": {
      "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
      "code": "PROPOSTA",
      "name": "Proposta Enviada",
      "changed_at": "2026-09-02T11:22:18-03:00"
    }
  },
  "tracking": {
    "source": "METAADS_MSG",
    "source_app": "instagram",
    "source_url": "https://www.instagram.com/",
    "source_type": "ad",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "referer": null,
    "page_url": null,
    "device": null,
    "browser": null,
    "os": null,
    "click_id": "ARAkLgdbrocNABYQnQoGHmFy",
    "click_id_type": "ctwa_clid",
    "click_date": "2026-09-02T09:14:31-03:00",
    "campaign_data": {
      "ad": {
        "id": "120212847391750456",
        "name": "Carrossel — Depoimentos",
        "adset_id": "120212847391740789",
        "campaign_id": "120212847391740123"
      },
      "ad_set": {
        "id": "120212847391740789",
        "name": "Público quente",
        "campaign_id": "120212847391740123"
      },
      "campaign": {
        "id": "120212847391740123",
        "name": "Institucional | Setembro",
        "status": "ACTIVE"
      }
    },
    "form_data": null,
    "journey": null
  },
  "form_submissions": []
}
```

### Atualizar lead

`PUT /v1/leads/{lead_id}`

Atualiza os dados de um lead. Só os campos enviados mudam: campos ausentes ou vazios não apagam o que já existe.

- `custom_fields` é mesclado pela `key`: chaves novas são adicionadas e chaves existentes, substituídas.
- O `lid` e o `created_from` não podem ser alterados.
- Para mudar o status, use [Mover lead de status](https://leaper.com.br/desenvolvedores/api/#mover-lead-de-status).

**Parâmetros de rota**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `lead_id` | texto (uuid) | Sim | `id` do lead. |

**Corpo da requisição** (JSON)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `source` | texto | Não | Origem do lead. `TRACKING_LOST` não é aceito. |
| `client` | objeto | Não | Dados do contato. |
| `client.name` | texto | Não | Nome. |
| `client.phone` | texto | Não | Telefone. Envie só dígitos, com DDI. |
| `client.email` | texto | Não | E-mail. |
| `client.address` | texto | Não | Endereço. |
| `client.custom_fields` | lista de objetos | Não | Campos personalizados, mesclados pela `key`. |
| `client.custom_fields[].key` | texto | Sim | Nome do campo. |
| `client.custom_fields[].value` | texto ou número | Sim | Valor do campo. |
| `lead_value` | texto ou número | Não | Valor do lead, no mesmo formato de [Criar lead](https://leaper.com.br/desenvolvedores/api/#criar-lead). |
| `tags` | texto | Não | Tags do lead. Substituem as atuais. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Lead atualizado. Corpo: [Recurso lead](https://leaper.com.br/desenvolvedores/api/#recurso-lead). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `404` | O lead não existe ou é de outra empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl -X PUT "https://api.external.leaper.com.br/v1/leads/b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84" \
  -H "X-API-Key: $LEAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "email": "marina@clinica-exemplo.com.br",
      "custom_fields": [
        {
          "key": "Unidade",
          "value": "Pinheiros"
        }
      ]
    },
    "lead_value": "4100.00"
  }'
```

**Resposta `200`** — Lead

```json
{
  "lead": {
    "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84",
    "name": "Marina Alves",
    "phone": "5511987654321",
    "email": "marina.alves@exemplo.com.br",
    "address": null,
    "custom_fields": [
      {
        "key": "Interesse",
        "value": "Clareamento"
      }
    ],
    "source": "METAADS_MSG",
    "tags": "prioridade-alta",
    "created_at": "2026-09-02T09:14:50-03:00",
    "updated_at": "2026-09-02T15:41:05-03:00",
    "created_from": "external_api",
    "lead_value": "3200"
  },
  "status": {
    "current": {
      "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
      "code": "NEGOCIACAO",
      "name": "Negociação",
      "changed_at": "2026-09-02T15:41:05-03:00"
    },
    "previous": {
      "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
      "code": "PROPOSTA",
      "name": "Proposta Enviada",
      "changed_at": "2026-09-02T11:22:18-03:00"
    }
  },
  "tracking": {
    "source": "METAADS_MSG",
    "source_app": "instagram",
    "source_url": "https://www.instagram.com/",
    "source_type": "ad",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "referer": null,
    "page_url": null,
    "device": null,
    "browser": null,
    "os": null,
    "click_id": "ARAkLgdbrocNABYQnQoGHmFy",
    "click_id_type": "ctwa_clid",
    "click_date": "2026-09-02T09:14:31-03:00",
    "campaign_data": {
      "ad": {
        "id": "120212847391750456",
        "name": "Carrossel — Depoimentos",
        "adset_id": "120212847391740789",
        "campaign_id": "120212847391740123"
      },
      "ad_set": {
        "id": "120212847391740789",
        "name": "Público quente",
        "campaign_id": "120212847391740123"
      },
      "campaign": {
        "id": "120212847391740123",
        "name": "Institucional | Setembro",
        "status": "ACTIVE"
      }
    },
    "form_data": null,
    "journey": null
  },
  "form_submissions": []
}
```

### Consultar conversa

`GET /v1/leads/{lead_id}/conversation`

Retorna todas as mensagens registradas na conversa do lead, em ordem cronológica. Sem mensagens, `messages` vem vazio.

**Parâmetros de rota**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `lead_id` | texto (uuid) | Sim | `id` do lead. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Conversa do lead. Corpo: [Conversa](https://leaper.com.br/desenvolvedores/api/#conversa). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `404` | O lead não existe ou é de outra empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/leads/b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84/conversation" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "messages": [
    {
      "from_me": false,
      "message": "Olá, quero agendar uma avaliação",
      "received_at": "2026-09-11T10:30:00-03:00"
    },
    {
      "from_me": true,
      "message": "Oi, Marina! Temos horário amanhã às 14h. Pode ser?",
      "received_at": "2026-09-11T10:32:14-03:00"
    }
  ]
}
```

## Status do lead

Consulte e altere o status de um lead no funil.

### Consultar status do lead

`GET /v1/leads/{lead_id}/status`

Retorna o status atual, o anterior e o histórico completo do lead no funil, do mais antigo para o mais recente.

**Parâmetros de rota**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `lead_id` | texto (uuid) | Sim | `id` do lead. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Status do lead. Corpo: [Resposta de status do lead](https://leaper.com.br/desenvolvedores/api/#resposta-de-status-do-lead). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `404` | O lead não existe ou é de outra empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/leads/b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84/status" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`** — Status do lead

```json
{
  "status": {
    "current": {
      "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
      "code": "NEGOCIACAO",
      "name": "Negociação",
      "changed_at": "2026-09-02T15:41:05-03:00"
    },
    "previous": {
      "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
      "code": "PROPOSTA",
      "name": "Proposta Enviada",
      "changed_at": "2026-09-02T11:22:18-03:00"
    },
    "history": [
      {
        "id": "1b8e0c52-7f3a-4d2e-9a61-3c5f0e8d2a17",
        "code": "NOVO_LEAD",
        "name": "Novo Lead",
        "changed_at": "2026-09-02T09:14:50-03:00"
      },
      {
        "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
        "code": "PROPOSTA",
        "name": "Proposta Enviada",
        "changed_at": "2026-09-02T11:22:18-03:00"
      },
      {
        "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
        "code": "NEGOCIACAO",
        "name": "Negociação",
        "changed_at": "2026-09-02T15:41:05-03:00"
      }
    ]
  }
}
```

### Mover lead de status

`PUT /v1/leads/{lead_id}/status`

Move o lead para outro status do funil. A mudança dispara os eventos de conversão configurados para o status
(Meta Ads e Google Ads) e os webhooks de mudança de status da empresa.

Enviar o status em que o lead já está não conta como mudança: nada entra no histórico e nenhum evento é disparado.
A resposta é a mesma de uma mudança.

**Parâmetros de rota**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `lead_id` | texto (uuid) | Sim | `id` do lead. |

**Corpo da requisição** (JSON)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status_id` | texto (uuid) | Sim | `id` do status de destino, de [Listar status do funil](https://leaper.com.br/desenvolvedores/api/#listar-status-do-funil). |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Status atualizado. Corpo: [Resposta de status do lead](https://leaper.com.br/desenvolvedores/api/#resposta-de-status-do-lead). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `404` | O lead não existe ou é de outra empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `422` | O `status_id` não é de um status ativo da empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl -X PUT "https://api.external.leaper.com.br/v1/leads/b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84/status" \
  -H "X-API-Key: $LEAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21"
  }'
```

**Resposta `200`** — Status do lead

```json
{
  "status": {
    "current": {
      "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
      "code": "NEGOCIACAO",
      "name": "Negociação",
      "changed_at": "2026-09-02T15:41:05-03:00"
    },
    "previous": {
      "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
      "code": "PROPOSTA",
      "name": "Proposta Enviada",
      "changed_at": "2026-09-02T11:22:18-03:00"
    },
    "history": [
      {
        "id": "1b8e0c52-7f3a-4d2e-9a61-3c5f0e8d2a17",
        "code": "NOVO_LEAD",
        "name": "Novo Lead",
        "changed_at": "2026-09-02T09:14:50-03:00"
      },
      {
        "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
        "code": "PROPOSTA",
        "name": "Proposta Enviada",
        "changed_at": "2026-09-02T11:22:18-03:00"
      },
      {
        "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
        "code": "NEGOCIACAO",
        "name": "Negociação",
        "changed_at": "2026-09-02T15:41:05-03:00"
      }
    ]
  }
}
```

## Funil

Status do funil configurados na empresa.

### Listar status do funil

`GET /v1/statuses`

Lista os status ativos do funil da empresa, na ordem em que aparecem no painel.

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Status do funil. Corpo: [Lista de status do funil](https://leaper.com.br/desenvolvedores/api/#lista-de-status-do-funil). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/statuses" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "data": [
    {
      "id": "1b8e0c52-7f3a-4d2e-9a61-3c5f0e8d2a17",
      "code": "NOVO_LEAD",
      "name": "Novo Lead",
      "position": 1,
      "is_funnel": true
    },
    {
      "id": "a81d44b0-5e2c-4b7f-8d13-6f9a2c4e0b58",
      "code": "PROPOSTA",
      "name": "Proposta Enviada",
      "position": 2,
      "is_funnel": true
    },
    {
      "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
      "code": "NEGOCIACAO",
      "name": "Negociação",
      "position": 3,
      "is_funnel": true
    },
    {
      "id": "c47e2a90-3d1b-4f6a-b852-9e0d7c1f4a36",
      "code": "END_WON",
      "name": "Finalizado - Convertido",
      "position": 4,
      "is_funnel": true
    },
    {
      "id": "e2915b7c-8a4d-4e3f-a6c0-1b7d9f2e5c84",
      "code": "END_LOST",
      "name": "Finalizado - Perdido",
      "position": 5,
      "is_funnel": true
    }
  ]
}
```

### Consultar status do funil

`GET /v1/statuses/{id}`

Retorna um status do funil da empresa.

**Parâmetros de rota**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | texto (uuid) | Sim | `id` do status. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Status encontrado. Corpo: [Status do funil](https://leaper.com.br/desenvolvedores/api/#status-do-funil). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `404` | O status não existe, foi excluído ou é de outra empresa. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/statuses/5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
  "code": "NEGOCIACAO",
  "name": "Negociação",
  "position": 3,
  "is_funnel": true
}
```

## Empresa

Dados da empresa dona da chave.

### Consultar empresa

`GET /v1/company`

Retorna os dados da empresa dona da chave. É uma boa chamada para testar a autenticação.

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Dados da empresa. Corpo: [Empresa](https://leaper.com.br/desenvolvedores/api/#empresa). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/company" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "id": "6201138c-fc0a-4478-820f-8907907e7f00",
  "name": "Clínica Exemplo",
  "document": "12345678000190",
  "address": "Rua dos Pinheiros, 1000 - São Paulo/SP",
  "phone_number": "551130000000"
}
```

## Relatórios

Números do funil já somados, para painéis e acompanhamento.

### Resumo do período

`GET /v1/reports/summary`

Totais do período: quantos leads entraram, quantos foram convertidos, quantos foram perdidos e a soma dos valores.
Convertido é o lead que está no status `END_WON`; perdido, o que está em `END_LOST`. O valor somado é o `lead_value` de cada lead.

**Parâmetros de consulta**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `start_date` | texto | Não | Início do período, em `YYYY-MM-DD` ou `YYYY-MM-DD HH:MM:SS`, no horário de Brasília. Só a data vale a partir de 00:00:00. Sem este parâmetro, o período começa 30 dias antes do fim. |
| `end_date` | texto | Não | Fim do período, no mesmo formato. Só a data vale até 23:59:59. Sem este parâmetro, o período termina hoje. O período pode ter no máximo 92 dias. |
| `date_field` | texto | Não | Data usada por `start_date` e `end_date`: `created_at` (entrada do lead) ou `status_changed_at` (última mudança de status). Valores: `created_at`, `status_changed_at`. Padrão: `created_at`. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Totais do período. Corpo: [Resumo do período](https://leaper.com.br/desenvolvedores/api/#resumo-do-periodo). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/reports/summary?start_date=2026-09-01&end_date=2026-09-30" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "period": {
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-30 23:59:59",
    "date_field": "created_at"
  },
  "leads": 184,
  "converted": 37,
  "lost": 52,
  "converted_value": 148200.5,
  "open_value": 96400
}
```

### Leads por status

`GET /v1/reports/leads-by-status`

Quantos leads estão em cada status do funil e a soma dos valores, na ordem do funil.
Cada lead aparece uma vez, no status em que está agora.

**Parâmetros de consulta**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `start_date` | texto | Não | Início do período, em `YYYY-MM-DD` ou `YYYY-MM-DD HH:MM:SS`, no horário de Brasília. Só a data vale a partir de 00:00:00. Sem este parâmetro, o período começa 30 dias antes do fim. |
| `end_date` | texto | Não | Fim do período, no mesmo formato. Só a data vale até 23:59:59. Sem este parâmetro, o período termina hoje. O período pode ter no máximo 92 dias. |
| `date_field` | texto | Não | Data usada por `start_date` e `end_date`: `created_at` (entrada do lead) ou `status_changed_at` (última mudança de status). Valores: `created_at`, `status_changed_at`. Padrão: `created_at`. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Leads por status. Corpo: [Leads por status](https://leaper.com.br/desenvolvedores/api/#leads-por-status). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/reports/leads-by-status?start_date=2026-09-01&end_date=2026-09-30" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "period": {
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-30 23:59:59",
    "date_field": "created_at"
  },
  "data": [
    {
      "status": {
        "id": "1b8e0c52-7f3a-4d2e-9a61-3c5f0e8d2a17",
        "code": "NOVO_LEAD",
        "name": "Novo Lead",
        "position": 1
      },
      "leads": 61,
      "value": 42300
    },
    {
      "status": {
        "id": "5f3c9a1e-2b7d-4c8a-9e61-0d4b8a7c3f21",
        "code": "NEGOCIACAO",
        "name": "Negociação",
        "position": 3
      },
      "leads": 34,
      "value": 54100
    },
    {
      "status": {
        "id": "c47e2a90-3d1b-4f6a-b852-9e0d7c1f4a36",
        "code": "END_WON",
        "name": "Finalizado - Convertido",
        "position": 4
      },
      "leads": 37,
      "value": 148200.5
    }
  ]
}
```

### Leads por origem

`GET /v1/reports/leads-by-source`

Quantos leads vieram de cada origem no período, quantos foram convertidos e quanto isso somou,
da origem com mais leads para a com menos.

**Parâmetros de consulta**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `start_date` | texto | Não | Início do período, em `YYYY-MM-DD` ou `YYYY-MM-DD HH:MM:SS`, no horário de Brasília. Só a data vale a partir de 00:00:00. Sem este parâmetro, o período começa 30 dias antes do fim. |
| `end_date` | texto | Não | Fim do período, no mesmo formato. Só a data vale até 23:59:59. Sem este parâmetro, o período termina hoje. O período pode ter no máximo 92 dias. |
| `date_field` | texto | Não | Data usada por `start_date` e `end_date`: `created_at` (entrada do lead) ou `status_changed_at` (última mudança de status). Valores: `created_at`, `status_changed_at`. Padrão: `created_at`. |

**Respostas**

| Código | Descrição |
|---|---|
| `200` | Leads por origem. Corpo: [Leads por origem](https://leaper.com.br/desenvolvedores/api/#leads-por-origem). |
| `400` | Corpo ou parâmetro inválido. A mensagem em `error` diz o que corrigir. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `401` | Cabeçalho `X-API-Key` ausente ou chave inválida. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `403` | A empresa está desativada. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |
| `429` | Limite de requisições atingido. O cabeçalho `Retry-After` diz em quantos segundos tentar de novo. Corpo: [Erro](https://leaper.com.br/desenvolvedores/api/#erro). |

**Exemplo**

```bash
curl "https://api.external.leaper.com.br/v1/reports/leads-by-source?start_date=2026-09-01&end_date=2026-09-30" \
  -H "X-API-Key: $LEAPER_API_KEY"
```

**Resposta `200`**

```json
{
  "period": {
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-30 23:59:59",
    "date_field": "created_at"
  },
  "data": [
    {
      "source": "METAADS_MSG",
      "leads": 96,
      "converted": 21,
      "converted_value": 83400.5
    },
    {
      "source": "GOOGLE_SITE",
      "leads": 52,
      "converted": 11,
      "converted_value": 44300
    },
    {
      "source": "WHATSAPP",
      "leads": 36,
      "converted": 5,
      "converted_value": 20500
    }
  ]
}
```

## Objetos

### Recurso lead

O lead completo, devolvido por Consultar lead, Criar lead e Atualizar lead. Os blocos são os mesmos dos webhooks, com os nomes em snake_case.

| Campo | Tipo | Descrição |
|---|---|---|
| `lead` | objeto ([Lead](https://leaper.com.br/desenvolvedores/api/#lead)) | Dados do contato e do cadastro. |
| `status` | objeto ([Status do lead](https://leaper.com.br/desenvolvedores/api/#status-do-lead)) | Status atual do lead e o anterior. Nulos quando não existem. |
| `tracking` | objeto ([Tracking](https://leaper.com.br/desenvolvedores/api/#tracking)) | Atribuição do lead, com a mesma informação do bloco `tracking` dos webhooks. URLs vêm sem query string. |
| `form_submissions` | lista de objetos ([Envio de formulário](https://leaper.com.br/desenvolvedores/api/#envio-de-formulario)) | Formulários enviados pelo lead, do mais recente para o mais antigo. |

### Lead

Dados do contato e do cadastro.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto (uuid) | Identificador do lead. Não muda; use como referência no seu sistema. |
| `name` | texto ou null | Nome do contato. |
| `phone` | texto ou null | Telefone do contato, como foi cadastrado. |
| `email` | texto ou null | E-mail do contato. |
| `address` | texto ou null | Endereço do contato. |
| `custom_fields` | lista de objetos | Campos personalizados. |
| `custom_fields[].key` | texto | Nome do campo. |
| `custom_fields[].value` | texto ou número ou booleano ou null | Valor do campo. |
| `source` | texto ([Origem do lead](https://leaper.com.br/desenvolvedores/api/#origem-do-lead)) | Valores possíveis de `source`. Leads antigos podem ter valores fora desta lista. |
| `tags` | texto ou null | Tags do lead, em texto. |
| `created_at` | texto (data e hora) ou null | Quando o lead entrou na Leaper. |
| `updated_at` | texto (data e hora) ou null | Última alteração nos dados do lead. |
| `created_from` | texto ou null | Canal de entrada, como `whatsapp`, `forms`, `external_api` ou `manual`. |
| `lead_value` | texto ou número ou null | Valor do lead, como foi informado. |

### Origem do lead

Valores possíveis de `source`. Leads antigos podem ter valores fora desta lista.

| Valor | Descrição |
|---|---|
| `PHONE` | Telefone |
| `EMAIL` | E-mail |
| `WEBSITE` | Site |
| `WHATSAPP` | WhatsApp |
| `WHATSAPPBOT` | Robô de WhatsApp |
| `METAADS_MSG` | Meta Ads, campanha de mensagem |
| `METAADS_SITE` | Meta Ads, campanha de site |
| `GOOGLE_SITE` | Google Ads |
| `TIKTOK_ADS` | TikTok Ads |
| `GOOGLE_ORGANIC` | Google orgânico |
| `INSTAGRAM_ORGANIC` | Instagram orgânico |
| `TIKTOK_ORGANIC` | TikTok orgânico |
| `FACEBOOK_ORGANIC` | Facebook orgânico |
| `YOUTUBE_ORGANIC` | YouTube orgânico |
| `OTHER_ORGANIC` | Outras origens orgânicas |
| `OTHER` | Outros |
| `REFERRAL` | Indicação |
| `IN_PERSON` | Visita presencial |
| `EVENT` | Evento |
| `NO_TRACKING` | Sem rastreio |
| `TRACKING_LOST` | Rastreio perdido. Definido só pela Leaper; não é aceito na entrada. |

### Status do lead

Status atual do lead e o anterior. Nulos quando não existem.

| Campo | Tipo | Descrição |
|---|---|---|
| `current` | objeto ([Passagem por status](https://leaper.com.br/desenvolvedores/api/#passagem-por-status)) ou null | Status atual. |
| `previous` | objeto ([Passagem por status](https://leaper.com.br/desenvolvedores/api/#passagem-por-status)) ou null | Status anterior no histórico. |

### Status do lead com histórico

O status atual, o anterior e todas as passagens do lead pelo funil.

| Campo | Tipo | Descrição |
|---|---|---|
| `current` | objeto ([Passagem por status](https://leaper.com.br/desenvolvedores/api/#passagem-por-status)) ou null | Status atual. |
| `previous` | objeto ([Passagem por status](https://leaper.com.br/desenvolvedores/api/#passagem-por-status)) ou null | Status anterior no histórico. |
| `history` | lista de objetos ([Passagem por status](https://leaper.com.br/desenvolvedores/api/#passagem-por-status)) | Passagens pelo funil, da mais antiga para a mais recente. |

### Resposta de status do lead

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | objeto ([Status do lead com histórico](https://leaper.com.br/desenvolvedores/api/#status-do-lead-com-historico)) | O status atual, o anterior e todas as passagens do lead pelo funil. |

### Passagem por status

Um status do funil e quando o lead entrou nele.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto (uuid) | `id` do status. Não muda quando o status é renomeado. |
| `code` | texto ou null | Código do status. Muda quando o status é renomeado, exceto `END_WON` (convertido) e `END_LOST` (perdido). |
| `name` | texto ou null | Nome do status no painel. |
| `changed_at` | texto (data e hora) ou null | Quando o lead entrou no status. |

### Tracking

Atribuição do lead, com a mesma informação do bloco `tracking` dos webhooks. URLs vêm sem query string.

| Campo | Tipo | Descrição |
|---|---|---|
| `source` | texto ou null | Origem do lead, igual a `lead.source`. |
| `source_app` | texto ou null | Aplicativo de origem, quando o lead veio de anúncio, como `instagram` ou `facebook`. |
| `source_url` | texto ou null | Endereço de onde partiu o clique. |
| `source_type` | texto ou null | Tipo da origem, quando identificado. |
| `utm_source` | texto ou null |  |
| `utm_medium` | texto ou null |  |
| `utm_campaign` | texto ou null |  |
| `utm_content` | texto ou null |  |
| `utm_term` | texto ou null |  |
| `referer` | texto ou null | Página que encaminhou o visitante. |
| `page_url` | texto ou null | Página em que o clique ou o envio aconteceu. |
| `device` | texto ou null | Tipo de dispositivo, como `mobile`. |
| `browser` | texto ou null | Navegador. |
| `os` | texto ou null | Sistema operacional. |
| `click_id` | texto ou null | Identificador do clique na plataforma de anúncio. |
| `click_id_type` | texto ou null | Tipo do identificador, como `ctwa_clid`, `fbclid`, `gclid`, `gbraid` ou `wbraid`. |
| `click_date` | texto (data e hora) ou null | Quando o clique aconteceu. |
| `campaign_data` | objeto ou null | Anúncio, conjunto e campanha de origem, quando identificados. |
| `campaign_data.ad` | objeto ou null |  |
| `campaign_data.ad.id` | texto ou null |  |
| `campaign_data.ad.name` | texto ou null |  |
| `campaign_data.ad.adset_id` | texto ou null |  |
| `campaign_data.ad.campaign_id` | texto ou null |  |
| `campaign_data.ad_set` | objeto ou null |  |
| `campaign_data.ad_set.id` | texto ou null |  |
| `campaign_data.ad_set.name` | texto ou null |  |
| `campaign_data.ad_set.campaign_id` | texto ou null |  |
| `campaign_data.campaign` | objeto ou null |  |
| `campaign_data.campaign.id` | texto ou null |  |
| `campaign_data.campaign.name` | texto ou null |  |
| `campaign_data.campaign.status` | texto ou null | Situação da campanha na plataforma, como `ACTIVE`. |
| `form_data` | objeto ou null | Formulário que originou o lead. |
| `form_data.form_name` | texto ou null | Nome do formulário. |
| `form_data.submitted_at` | texto (data e hora) ou null | Quando o formulário foi enviado. |
| `journey` | lista de objetos ([Passo da jornada](https://leaper.com.br/desenvolvedores/api/#passo-da-jornada)) ou null | Páginas visitadas antes da conversão, quando o rastreamento do site está ativo. |

### Passo da jornada

Uma página visitada. Os parâmetros de atribuição (`utm_*`, `gclid`, `wbraid`, `gbraid`, `fbclid`, `ttclid`, `msclkid`) só aparecem quando existiam no acesso.

| Campo | Tipo | Descrição |
|---|---|---|
| `ts` | texto (data e hora) ou null | Quando a página foi acessada. |
| `duration` | inteiro ou null | Tempo na página, em milissegundos. |
| `url` | texto ou null | Endereço da página. |
| `ref` | texto ou null | Página anterior. |

### Envio de formulário

| Campo | Tipo | Descrição |
|---|---|---|
| `form_name` | texto ou null | Nome do formulário. |
| `answers` | lista de objetos | Respostas dos campos definidos no formulário. |
| `answers[].field` | texto | Nome técnico do campo. |
| `answers[].label` | texto ou null | Rótulo exibido no formulário. |
| `answers[].value` | texto ou número ou booleano ou lista ou null | Valor respondido. Campos de múltipla escolha trazem uma lista. |
| `tracking` | objeto ([Tracking do formulário](https://leaper.com.br/desenvolvedores/api/#tracking-do-formulario)) ou null | Parâmetros capturados na página no momento do envio. |
| `submitted_at` | texto (data e hora) ou null | Quando o formulário foi enviado. |

### Tracking do formulário

Parâmetros capturados na página do formulário. Os que não existiam vêm `null`.

| Campo | Tipo | Descrição |
|---|---|---|
| `utm_source` | texto ou null |  |
| `utm_medium` | texto ou null |  |
| `utm_campaign` | texto ou null |  |
| `utm_content` | texto ou null |  |
| `utm_term` | texto ou null |  |
| `utm_id` | texto ou null |  |
| `fbclid` | texto ou null |  |
| `gclid` | texto ou null |  |
| `wbraid` | texto ou null |  |
| `gbraid` | texto ou null |  |
| `msclkid` | texto ou null |  |
| `ttclid` | texto ou null |  |
| `leaper_adid` | texto ou null | Anúncio informado no link rastreável. |
| `leaper_adsetid` | texto ou null | Conjunto de anúncios informado no link rastreável. |
| `leaper_campaignid` | texto ou null | Campanha informada no link rastreável. |
| `referer` | texto ou null | Página que encaminhou o visitante. |
| `page_url` | texto ou null | Página do formulário. |
| `device` | texto ou null |  |
| `browser` | texto ou null |  |
| `os` | texto ou null |  |
| `click_id` | texto ou null |  |
| `click_id_type` | texto ou null |  |
| `journey` | lista de objetos ([Passo da jornada](https://leaper.com.br/desenvolvedores/api/#passo-da-jornada)) ou null |  |

### Lista de leads

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | lista de objetos | Leads da página. |
| `data[].lead` | objeto ([Lead](https://leaper.com.br/desenvolvedores/api/#lead)) | Dados do contato e do cadastro. |
| `data[].status` | objeto ([Status do lead](https://leaper.com.br/desenvolvedores/api/#status-do-lead)) | Status atual do lead e o anterior. Nulos quando não existem. |
| `data[].tracking` | objeto ([Tracking](https://leaper.com.br/desenvolvedores/api/#tracking)) | Só com `include=tracking`. |
| `data[].form_submissions` | lista de objetos ([Envio de formulário](https://leaper.com.br/desenvolvedores/api/#envio-de-formulario)) | Só com `include=form_submissions`. Do envio mais recente para o mais antigo. |
| `count` | inteiro | Total de leads que atendem aos filtros, em todas as páginas. |
| `limit` | inteiro | `limit` usado na consulta. |
| `offset` | inteiro | `offset` usado na consulta. |

### Status do funil

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto (uuid) | Identificador do status. Não muda. |
| `code` | texto ou null | Código do status. Muda quando o status é renomeado, exceto `END_WON` e `END_LOST`. |
| `name` | texto ou null | Nome do status no painel. |
| `position` | inteiro ou null | Posição no funil. |
| `is_funnel` | booleano ou null | Se o status aparece nas colunas do funil. |

### Lista de status do funil

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | lista de objetos ([Status do funil](https://leaper.com.br/desenvolvedores/api/#status-do-funil)) |  |

### Empresa

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto (uuid) |  |
| `name` | texto ou null |  |
| `document` | texto ou null | CNPJ ou CPF. |
| `address` | texto ou null |  |
| `phone_number` | texto ou null |  |

### Conversa

| Campo | Tipo | Descrição |
|---|---|---|
| `messages` | lista de objetos | Mensagens em ordem cronológica. |
| `messages[].from_me` | booleano | `true` quando a mensagem foi enviada pela empresa. |
| `messages[].message` | texto | Texto da mensagem. |
| `messages[].received_at` | texto (data e hora) ou null | Data e hora da mensagem. |

### Resultado de mensagem

| Campo | Tipo | Descrição |
|---|---|---|
| `lead` | objeto ou null | Lead da conversa. `null` quando a mensagem da empresa foi ignorada. |
| `lead.id` | texto (uuid) |  |

### Período do relatório

Período somado no relatório, do jeito que a API entendeu os parâmetros.

| Campo | Tipo | Descrição |
|---|---|---|
| `start_date` | texto | Início do período, no horário de Brasília. |
| `end_date` | texto | Fim do período, no horário de Brasília. |
| `date_field` | texto | Data usada para montar o período. Valores: `created_at`, `status_changed_at`. |

### Resumo do período

Totais do período.

| Campo | Tipo | Descrição |
|---|---|---|
| `period` | objeto ([Período do relatório](https://leaper.com.br/desenvolvedores/api/#periodo-do-relatorio)) | Período somado no relatório, do jeito que a API entendeu os parâmetros. |
| `leads` | inteiro | Leads no período. |
| `converted` | inteiro | Leads no status `END_WON`. |
| `lost` | inteiro | Leads no status `END_LOST`. |
| `converted_value` | número | Soma do `lead_value` dos leads convertidos. |
| `open_value` | número | Soma do `lead_value` dos leads que não foram convertidos nem perdidos. |

### Leads por status

Leads e valores de cada status do funil, na ordem do funil.

| Campo | Tipo | Descrição |
|---|---|---|
| `period` | objeto ([Período do relatório](https://leaper.com.br/desenvolvedores/api/#periodo-do-relatorio)) | Período somado no relatório, do jeito que a API entendeu os parâmetros. |
| `data` | lista de objetos |  |
| `data[].status` | objeto | Status do funil. |
| `data[].status.id` | texto (uuid) ou null | Identificador do status. Não muda. |
| `data[].status.code` | texto ou null | Código do status. |
| `data[].status.name` | texto ou null | Nome do status no painel. |
| `data[].status.position` | inteiro ou null | Posição no funil. |
| `data[].leads` | inteiro | Leads que estão neste status. |
| `data[].value` | número | Soma do `lead_value` desses leads. |

### Leads por origem

Leads e conversões de cada origem, da origem com mais leads para a com menos.

| Campo | Tipo | Descrição |
|---|---|---|
| `period` | objeto ([Período do relatório](https://leaper.com.br/desenvolvedores/api/#periodo-do-relatorio)) | Período somado no relatório, do jeito que a API entendeu os parâmetros. |
| `data` | lista de objetos |  |
| `data[].source` | texto ou null | Origem do lead (veja [Origem do lead](https://leaper.com.br/desenvolvedores/api/#origem-do-lead)). |
| `data[].leads` | inteiro | Leads desta origem no período. |
| `data[].converted` | inteiro | Leads desta origem no status `END_WON`. |
| `data[].converted_value` | número | Soma do `lead_value` dos leads convertidos desta origem. |

### Erro

Formato de todos os erros. A mensagem é em inglês e diz o que corrigir.

| Campo | Tipo | Descrição |
|---|---|---|
| `error` | texto | Descrição do problema. |