> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegly.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead score

> Consultar, criar e atualizar critérios de pontuação e aplicá-los no cadastro de leads e oportunidades.

O lead score soma os pontos dos critérios aplicados a um lead ou a uma oportunidade, sempre limitado entre `0` e `100`. Pela API externa você lista, consulta, cria e atualiza os critérios da empresa em `/integrations/external/lead-scores/criteria` e aplica critérios já no cadastro de leads e oportunidades. A exclusão de critérios é feita apenas no CRM.

| Ação | Permissão da chave |
| - | - |
| Listar e consultar critérios | `crm/lead-score.read` |
| Criar critérios | `crm/lead-score.create` |
| Atualizar, inativar e reativar critérios | `crm/lead-score.update` |
| Aplicar critérios na criação de leads e oportunidades | `crm/lead-score.create`, além de `crm/lead.create` ou `crm/deal.create` |

O usuário que criou a chave é o ator das operações. Se ele estiver inativo, as rotas retornam `403`.

## Como um critério funciona

| Campo | Regra |
| - | - |
| `target_type` | `LEAD` para leads, `DEAL` para oportunidades ou `BOTH` para os dois |
| `points` | Inteiro entre `-100` e `100`, diferente de `0`. Pontos negativos reduzem o score |
| `options` | Opções de resposta, cada uma com `label` e `points` próprios |
| `status` | `1` ativo ou `0` inativo. Só critérios ativos podem ser aplicados |
| `category_id` | Categoria opcional, que precisa estar ativa. As categorias são gerenciadas no CRM, e o critério retorna os dados dela em `category` |

Quando o critério tem opções ativas, quem aplica precisa escolher uma delas, e a pontuação aplicada é a da opção. Sem opções ativas, vale o `points` do critério. Alterar um critério depois não recalcula leads e oportunidades que já o receberam: cada aplicação guarda a pontuação e os nomes da época.

## Listar e consultar

```bash theme={null}
curl --get 'https://api.wegly.com.br/integrations/external/lead-scores/criteria' \
  --header "Authorization: Bearer $WEGLY_API_KEY" \
  --data-urlencode 'target_type=LEAD' \
  --data-urlencode 'status=1' \
  --data-urlencode 'take=50'
```

A listagem aceita `search` (parte do nome), `skip`, `take` (de `1` a `100`, padrão `10`), `category_id`, `without_category=true` (somente critérios sem categoria), `target_type` e `status`. `target_type=LEAD` e `target_type=DEAL` também trazem os critérios `BOTH`; `target_type=BOTH` traz apenas os compartilhados. `category_id` e `without_category=true` não podem ser usados juntos. Os critérios vêm do mais recente para o mais antigo:

```json theme={null}
{
  "total": 1,
  "records": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "category_id": "22222222-2222-4222-8222-222222222222",
      "category": {
        "id": "22222222-2222-4222-8222-222222222222",
        "name": "Qualificação",
        "color": { "background": "#1E88E5", "foreground": "#FFFFFF" },
        "status": 1
      },
      "target_type": "BOTH",
      "name": "Faixa de orçamento",
      "description": "Orçamento informado pelo contato",
      "points": 10,
      "status": 1,
      "options": [
        {
          "id": "33333333-3333-4333-8333-333333333333",
          "label": "Até R$ 10 mil",
          "description": null,
          "points": 5,
          "position": 0,
          "status": 1
        },
        {
          "id": "44444444-4444-4444-8444-444444444444",
          "label": "Acima de R$ 10 mil",
          "description": null,
          "points": 20,
          "position": 1,
          "status": 1
        }
      ],
      "created_at": "2026-11-12T12:00:00.000Z",
      "updated_at": "2026-11-12T12:00:00.000Z"
    }
  ]
}
```

`options` traz as opções ativas e inativas, ordenadas por `position`. Critérios inativos aparecem na listagem, a menos que você filtre por `status=1`. Para consultar um critério, use `GET /integrations/external/lead-scores/criteria/{id}`; um critério inexistente, excluído no CRM ou de outra empresa retorna `404`.

## Criar um critério

```bash theme={null}
curl --request POST 'https://api.wegly.com.br/integrations/external/lead-scores/criteria' \
  --header "Authorization: Bearer $WEGLY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "target_type": "BOTH",
    "name": "Faixa de orçamento",
    "description": "Orçamento informado pelo contato",
    "points": 10,
    "options": [
      { "label": "Até R$ 10 mil", "points": 5 },
      { "label": "Acima de R$ 10 mil", "points": 20 }
    ]
  }'
```

A resposta `201` é o critério criado, já ativo e com os IDs das opções, no mesmo formato da consulta. `target_type`, `name` e `points` são obrigatórios; `points` continua obrigatório mesmo com opções e vale se o critério ficar sem opções ativas.

