Documentação de Antifraude

Visão Geral

O módulo de Antifraude da plataforma Uappi V3 é um componente vital para a segurança e integridade das operações financeiras de uma loja virtual. 🛡️

Através deste ecossistema, o lojista pode configurar e gerenciar diversas soluções de análise de risco que atuam na validação de transações de pagamento, visando identificar e prevenir comportamentos fraudulentos antes da captura definitiva dos valores.

A arquitetura do módulo é baseada em provedores de serviço (como ClearSale e Konduto) que recebem os dados dos pedidos.

Aplicam seus próprios algoritmos de inteligência e bases de dados globais para emitir um parecer sobre o risco daquela transação. 🚀

A plataforma permite não apenas o cadastro e a configuração dessas integrações, mas também o gerenciamento fino de credenciais, permitindo que cada loja opere com suas próprias chaves de acesso e parâmetros específicos junto aos provedores.

O fluxo de antifraude é intrinsecamente ligado ao processamento de pedidos e pagamentos. 🛒

Quando uma transação é enviada para análise, o sistema acompanha seu status e pode receber atualizações automáticas via webhooks.

Garante que o status do pedido na plataforma reflita sempre a última decisão do provedor de antifraude (Aprovação, Reprovação ou Revisão Manual).

O acesso e a gestão deste módulo são protegidos por escopos de segurança específicos. 🔒

A visualização de configurações e listagens exige a permissão ANTIFRAUD_READ.

Já as operações que envolvem a criação, edição ou remoção de credenciais de acesso junto aos provedores exigem a permissão ANTIFRAUD_CREDENTIAL_WRITE.

Entidades Envolvidas

• Provedor de Antifraude: Representa a entidade integradora (ex: ClearSale, Konduto). Define o protocolo de comunicação, os campos de credencial necessários e as URLs de webhook. 🏢
• Credencial de Antifraude: É o vínculo entre a loja e o provedor. Armazena as chaves de API, tokens e IDs de cliente necessários para que a plataforma consiga autenticar as requisições em nome do lojista. 🔑
• Itens de Credencial: Definidos dinamicamente por cada provedor, representam os campos específicos (ex: app_key, secret_token) que devem ser preenchidos no cadastro da credencial. 📋
• Política Comercial: Permite segmentar o uso de diferentes credenciais de antifraude por canal de venda, garantindo flexibilidade em operações multi-canais. 📍

Notas e Considerações

A configuração correta das credenciais é crítica para o funcionamento do checkout. ⚠️

Um erro nas chaves de acesso ou a ausência de uma credencial vinculada a um método de pagamento que exige antifraude pode resultar em falhas no processamento de pedidos ou na suspensão preventiva de vendas por segurança.

Além disso, a plataforma suporta a recepção de notificações assíncronas. 🛠️

Certifique-se de que a URL de webhook gerada pela plataforma esteja corretamente configurada no painel do seu provedor de antifraude.

Sem este vínculo, o sistema dependerá exclusivamente de consultas manuais ou agendadas para atualizar o status de risco dos pedidos, o que pode atrasar o fluxo logístico da loja. ✅

Listagem de Antifraudes

Descrição

Este endpoint é responsável por retornar a lista de todos os provedores de antifraude integrados nativamente com a plataforma Uappi V3. 📋

Ele serve como ponto de partida para o lojista identificar quais soluções de análise de risco estão disponíveis (como Konduto, ClearSale, etc.) e obter os IDs necessários para iniciar o cadastro de suas credenciais específicas.

A listagem fornece informações básicas sobre cada provedor, incluindo nome, descrição, logotipos e metadados sobre o estado atual da integração na loja, como a quantidade de credenciais já cadastradas e o volume de opções de pagamento que utilizam aquele provedor específico. 🔍

Além disso, o endpoint suporta filtros por status de ativação e nome, permitindo localizar rapidamente um provedor dentro do catálogo de integrações disponíveis.

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão ANTIFRAUD_READ. 🔒

Parâmetros

Headers Obrigatórios

Campos Disponíveis (fields)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/anti-frauds \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "paymentCredentialQuantity"
7    ],
8    "conditions": {
9      "type": "AND",
10      "conditions": [
11        {
12          "field": "active",
13          "value": 1
14        }
15      ]
16    }
17  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "code": "konduto",
8        "name": "Konduto",
9        "image": "https://static.uappi.com.br/anti-fraud/konduto.png",
10        "url": "https://www.konduto.com",
11        "description": "Análise de risco inteligente para e-commerce.",
12        "active": true,
13        "oauth": false,
14        "order": 1,
15        "paymentCredentialQuantity": 2,
16        "paymentOptionQuantity": 5
17      }
18    ],
19    "pagination": {
20      "limit": 10,
21      "offset": 0,
22      "pages": 1,
23      "registers": 1
24    }
25  }
26}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Listagem de Itens de Credencial

Descrição

Este endpoint é fundamental para o fluxo de configuração dinâmica de antifraudes na plataforma. 🛠️

Como cada provedor (ClearSale, Konduto, etc.) possui exigências técnicas distintas, este recurso permite consultar exatamente quais informações (como chaves de API, tokens, IDs de conta ou senhas) são necessárias para estabelecer a comunicação com aquele serviço específico.

Ao informar o ID do provedor, a API retorna uma lista de itens de configuração, detalhando o nome técnico do campo, seu rótulo para exibição, tipo de dado e se ele é obrigatório. 📋

Essa estrutura permite que a interface administrativa construa o formulário de cadastro de forma dinâmica, garantindo que o lojista forneça todos os dados exigidos pelo integrador sem a necessidade de hardcode no frontend.

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão ANTIFRAUD_READ. 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/anti-frauds/1/credentials \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "code": "api_key",
6      "title": "Chave de API",
7      "description": "Chave pública fornecida pelo provedor de antifraude.",
8      "type": "string",
9      "default": "",
10      "required": true,
11      "enum": null
12    },
13    {
14      "code": "environment",
15      "title": "Ambiente",
16      "description": "Define se as transações serão enviadas para produção ou homologação.",
17      "type": "array",
18      "default": [],
19      "enum": [
20        {
21          "value": "production",
22          "label": "Produção"
23        },
24        {
25          "value": "sandbox",
26          "label": "Sandbox/Homologação"
27        }
28      ],
29      "mapKey": "",
30      "mapValue": ""
31    }
32  ] 
33}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.