API Device Check

Última atualização: 27 de Janeiro de 2025

Introdução

A Device Check é uma API que realiza a consulta dos dispositivos, fornecendo informações e insights. Através desse recurso é possível verificar a confiabilidade do dispositivo.

Fingerprint

Para que seja possível utilizar a API, é necessário que o Fingerprint esteja integrado no momento de captura dos dados. Clique aqui para obter mais informações sobre as configurações do Fingerprint.

Autenticação

Todas as requisições submetidas à nossa API devem ser realizadas por meio de um token. Um token é um objeto digital que contém informações sobre a identidade de quem faz a solicitação e para que tipo de acesso ele está autorizado. Ele é gerado através de um usuário e senha que devem ser fornecidos pela ClearSale. Entre em contato com o seu consultor de vendas para mais informações.

Para o recebimento desse dado é necessário que reserve um espaço de 2048 caracteres. Só gere um novo token após a expiração do seu token atual.

Requisição
POST https://devicecheck.clearsale.com.br/api/v1/authentication HTTP/1.1
Content-Type: application/json
{
    "username": "{Seu Usuário}",
    "password": "{Sua Senha}"
}
POST https://devicecheckhml.clearsale.com.br/api/products/v1/authentication HTTP/1.1
Content-Type: application/json
{
    "username": "{Seu Usuário}",
    "password": "{Sua Senha}"
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "token": "{Valor do Token}"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
    {
        "message": "Username or Password is incorrect"
    }
}

Transação

Envio

Para que a transação da DeviceCheck seja gerada, é necessário o envio dos dados da transação. A seguir, detalhamos os principais dados necessários e como enviá-los.

Transação
POST https://devicecheck.clearsale.com.br/api/v2/insights HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization:Bearer {}
{
    "sessionID": "ID1234567891234567891234", //obrigatório
    "externalID": "ID1234", //obrigatório
    "cpf": "12345678900", //opcional, mas se o campo for preenchido há validação de tamanho e formato
    "email": "test1@test", //opcional, mas se o campo for preenchido há validação de tamanho e formato
    "phone": { //opcional, mas se o campo "number" for preenchido todos os outros campos são obrigatórios
        "countryCode": "55",
        "cityCode": "11",
        "number": "99999999"
    },
    "zipCode": "12345678", //opcional, mas se o campo for preenchido há validação de tamanho e formato
}
POST https://devicecheckhml.clearsale.com.br/api/products/v2/insights HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization:Bearer {Token}
{
    "sessionID": "ID1234567891234567891234", //obrigatório
    "externalID": "ID1234", //obrigatório
    "cpf": "12345678900", //opcional, mas se o campo for preenchido há validação de tamanho e formato
    "email": "test1@test", //opcional, mas se o campo for preenchido há validação de tamanho e formato
    "phone": { //opcional, mas se o campo "number" for preenchido todos os outros campos são obrigatórios
        "countryCode": "55",
        "cityCode": "11",
        "number": "99999999"
    },
    "zipCode": "12345678", //opcional, mas se o campo for preenchido há validação de tamanho e formato
}
Resposta

Requisição realizada com sucesso



HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "deviceID": "25432df56bf24f15hd928374",
    "insights": [
        "DEV0002",
        "DEV0007",
        "DEV0500",
        "GER2450",
        "GER2448",
        "GER2405",
        "GER2471",
        "GER2474"
    ],
    "alertQuantity": 0,
    "deviceAge": 24,
    "deviceRisk": "low",
    "score": 0.21142755651978073,
    "similarityResult" : {
        "deviceID": "25432df56bf24f15hd928374",
        "maximumScore": [
            0.9614484590856165
        ],
        "similarDevices": [
            "25432df56bf24f15hd928374",
            "6384118b7016ba14b42221be"
        ]
    }
}
        

O servidor atendeu à solicitação com êxito e não há conteúdo adicional a ser enviado na resposta.

