# Como instalar a integração IPQualityScore Phone Validation

**IPQualityScore Phone Validation** é uma integração de Firewall que valida números de telefone em tempo real, analisando score de risco, país de origem, operadora, tipo de linha e status de conexão. Ela ajuda sua aplicação a detectar números de telefone fraudulentos, linhas inativas e VOIPs de alto risco antes que cheguem à sua origem.

Quando uma requisição chega ao edge, a função extrai o número de telefone da fonte configurada (query string, corpo da requisição ou header), consulta a API do IPQualityScore e bloqueia a requisição, descarta a conexão ou adiciona um header com o resultado — dependendo da ação configurada.

---

## Pré-requisitos

Para começar a usar esta integração, você precisa:

- Criar uma [conta no IPQualityScore](https://www.ipqualityscore.com/create-account).
- Obter sua **API Key** no painel do IPQualityScore após a criação da conta.

---

## Obtenha a integração

Para instalar esta integração:

1. Acesse [Azion Console](/pt-br/documentacao/produtos/guias/como-acessar-o-azion-console/) > **Marketplace**.
2. Na página inicial do Marketplace, selecione o cartão da **Phone Validation**.
3. Na página de integração, clique no botão **Install**.

Você verá uma mensagem indicando que sua integração foi instalada com sucesso.

:::tip
Você pode procurar qualquer integração navegando pelos cards, usando os filtros ou digitando uma palavra-chave na barra de busca.
:::

---

## Configure a integração

Depois de instalar a integração **IPQualityScore Phone Validation**, conclua as etapas abaixo para configurá-la.

### Configure um Firewall

Siga estes passos:

1. No canto superior esquerdo, abra o **Products menu** e selecione **Firewall** na seção **Secure**.
2. Clique no botão **+ Firewall**.
3. Dê um nome fácil de lembrar ao seu firewall.
4. Ative a opção **Functions** na seção **Modules**.
   - Esta ação dá acesso a functions no firewall.
5. Clique no botão **Save**.

Pronto. Agora você instanciou o firewall para sua função e tem acesso a functions em seu firewall.

:::caution[Atenção]
Se um produto ou módulo estiver ativado, pode gerar custos relacionados ao uso. Consulte a [página de preços](/pt-br/documentacao/produtos/precos/) para obter mais informações.
:::

### Configure uma função no Firewall

Enquanto ainda estiver na página do **Firewall**:

1. Selecione a aba **Functions Instances**.
2. Clique no botão **+ Function Instance**.
3. Dê um nome fácil de lembrar à sua instância.
4. No menu suspenso, selecione a função **IPQualityScore Phone Validation**.
5. Na caixa **Arguments**, passe suas variáveis:

```json
{
  "api_key": "SuaAPIKeyIPQS",
  "fast": true,
  "get_data_from": "querystring",
  "data_name": "phone",
  "when_score_above": 80,
  "execute": "deny"
}
```

Onde:

| Variável | Obrigatório | Descrição |
| ---- | ---- | ---- |
| `api_key` | Sim | Sua API Key do IPQualityScore |
| `fast` | Não | Ativa o modo de validação rápida. Quando `true`, algumas verificações forenses são ignoradas para menor latência. Recomendado: `true`. Padrão: `false` |
| `get_data_from` | Sim | Define de onde o número de telefone será extraído. Valores aceitos: `querystring`, `body`, `header` |
| `data_name` | Sim | O nome do parâmetro de query string, campo do corpo ou header que contém o número de telefone |
| `when_score_above` | Não | Threshold de score (0–100) que aciona a ação definida em `execute`. Scores de fraude ≥ 90 são considerados alto risco. Se não definido, nenhuma ação é executada |
| `execute` | Não | Ação a ser executada quando o score ultrapassar `when_score_above`. Valores aceitos: `deny`, `drop`, `add_header` |

Os valores de `execute` se comportam da seguinte forma:

| Valor | Comportamento |
| ---- | ---- |
| `deny` | Executa o behavior **Deny**, retornando uma resposta `403 Forbidden` |
| `drop` | Executa o behavior **Drop**, encerrando a conexão sem resposta |
| `add_header` | Adiciona o header `ipqs-limit-score-reached` à requisição e deixa ela seguir. Use quando quiser tratar o resultado no Rules Engine ou na origem |

:::note
Os principais dados retornados pela API do IPQualityScore são: `valid`, `risky`, `active`, `line_type`, `carrier`, `VOIP`, `fraud_score` e `recent_abuse`. Para a lista completa de campos e suas descrições, consulte a [documentação da API de validação de telefone do IPQualityScore](https://www.ipqualityscore.com/documentation/phone-number-validation-api/overview).
:::

6. Clique no botão **Save**.

### Configure uma regra no Rules Engine

Para concluir, você deve configurar uma regra no **Rules Engine** para definir os critérios (*criteria*) e o comportamento (*behavior*) para executar a função.

Ainda na página do **Firewall**:

1. Selecione a aba **Rules Engine**.
2. Clique no botão **+ Rule Engine**.
3. Dê um nome fácil de lembrar à sua nova regra.
4. Selecione um *criteria* (critério) para definir quais requisições acionam a verificação de telefone.
   - Exemplo: if `Host` *matches* `seudominio.com`.
5. Abaixo, selecione **Run Function** como *behavior* e escolha a instância da função Phone Validation criada anteriormente.
6. Clique no botão **Save**.

### Associe o Firewall ao seu domínio

No Console, você deve agora configurar seu domínio para que ele seja protegido pelo seu Firewall.

1. No **Products menu**, selecione **Workloads**.
2. Clique no workload que contém o domínio que você deseja proteger com sua função **Phone Validation**.
3. Na seção **Deployment Settings**, clique no seletor de `Firewall` e escolha o Firewall que você acabou de criar.
4. Clique no botão **Save**.

Pronto. Agora a integração **IPQualityScore Phone Validation** está em execução e validando números de telefone no edge.

---

## Documentação relacionada

- [Referência de Integrações da Azion](/pt-br/documentacao/produtos/marketplace/integracoes/)
- [Como instalar uma integração](/pt-br/documentacao/produtos/marketplace/instalar-uma-integracao/)
- [Como atualizar uma integração](/pt-br/documentacao/produtos/marketplace/atualizar-uma-integracao/)
- [Documentação da API de validação de telefone do IPQualityScore](https://www.ipqualityscore.com/documentation/phone-number-validation-api/overview)