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 Credenciais

Descrição

Este endpoint permite recuperar todas as credenciais de antifraude que o lojista cadastrou para sua operação. 📋

Enquanto a listagem de antifraudes retorna os provedores disponíveis na plataforma, este recurso foca nas configurações específicas da loja (chaves, tokens e segredos) vinculadas a esses provedores.

Através deste recurso, é possível gerenciar o catálogo de contas de antifraude da loja, permitindo filtrar por nome ou pelo ID do provedor específico.

Isso facilita a identificação de quais integrações estão ativas e quais contas estão sendo utilizadas. 🔍

Uma funcionalidade importante desta listagem é a possibilidade de expandir a resposta para incluir os vínculos com políticas comerciais.

Ao utilizar campos customizados, o sistema detalha quais canais de venda e opções de pagamento estão associados a cada credencial.

O acesso a este recurso requer obrigatoriamente que o usuário possua o escopo de permissão ANTIFRAUD_CREDENTIAL_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/credentials \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "tradePolicies"
7    ],
8    "conditions": {
9      "type": "AND",
10      "conditions": [
11        {
12          "field": "paymentAntiFraudId",
13          "value": 1
14        }
15      ]
16    }
17  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 5,
7        "paymentAntiFraudId": 1,
8        "name": "Konduto - Conta Produção",
9        "credentials": [
10          {
11            "credentialCode": "api_key",
12            "value": "T1234567890ABCDEF",
13            "enum": null,
14            "createdAt": "2025-07-08 17:07:43",
15            "updatedAt": "2025-07-08 17:07:43"
16          }
17        ],
18        "webhookUrl": "https://minhaloja.com.br/api/v3/anti-fraud/webhook/konduto",
19        "tradePolicies": [
20          {
21            "tradePolicyId": 1,
22            "paymentOptions": [1,2,3]
23          }
24        ]
25      }
26    ],
27    "pagination": {
28      "limit": 10,
29      "offset": 0,
30      "pages": 1,
31      "registers": 1
32    }
33  }
34}

Detalhes da Credencial

Descrição

Este endpoint é utilizado para recuperar todas as informações de uma credencial de antifraude específica. 📋

Diferente da listagem, o detalhe retorna a estrutura completa de configuração, incluindo os valores dos campos técnicos (como chaves e tokens) que foram informados no momento do cadastro junto ao provedor.

Este recurso é essencial para processos de auditoria e conferência de configurações, permitindo que o lojista valide se os dados de integração com o provedor de antifraude estão corretos.

Além disso, ele detalha os vínculos comerciais daquela credencial. 🔍

A resposta inclui a lista de itens de credencial, onde cada item possui seu código técnico, nome e o valor configurado.

Isso garante transparência total sobre como a plataforma está se autenticando junto ao serviço externo.

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

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Campos Disponíveis (fields)

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/anti-frauds/credentials/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "tradePolicies"
7    ]
8  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "paymentAntiFraudId": 1,
6    "name": "Konduto - Conta Produção",
7    "credentials": [
8      {
9        "credentialCode": "api_key",
10        "value": "T1234567890ABCDEF",
11        "enum": null,
12        "createdAt": "2025-07-08 17:07:43",
13        "updatedAt": "2025-07-08 17:07:43"
14      },
15      {
16        "credentialCode": "environment",
17        "value": "production",
18        "enum": [
19          {
20            "value": "production",
21            "label": "Produção"
22          },
23          {
24            "value": "sandbox",
25            "label": "Sandbox/Homologação"
26          }
27        ],
28        "createdAt": "2025-07-08 17:07:43",
29        "updatedAt": "2025-07-08 17:07:43"
30      }
31    ],
32    "webhookUrl": "https://minhaloja.com.br/api/v3/anti-fraud/webhook/konduto",
33    "tradePolicies": [
34      {
35        "tradePolicyId": 1,
36        "paymentOptions": [
37          10,
38          11
39        ]
40      }
41    ]
42  }
43}

⚠️ Possíveis erros:

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

Cadastro de Credencial

Descrição

Este endpoint é utilizado para vincular uma nova conta de antifraude à loja. 🛡️

O processo de cadastro exige que o lojista forneça um nome identificador para a credencial e os dados técnicos específicos exigidos pelo provedor (como chaves de API e tokens), que foram previamente consultados no endpoint de listagem de itens de credencial.

