Esta API identifica alterações recentes de SIM card (SIM SWAP) realizadas 
em um número de celular, podendo assim ajudar a identificar possíveis transações fraudulentas antes que elas aconteçam.

Esta API identifica alterações recentes de SIM card (SIM SWAP) realizadas 
em um número de celular, podendo assim ajudar a identificar possíveis transações fraudulentas antes que elas aconteçam.

URL base:

```bash.copy
https://hml-api.elo.com.br/riskscore/v1
```



### HTTP Headers

Todas as chamadas desta API exigem que os seguintes cabeçalhos estejam presentes na requisição:


<table align="center" border="1" bordercolor="#C0C0C0" cellspacing="0" style="font-size: 1.8rem; font-family: Museo Sans,Helvetica,sans-serif">
 <thead>
 <tr>
 <th style="padding: 5px;">Chave</th>
 <th style="padding: 5px;">Descrição</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td align="left" style="padding: 5px">client_id</td>
 <td align="left" style="padding: 5px">Identificador da aplicação cliente obtida no portal</td>
 </tr>
 <tr>
 <td align="left" style="padding: 5px">access_token</td>
 <td align="left" style="padding: 5px">Token de acesso do usuário que realiza a chamada</td>
 </tr>
 </tbody>
</table>


A geração do access_token está descrita na parte de **autenticação**.

Introdução

O `Authorization` pode ser obtido concatenando o texto __"Basic "__ ao resultado da codificação em Base 64 dos campos `client_id` e `client_secret` concatenados com __:__.

Abaixo um exemplo de pseudo-código para gerar o `Authorization`:

```javascript.copy
var authorization = "Basic " + base64(client_id + ":" + client_secret);
```

e a seguir temos um exemplo de `Authorization` já definido no *header* da requisição:

```bash.copy
Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==
```


Authorization

Conforme descrito na seção de __Introdução__ todas as requisições requerem o *header* `access_token` com o token de acesso para identificar as requisições.

Para obtê-lo, basta utilizar o seguinte *endpoint*:

`POST /oauth/access-token`

Corpo da requsição:

```json.copy
{
  "grant_type": "client_credentials"
}
```

Cabeçalhos:

- Authorization: para obter o access-token, é preciso enviar o *header* `Authorization` que é melhor descrito logo a seguir na subseção __Authorization__.


Autenticação

Na consulta, é passado um número de celular (`phone`) formado pelo sinal de positivo (+) que é opcional, o código do país (55), o código da região formado por dois caracteres, o número 9 referente a um prefixo e mais oito números que identificam o telefone.

__GET /sim-swap/{phone}__

### Resposta

```json
{
    "tag": "Z",
    "swapMin": "90",
    "swapMax": "INF"
}
```
A consulta retorna um período mínimo e um período máximo, que formam o intervalo de dias da alteração, também é retornada uma tag  que representa este intervalo.

- swapMin: período mínimo em dias
- swapMax: período máximo em dias (pode assumir o valor INF caso o retorno seja menor que 1 dia ou maior que 90 dias)
- tag A: menos de 1 dia
- tag B: troca de 1 a 3 dias
- tag C: troca de 3 a 5 dias
- tag D: troca de 5 a 10 dias
- tag E: troca de 10 a 15 dias
- tag F: troca de 15 a 30 dias
- tag G: troca de 30 a 45 dias
- tag H: troca de 45 a 90 dias
- tag X: Operadora/Número não monitorado
- tag Z: acima de 90 dias


SIM Swap request

O recurso sim-swap é uma consulta que retorna um intervalo de dias em que foi feita a alteração mais recente de SIM card para um número de celular.

SIM Swap

Na consulta, é passado um número de celular (phoneNumber) formado pelo código do país (ex:55), o código da região formado por dois caracteres (ex:11) e mais nove números que identificam o telefone.

__POST /trust__

Exemplo de corpo da requisição: 

```json
{
 "details": "true",
 "phoneNumber": "5511999999999",
 "requestId": "elobrazil1000000001006"
}
```

### Resposta

A consulta retorna um conjunto de dados do número pesquisado, dentre eles a pontuação (trustScore) que quanto mais próxima do valor 1000, maior a confiabilidade da linha. Sendo este valor reduzido por cada validação (indicators) mal sucedida, tendo maior risco e menos confiabilidade quando seu valor se aproximar a 0.
Além da pontuação (score) os indicadores abaixo são enviados para propiciar maior clareza e auxiliar a tomada de decisão do parceiro.

