Documentação de Antifraude (Pedidos)

Visão Geral

O antifraude da Uappi atua junto aos pagamentos de pedidos: o lojista pode enviar transações para análise, consultar o status junto ao provedor e receber atualizações assíncronas via webhook quando o integrador suporta esse modelo.

Na API privada, as operações de consulta e envio ficam no escopo de pagamentos de pedidos (/orders/payments/...), com validações e permissões alinhadas às demais rotas de pagamento.

As URLs de webhook seguem outro prefixo (/anti-fraud/webhook/...) e são pensadas para serem chamadas pelos provedores de antifraude (ou por proxies configurados), com corpo e cabeçalhos conforme cada integração.

Os códigos de antifraude disponíveis na plataforma seguem o cadastro do serviço de integração (exemplos presentes na base: clearsale-start, clearsale-total, konduto), sempre referenciados pelo parâmetro de rota antiFraudCode nos webhooks.

Entidades Envolvidas

• Pagamento do pedido (order payment): registro financeiro que pode ser enviado ao antifraude, receber credencial vinculada e ter campos como status de antifraude atualizados após consulta ou notificação.
• Transação / credencial de antifraude: definidas no ecossistema de integração; o envio pode informar credencial específica ou usar comportamento padrão já associado ao pagamento.
• Provedor externo: ClearSale, Konduto, entre outros cadastrados; cada um expõe contratos próprios de envio, consulta e webhook.

Notas e Considerações

• A consulta exige que o pagamento já tenha sido enviado ao antifraude; caso contrário, a API responde com erro de negócio específico (vide documentação do endpoint de consulta).
• O envio manual não deve duplicar envio para o mesmo pagamento: se a transação já foi enviada, a API bloqueia a operação.
• Para webhooks, o formato do JSON e cabeçalhos depende do provedor; use as páginas dedicadas a cada código como guia de URL e comportamento esperado ao nível da plataforma. Em caso de dúvida sobre autenticação na borda (comparar com outras rotas públicas de webhook do projeto), alinhe com o time de plataforma.

Consulta de transações no antifraude

Descrição

Este endpoint permite atualizar o status do antifraude de um ou mais pagamentos de pedido, consultando o provedor configurado na loja.

Na prática, ele busca a análise mais recente do antifraude (como aprovação, rejeição ou revisão) e aplica essas informações aos pagamentos correspondentes.

Após uma chamada bem-sucedida, o sistema atualiza os dados do pagamento e pode executar automaticamente algumas ações previstas nas regras da loja — como capturar ou cancelar a transação, dependendo do retorno do antifraude.

Esse recurso exige o escopo TRANSACTIONS_READ.

> Importante: > Apenas pagamentos que já foram enviados ao antifraude podem ser consultados. > Caso algum pagamento informado ainda não tenha sido enviado, a requisição será rejeitada com erro específico.

Parâmetros

Headers Obrigatórios

Parâmetros de consulta (query string)

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/orders/payments/anti-fraud/consult \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --data '{
5    "orderPaymentIds": [
6      1, 2, 3,
7    ]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1[
2  {
3    "orderPaymentId": 101,
4    "success": true,
5    "status": "approved",
6    "paymentAntiFraudId": 10,
7    "paymentAntiFraudCredentialId": 5,
8    "request": {},
9    "response": {},
10    "credentials": {
11      "capture-on-approval": false,
12      "cancel-on-failure": false
13    }
14  }
15]

> Nota: valores de status, request, response e credentials dependem do antifraude e da configuração da credencial. Use ambiente de homologação do provedor para validar o contrato completo.

⚠️ Possíveis erros:

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

Envio de transações ao antifraude

Descrição

Este endpoint permite enviar manualmente pagamentos ao antifraude configurado na loja.

Diferente do fluxo automático, aqui o envio é iniciado de forma explícita — útil quando você precisa reenviar uma transação, corrigir um fluxo ou forçar uma nova análise.

Para cada pagamento informado, o sistema encaminha os dados ao provedor de antifraude e passa a acompanhar o retorno dessa análise, que pode influenciar o andamento do pagamento (como aprovação ou rejeição).

A requisição aceita até 100 pagamentos por chamada. Também é possível informar, opcionalmente, qual credencial de antifraude deve ser usada; se o pagamento já tiver uma credencial associada, ela pode ser mantida conforme a regra da loja.