HTTP/1.1 204 No Content

Requisição com parâmetros inválidos


HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "Title": "BadRequest",
    "Status": 400,
    "Detail": "Invalid Body Request.",
    "Instance": "/api/v2/Insights",
    "Extensions": {
        "traceId": "b4068ddd57f96acb19d7cdb25aa9sg01"
    }
}
    

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized

Rota da requisição inválida.

HTTP/1.1 404 NotFound

Erro no processamento da requisição.


HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
    "Title": "Internal Server Error",
    "Status": 500,
    "Detail": "An error occurred while processing your request",
    "Instance": "/api/v2/Insights",
    "Extensions": {
        "traceId": "b4068ddd57f96acb19d7cdb25aa9fd312"
    }
}
    

Dicionário de variáveis

Transaction

Nome Descrição Tipo Tamanho Obrigatório
SessionID Identificador único da sessão da transação. String 24 a 64 Sim
ExternalID Identificador único da transação do integrador. String 6 a 64 Sim
CPF CPF da transação. String 11 opcional
Email Email da transação String 10 a 256 opcional
Phone Telefone da transação Phone - Sim (se informado o campo "number")
ZipCode CEP da transação. String 8 a 11 opcional

Phone

Nome Descrição Tipo Tamanho Obrigatório
CountryCode Código do país do celular da transação. String 1 a 3 Somente se informado o campo "number"
CityCode Código do DDD do celular da transação. String 2 a 3 Somente se informado o campo "number"
Number Número do celular da transação. String 8 a 9 opcional

Resposta

Nome Descrição Tipo
DeviceID Identificador único do dispositivo. String
Insights Insights com base no histórico das informações do dispositivo e os demais dados enviados na requisição. List<String>
AlertQuantity Quantidade de alertas detectados a partir do retorno dos insights. Int
SimilarityResult Lista de objetos contendo os dados de similaridade. Em caso de um novo identificador do dispositivo (DeviceID), a similaridade retorna se existe algum device que possua características similares ao dispositivo e dados da transação. Similarity Result
DeviceAge Idade do dispositivo na base Clearsale (em horas). Int
DeviceRisk Risco associado ao dispositivo em questão. Os níveis de risco do dispositivo podem ser: baixo (low), médio (medium), alto (high). Quanto menor o risco, menor propensão a fraude. String
Score Score de risco de propensão a fraude da dupla CPF + Device. O valor do score de risco é um decimal entre 0 e 1. Quanto mais próximo de 0, menor a propensão a fraude. Double
SmartID Identificador de redundância não único. String

Similarity Result

Nome Descrição Tipo
DeviceID Identificador único do dispositivo. String
MaximumScore Resultado do cálculo de similaridade com informações do score. List<object>
SimilarDevices Lista de devices similares ao dispositivo e dados da transação. List<String>

Error Codes

Código Tipo Descrição
200 Success Sua solicitação foi bem-sucedida.
204 No Content Solicitação processada com sucesso, mas não há conteúdo para mostrar.
400 Bad Request Parece que houve um erro na sua solicitação. Por favor, confira a tabela com as variáveis necessárias, verifique se todos os campos obrigatórios estão preenchidos corretamente e se a sintaxe está correta.
401 Unauthorized Você precisa se autenticar para acessar este recurso. Por favor, faça login.
403 Forbidden Desculpe, você não tem permissão para acessar este recurso.
404 Not Found Não conseguimos encontrar o recurso solicitado. Verifique se a URL está correta.
500 Internal Server Error Desculpe, algo deu errado no nosso lado. Estamos trabalhando para resolver isso. Por favor, entre em contato com nosso suporte para mais informações.
502 Bad Gateway Recebemos uma resposta inválida do servidor upstream. Nossa equipe está ciente e trabalhando para corrigir isso. Entre em contato com nosso suporte se precisar de ajuda imediata.
503 Service Unavailable Desculpe, estamos temporariamente fora do ar devido a manutenção ou sobrecarga. Nossa equipe está trabalhando para resolver isso o mais rápido possível. Entre em contato com nosso suporte para mais detalhes.
504 Gateway Timeout O servidor, ao atuar como um gateway ou proxy, não recebeu uma resposta oportuna do servidor upstream. Estamos cientes do problema e trabalhando para resolvê-lo. Entre em contato com nosso suporte para mais informações.