![reponses simswap](//images.ctfassets.net/y9c4hf5fbr1n/5Xl3u7PhUIUsKIe58CYck9/4b5167aa569b9fe7f05a528cde8289ff/Captura_de_Tela_2025-05-22_aÌ_s_17.58.19.png)

Estes são os indicadores atuais avaliados:

- __CF__ O encaminhamento incondicional de chamadas está ativado para o número do celular. 
- __CU__ A chamada da operadora não foi bem-sucedida. 
- __D1__ O número de telefone foi encontrado expondo mensagens de texto em páginas da web públicas usadas por pessoas mal-intencionadas para burlar verificações de posse. 
- __DR__ A data do dispositivo retornada não foi obtida em tempo real; pode haver uma mudança de SIM mais recente. 
- __DV__ Alta velocidade de mudança de dispositivo. 
- __LS__ SIM com tempo de permanencia baixo. 
- __ND__ As informações de status da rede não estão disponíveis. 
- __NM__ Não é um tipo de linha móvel. 
- __NV__ Número de telefone inválido. 
- __PN__ O número do celular não está ativo. 
- __PT__ O número de telefone está atualmente em um estado "portado". 
- __PV__ Parcialmente verificado. O ID aprimorado (IDEnhanced) passa, mas a verificação do número de telefone, o MobileID falha. 
- __RO__ O número de telefone está em roaming. 
- __RL__ O número de telefone está associado a um tipo de linha de alto risco (Voip não fixo ou MVNO pré-pago). 
- __TF__ Código de área gratuito. 
- __TR__ Muitas mensagens de solicitação retornadas do provedor. 
- __UC__ Dados insuficientes para calcular a pontuação de confiança. 
- __WS__ O carimbo de data/hora do SIM não foi levado em consideração. 

# Tag
- __swapMin__: período mínimo em dias 
- __swapMax__: período máximo em dias (pode assumir o valor INF caso o retorno seja menor que 1 dia ou maior que 90 dias) 
- __tag A__: menos de 1 dia 
- __tag B__: troca de 1 a 3 dias 
- __tag C__: troca de 3 a 5 dias 
- __tag D__: troca de 5 a 10 dias 
- __tag E__: troca de 10 a 15 dias 
- __tag F__: troca de 15 a 30 dias 
- __tag G__: troca de 30 a 45 dias 
- __tag H__: troca de 45 a 90 dias 
- __tag X__: Operadora/Número não monitorado 
- __tag Z__: acima de 90 dias 

**A Elo retornará HTTP 200**

Exemplo de resposta:

```json
{
 "status": 0,
 "requestId": "elobrazil1000000001006",
 "response": {
 "trustScore": 800,
 "details": [
 {
 "riskLevel": "2"
 },
 {
 "simTimestamp":"2021-03-17T19:44:28Z"
 }
 ],
 "troubleshootingId": "f17f7af8-7cbf-4243-b0fd-5710fb8609da",
 "numberInfo": {
 "carrier": "VIVO S.A.",
 "lineType": "mobile",
 "countryCode": "BR"
 },
 "tag": {
 "tag": "Z",
 "swapMin": "90",
 "swapMax": "INF"
 }
 }
}
```

Valida Sim Card Score request

Essa API oferece um serviço de consulta de reputação do número de telefone móvel para fins de verificação de identidade e autenticação.

O Valida SIM Card Score analisa sinais comportamentais e telefônicos, provenientes de fontes autorizadas, e elenca um indicador de confiança (score) ao número da linha antes de enviar uma comunicação ao cliente, avaliando potenciais riscos através de um fraud score, identificação de linha VOIP insegura, troca de SIM e tempo de ativação do SIM, por exemplo.

Valida Sim Card Score

Elo Valida Sim Card

Número do celular do cliente sem hifen, ponto e parênteses

phone

simSwap

Dados de validação do sim swap do cliente.

A consulta retorna um período mínimo e um período máximo, que formam o intervalo
de dias da alteração,também é retornada uma tag que representa este intervalo.

Código que classifica o SimSwap ou Changemno do Número de Diretório Internacional 
de Assinantes da Mobile Station

Intervalo SWAP mínimo do período de tempo para troca do SimSwap.

- _tag A:_ menos de 1 dia

- _tag B:_ troca de 1 a 3 dias

- _tag C:_ troca de 3 a 5 dias

- _tag D:_ troca de 5 a 10 dias

- _tag E:_ troca de 10 a 15 dias

- _tag F:_ troca de 15 a 30 dias

- _tag G:_ troca de 30 a 45 dias

- _tag H:_ troca de 45 a 90 dias

- _tag X:_ Operadora/Número não monitorado

- _tag Z:_ acima de 90 dias

Intervalo SWAP minimo do período de tempo para troca do SimSwap.

`swapMin:` período mínimo em dias.

swapMin

Intervalo SWAP máximo do período de tempo para troca do SimSwap.

`swapMax:` período máxino em dias `(pode assumir o valor INF caso o retorno seja menor que 1 dia ou maior que 90 dias)`.