Ao realizar o cadastro, a plataforma valida se todos os campos obrigatórios do provedor foram preenchidos corretamente.

Uma credencial bem-sucedida torna-se disponível para ser vinculada a métodos de pagamento e políticas comerciais, permitindo que a análise de risco seja ativada no checkout. 🚀

É importante garantir que os valores informados no campo credentials correspondam exatamente ao que o provedor de antifraude forneceu, pois qualquer erro de digitação impedirá a comunicação entre as plataformas.

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

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo (Body)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/anti-frauds/1/credentials \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Konduto - Conta Produção",
6    "credentials": {
7      "api-key": "minha-api-key",
8      "homologation": false,
9      "min-value": 0.0,
10      "cancel-on-failure": true,
11      "capture-on-approval": true
12    }
13  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "paymentAntiFraudId": 1,
6    "name": "Konduto - Conta Produção",
7    "credentials": [
8      {
9        "credentialCode": "api_key",
10        "value": "T1234567890ABCDEF",
11        "enum": null,
12        "createdAt": "2025-07-08 17:07:43",
13        "updatedAt": "2025-07-08 17:07:43"
14      }
15    ],
16    "webhookUrl": "https://minhaloja.com.br/api/v3/anti-fraud/webhook/konduto",
17    "tradePolicies": [
18      {
19        "tradePolicyId": 1,
20        "paymentOptions": [1,2,3]
21      }
22    ] 
23  }
24}

⚠️ Possíveis erros:

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

Atualização de Credencial

Descrição

Este endpoint permite a modificação de credenciais de antifraude já configuradas. 🛠️

A atualização é necessária sempre que houver mudança nas chaves de acesso fornecidas pelo provedor ou quando o lojista desejar alterar o ambiente de operação (ex: migrar de Sandbox para Produção).

Ao atualizar uma credencial, todos os campos (nome e lista de credenciais) devem ser enviados novamente, garantindo que o estado final da configuração seja consistente.

A plataforma revalida os dados junto às regras do provedor para assegurar que a integração permaneça funcional após a alteração. 🔄

É importante notar que a atualização da credencial impacta imediatamente todos os métodos de pagamento e políticas comerciais que utilizam essa configuração.

Recomenda-se realizar testes após qualquer alteração crítica nas chaves de acesso.

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

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo (Body)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/anti-frauds/credentials/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Konduto - Conta Produção (Atualizada)",
6    "credentials": {
7      "api-key": "123456",
8      "homologation": false,
9      "min-value": 0.0,
10      "cancel-on-failure": true,
11      "capture-on-approval": true
12    }
13  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "paymentAntiFraudId": 1,
6    "name": "Konduto - Conta Produção",
7    "credentials": [
8      {
9        "credentialCode": "api_key",
10        "value": "T1234567890ABCDEF",
11        "enum": null,
12        "createdAt": "2025-07-08 17:07:43",
13        "updatedAt": "2025-07-08 17:07:43"
14      }
15    ],
16    "webhookUrl": "https://minhaloja.com.br/api/v3/anti-fraud/webhook/konduto",
17    "tradePolicies": [
18      {
19        "tradePolicyId": 1,
20        "paymentOptions": [1,2,3]
21      }
22    ] 
23  }
24}

⚠️ Possíveis erros:

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

Remoção de Credencial

Descrição

Este endpoint permite a exclusão definitiva de uma credencial de antifraude da plataforma. 🗑️

A remoção deve ser feita com cautela, pois apaga permanentemente as chaves de acesso e configurações vinculadas ao provedor.

Este recurso é utilizado quando a loja encerra o contrato com um serviço de análise de risco ou quando uma conta antiga precisa ser descartada.

Por segurança, o sistema impede a remoção de credenciais que estejam atualmente em uso. ⚠️

Se a credencial estiver vinculada a qualquer opção de pagamento ou política comercial ativa, a API retornará um erro de negócio, exigindo que o vínculo seja removido antes da exclusão.

Uma vez removida, a credencial não poderá mais ser utilizada para o processamento de novos pedidos.

Todos os registros históricos de transações feitas com essa credencial permanecem preservados, mas novas análises dependerão de uma nova configuração. ✅

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

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis erros:

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