* `name` e `label` aceitam até 120 caracteres; os espaços das extremidades são removidos, e um nome só com espaços retorna `400`.
* `description` aceita até 5.000 caracteres.
* Um critério aceita até 50 opções, e os nomes das opções não podem se repetir no mesmo critério, sem diferenciar maiúsculas e minúsculas.
* Nas opções, `position` assume a ordem da lista e `status` assume `1` quando omitidos.
* Uma categoria inexistente ou inativa em `category_id` retorna `404`.
* A criação não usa idempotência: repetir a chamada cria outro critério.

## Atualizar um critério

`PUT /integrations/external/lead-scores/criteria/{id}` altera somente os campos enviados:

```json theme={null}
{
  "name": "Faixa de orçamento mensal",
  "options": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "label": "Até R$ 10 mil",
      "points": 5
    },
    { "label": "Acima de R$ 50 mil", "points": 30 }
  ]
}
```

Quando `options` é enviado, ele substitui a lista inteira: opções com `id` são atualizadas, opções sem `id` são criadas e as opções atuais que não vierem na lista são excluídas. Para manter as opções como estão, não envie `options`; para remover todas, envie uma lista vazia. Consulte o critério antes de alterar as opções para reenviar os `id` das que devem continuar. Um `id` que não pertence ao critério retorna `404`.

`category_id: null` remove a categoria, e `description: null` limpa a descrição. `target_type`, `name`, `points`, `status` e `options` não aceitam `null`. Para tirar um critério de uso, envie `status: 0`: ele deixa de poder ser aplicado e de contar no conhecimento do registro, mas as aplicações já feitas continuam. `status: 1` o reativa. Não há exclusão pela API.

## Aplicar critérios no cadastro

`POST /integrations/external/leads` e `POST /integrations/external/deals` aceitam `score_applications`, com até 50 critérios. Cada item tem `criterion_id`, `criterion_option_id` e `note`, a observação do critério aplicado:

```json theme={null}
{
  "title": "Interesse no plano Enterprise",
  "person": {
    "name": "Marina Souza",
    "contacts": [{ "type": 0, "value": "11999999999" }]
  },
  "score_applications": [
    {
      "criterion_id": "11111111-1111-4111-8111-111111111111",
      "criterion_option_id": "44444444-4444-4444-8444-444444444444",
      "note": "Informou orçamento de R$ 25 mil no formulário."
    },
    {
      "criterion_id": "55555555-5555-4555-8555-555555555555"
    }
  ]
}
```

* A chave precisa de `crm/lead-score.create`, além da permissão de criar o registro. Sem ela, a criação inteira retorna `403`. Uma lista vazia ou a ausência do campo não exige a permissão.
* Cada critério precisa estar ativo e servir ao registro: leads aceitam critérios `LEAD` ou `BOTH`; oportunidades, `DEAL` ou `BOTH`. O mesmo critério não pode vir duas vezes.
* `criterion_option_id` é obrigatório quando o critério tem opções ativas e precisa ser uma delas; quando o critério não tem opções ativas, a opção não pode ser enviada.
* `note` é opcional e aceita até 5.000 caracteres.
* Permissão e critérios são conferidos antes da idempotência e da deduplicação de pessoa: um critério inválido retorna erro sem consumir a chave de idempotência, alterar uma pessoa ou criar o registro. Repetir uma criação já concluída devolve o registro sem conferir os critérios de novo.
* Os critérios são gravados logo depois do registro, com o histórico do score e uma atividade na linha do tempo, e atualizam `score`, `score_criteria_count` e `score_updated_at`. Se a empresa usa o lead score como métrica de qualificação, eles também atendem às etapas que exigem qualificação na entrada.

A API externa aplica critérios apenas na criação. Para mudar a pontuação de um registro existente, use o CRM. Os demais campos do cadastro estão no guia de [leads e oportunidades](https://docs.wegly.com.br/documentacao-da-api/integracoes/leads-e-oportunidades.md).

## Erros

| Status | Situação |
| - | - |
| `400` | Dados inválidos: pontos `0`, decimais ou fora de `-100` a `100`, opções com nomes repetidos, `status` diferente de `0` e `1`, `null` em campo obrigatório, `category_id` com `without_category=true`, ou critério repetido, de outro tipo de registro ou com opção ausente ou indevida no cadastro |
| `401` | Chave ausente, inválida, inativa, expirada ou domínio não permitido |
| `403` | Permissão de lead score ausente na chave ou usuário criador da chave inativo |
| `404` | Critério, opção ou categoria inexistente, excluída ou de outra empresa. Também categoria inativa ao criar ou atualizar um critério, e critério ou opção inativa no cadastro |
| `429` | Limite de requisições atingido |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.