Confirmação de fraude

Se, após uma revisão posterior, for confirmado que uma transação específica correspondia a uma tentativa de fraude, o consumer pode notificar o serviço. Essas informações reforçam futuras detecções sobre o mesmo documento ou identidade. Esta etapa é opcional.

Endpoint

POST /document/validate/fraud-report

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de consumer no formato Bearer <token> (veja Autenticação).
consumer-id	string	Sim	Identificador do consumer.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
transactionId	string	Sim	Identificador da transação de validação que é confirmada como fraude.
categories	array	Sim	Uma ou mais categorias da fraude detectada. Cada valor deve pertencer ao catálogo de categorias válidas (veja abaixo).
comment	string	Não	Comentário livre, máx. 500 caracteres.

Categorias válidas

O campo categories aceita apenas os seguintes códigos:

Código	Descrição
document_is_manipulated	O documento está manipulado.
document_shown_from_screen	O documento é mostrado em uma tela.
document_is_printed_copy	O documento é uma cópia impressa.
selfie_shown_from_screen	A selfie é mostrada em uma tela.
selfie_is_manipulated	A selfie está manipulada.
selfie_document_portrait_mismatch	A selfie não corresponde ao retrato do documento.
injected_media	O conteúdo (imagem/vídeo) foi injetado.

Esta lista reflete o catálogo vigente no momento da publicação deste guia. O serviço valida as categorias em relação ao catálogo atualizado; envie apenas os códigos desta tabela.

Exemplo de solicitação

{
  "transactionId": "1c7d...e9",
  "categories": ["document_is_manipulated", "selfie_is_manipulated"],
  "comment": "Confirmado como fraude após revisão interna"
}

Respostas

200 Sucesso

{
  "accepted": true
}

Todas as ações aplicáveis da confirmação foram registradas corretamente. Isso inclui o enrolamento do rosto nas blocklists aplicáveis (veja abaixo). A operação é idempotente: se o rosto já estava em uma blocklist, ou se a transação já havia sido reportada anteriormente, a nova tentativa é considerada igualmente um sucesso e retorna 200.

400 Requisição inválida

Alguma das categories enviadas não pertence ao catálogo de categorias válidas. Nenhuma ação é registrada; corrija as categorias e tente novamente.

401 Não autorizado

Token ausente, inválido ou expirado.

403 Proibido

O consumer não está provisionado com o serviço DOCUMENT_ANTIFRAUD.

404 Não encontrado

A transação indicada não existe.

422 Entidade não processável

A transação não admite reporte: só são admissíveis transações finalizadas em estado COMPLETED.

429 Muitas solicitações

O consumer ultrapassou seu limite de taxa de requisições. A resposta inclui Retry-After com os segundos de espera, e X-RateLimit-Limit e X-RateLimit-Burst com os limites vigentes. Nenhuma ação é registrada.

503 Serviço indisponível

Alguma das ações aplicáveis da confirmação não pôde ser concluída. A confirmação não é considerada plenamente registrada; o consumer deve tentar novamente mais tarde ou, se o problema persistir, notificá-lo ao suporte informando o transactionId. A operação é idempotente, portanto tentar novamente é seguro.

Blocklists de rostos

Quando a transação confirmada como fraude inclui selfie, o rosto é enrolado nas blocklists aplicáveis, de forma que futuras validações o detectem (códigos 200/201, ver resposta de resultado):

• Blocklist da plataforma: o rosto é sempre enrolado na blocklist própria da plataforma.

• Blocklist global: além disso, se a plataforma participa da blocklist global compartilhada, o rosto também é enrolado nela.

A participação na blocklist global é acordada com Facephi na contratação do serviço e não é controlada pela API. Seu escopo é simétrico: aplica-se tanto à busca durante a validação quanto ao enrolamento nesta confirmação de fraude. Se a transação foi processada sem selfie (sem TOKEN_FACE_IMAGE), nenhum rosto é enrolado em nenhuma blocklist.

Recomenda-se enviar um único relato de fraude por transação. No entanto, tentar novamente é seguro: a operação é idempotente e um relato já registrado retorna 200 sem duplicar efeitos.