Lista de Insights

Requisitos de Dados

Para garantir a precisão e relevância dos Insights, é fundamental que os dados correspondentes aos módulos contratados sejam devidamente enviados. Por exemplo, ao solicitar um Insight relacionado ao histórico de telefone, é imprescindível que as informações do telefone em questão tenham sido enviadas.


Baixe o arquivo para visualizar todos os insights

XLSX

Módulos

Os módulos da API Device Check são extensões que podem ser contratadas para obter resultados personalizados.

Módulo Informações
Envio de Eventos Clique aqui para acessar a nossa documentação do Envio de Eventos.

Variável Resposta

A variável resposta tem a finalidade de abastecer o ecossistema de fraudes, identificando os dispositivos envolvidos em transações fraudulentas.

Para utilizar este endpoint, é necessário estar autenticado. saiba mais.

Detalhes do arquivo

Configuração do Webhook

São aceitos dois tipos de arquivos na requisição, .csv e .zip. Ambos os tipos são verificados e precisam conter dados válidos.

Tabela com informações das colunas:

Nome da Coluna Descrição
ID Transacional Identificador transacional utilizado.
DeviceId ID do dispositivo do cliente.
Resultado Informação referente ao resultado da análise. Os resultados podem ser:
° Suspeito
° Fraude Confirmada
° Device Positivado

Transação

Requisição
POST https://devicecheck.clearsale.com.br/api/v1/responsevariables HTTP/1.1
Content-Type: multipart/form-data
Authorization:Bearer {Token}
Content-Disposition: form-data; name="file"; filename="VariavelRespostaExemplo.csv"
    
Resposta
HTTP/1.1 200 OK

Requisição com alguma inconsistência no arquivo ou na configuração da requisição.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
    "Title": "BadRequest",
    "Status": 400,
    "Detail": "'File' must not be empty. | 'File' must not be empty. | The File value is not valid",
    "Instance": "/api/v1/responsevariables",
    "Extensions": {
        "traceId": "123456abcdefghijl00m37af1681c02c4"
    }
}

Requisição com token expirado ou inválido

HTTP/1.1 401 Unauthorized

Rota da requisição inválida

HTTP/1.1 404 NotFound

Erro no processamento da requisição

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
    "Title": "Internal Server Error",
    "Status": 500,
    "Detail": "An error occurred while processing your request",
    "Instance": "/api/v1/responsevariables",
    "Extensions": {
        "traceId": "123456abcdefghijl00m37af1681c02c4"
    }
}

Arquivo de exemplo

Baixe o nosso arquivo de exemplo de envio da variável resposta:

XLSX

FAQ

Acesse nosso FAQ Clicando Aqui

Licença de Uso

Ao utilizar a nossa API você estará concordando com a seguinte licença.

Copyright © 2025 ClearSale

Todos os direitos são reservados, sendo concedida a permissão para usar o software da maneira como está, não sendo permitido qualquer modificação ou cópia para qualquer fim. O Software é licenciado com suas atuais configurações “tal como está” e sem garantia de qualquer espécie, nem expressa e nem implícita, incluindo mas não se limitando, garantias de comercialização, adequação para fins particulares e não violação de direitos patenteados. Em nenhuma hipótese os titulares dos Direitos Autorais podem ser responsabilizados por danos, perdas, causas de ação, quer seja por contrato ou ato ilícito, ou outra ação tortuosa advinda do uso do Software ou outras ações relacionadas com este Software sem prévia autorização escrita do detentor dos direitos autorais.