O uso deste endpoint exige o escopo ORDER_WRITE, pois a operação pode impactar o estado do pagamento e disparar integrações relacionadas.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/orders/payments/anti-fraud/send' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "payments": [
7      {
8        "orderPaymentId": 101,
9        "paymentAntiFraudCredentialId": null
10      }
11    ]
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1[
2  {
3    "orderPaymentId": 101,
4    "success": true,
5    "status": "pending_analysis",
6    "paymentAntiFraudId": 20,
7    "paymentAntiFraudCredentialId": 5,
8    "request": {},
9    "response": {},
10    "credentials": {}
11  }
12]

⚠️ Possíveis erros:

Webhook antifraude — ClearSale Start

Descrição

Esta rota recebe webhooks de antifraude da ClearSale (Start), associados ao código clearsale-start cadastrado na plataforma.

Ela recebe o payload enviado pela ClearSale e o encaminha para o serviço de integração, que interpreta o evento e aplica as atualizações necessárias na loja — incluindo possíveis impactos no pagamento, conforme o resultado da análise.

O formato da requisição (corpo e cabeçalhos) segue o contrato oficial da ClearSale Start e é repassado diretamente ao integrador, sem validação prévia na API.

Parâmetros

Parâmetros da URL

Corpo

Objeto JSON conforme a especificação do webhook ClearSale Start na sua versão contratada com a plataforma. Campos comuns dependem da configuração do conector no external.uappi.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/anti-fraud/webhook/clearsale-start' \
3  --header 'Content-Type: application/json' \
4  --data '{ }'

Substitua { } pelo payload real fornecido pela ClearSale.

✅ Resposta de Sucesso

HTTP Status: 200 OK em cenários processados pela controller com retorno JSON.

• Em fluxos concluídos com sucesso no integrador, o corpo costuma refletir a resposta acordada com o conector (pode ser um objeto simples de confirmação).
• Quando a análise do antifraude retorna insucesso interno tratado como resposta estruturada, o payload pode trazer campos como success, status e response — o formato exato depende do retorno do processo de webhook.

⚠️ Possíveis erros:

⚠️ Nota de implementação (borda)

No código da API, a rota de webhook de pagamento equivalente utiliza o middleware PublicAuth; a rota de antifraude está declarada em routes/api/anti-fraud/anti-fraud.php sem middleware nomeado na mesma linha. Confirme com o time de plataforma autenticação, IP allowlist e formato esperado em produção antes de publicar integrações novas.

Webhook antifraude — ClearSale Total

Descrição

Esta rota recebe webhooks de antifraude da ClearSale (Total), associados ao código clearsale-total.

O funcionamento é semelhante ao da versão Start: o sistema recebe o payload enviado pela ClearSale, encaminha para o serviço de integração e aplica as atualizações no estado dos pagamentos na loja conforme o retorno da análise.

A principal diferença está no formato dos dados, que segue o contrato do produto ClearSale Total, geralmente mais completo em relação aos eventos e informações enviadas.

O conteúdo da requisição é repassado ao integrador sem validação prévia na API.

Parâmetros

Parâmetros da URL

Corpo

JSON conforme documentação ClearSale Total / contrato do conector Uappi.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/anti-fraud/webhook/clearsale-total' \
3  --header 'Content-Type: application/json' \
4  --data '{ }'

✅ Resposta de Sucesso

HTTP Status: 200 OK com corpo JSON conforme o resultado do processamento (confirmação ou estrutura de erro de negócio do antifraude, dependendo do caso).

⚠️ Possíveis erros:

⚠️ Nota de implementação (borda)

Mesma observação da página ClearSale Start: alinhar com o time autenticação e exposição desta URL em produção, comparando com outras rotas públicas de webhook do projeto.

Webhook antifraude — Konduto

Descrição

Esta rota recebe webhooks de antifraude da Konduto, associados ao código konduto na plataforma.

O payload enviado pelo provedor é encaminhado ao serviço de integração, que processa a análise e aplica as atualizações necessárias nos pagamentos da loja, conforme o resultado retornado.

O formato da requisição segue o padrão definido pela própria Konduto (e pelo conector de integração) e é tratado diretamente pelo serviço responsável.

Parâmetros

Parâmetros da URL

Corpo

JSON conforme especificação Konduto para notificações de pedido / transação utilizadas pelo conector Uappi.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/anti-fraud/webhook/konduto' \
3  --header 'Content-Type: application/json' \
4  --data '{ }'

✅ Resposta de Sucesso

HTTP Status: 200 OK com JSON resultante do pipeline de webhook (confirmação ou corpo de erro de negócio serializado, conforme o caso).

⚠️ Possíveis erros:

⚠️ Nota de implementação (borda)

Ver nota nas páginas de webhook ClearSale: validar middleware, IP e contrato com o time de plataforma antes de depender desta URL em integrações críticas.