> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/confirmacion-de-fraude.md).

# 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 notificá-lo ao serviço. Essas informações reforçam detecções futuras 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>` (ver [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md)). |
| **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 (UUID) da transação de validação que é confirmada como fraude, conforme retornado por `POST /document/validate`. |
| `categories`    | array  | **Sim**     | Uma ou mais categorias da fraude detectada. Cada valor deve ser um dos **valores permitidos** (veja abaixo).                   |
| `comment`       | string | Não         | Comentário livre, máx. 500 caracteres.                                                                                         |

#### Categorias válidas

O campo `categories` aceita apenas os seguintes valores:

| Valor                      | Descrição                                         |
| -------------------------- | ------------------------------------------------- |
| `DOCUMENT_MANIPULATED`     | O documento está manipulado.                      |
| `DOCUMENT_ON_SCREEN`       | O documento é exibido em uma tela.                |
| `DOCUMENT_PRINTED_COPY`    | O documento é uma cópia impressa.                 |
| `SELFIE_ON_SCREEN`         | A selfie é exibida em uma tela.                   |
| `SELFIE_MANIPULATED`       | A selfie está manipulada.                         |
| `SELFIE_DOCUMENT_MISMATCH` | A selfie não corresponde ao retrato do documento. |
| `INJECTED_MEDIA`           | O conteúdo (imagem/vídeo) foi injetado.           |

{% hint style="info" %}
O campo `categories` aceita exatamente os valores desta tabela. Qualquer outro valor é rejeitado com `400` e nenhuma ação é registrada.
{% endhint %}

#### Exemplo de solicitação

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

### Respostas

#### `200` Sucesso

```json
{
  "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 registrada anteriormente, a nova tentativa é considerada igualmente um sucesso e retorna `200`.

#### `400` Requisição inválida

A solicitação não é válida: falta `transactionId` ou não tem formato de UUID, `categories` está vazio ou contém um valor não permitido (veja **Categorias válidas**), ou `comment` ultrapassa os 500 caracteres. Nenhuma ação é registrada; corrija a solicitação 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`, ou o consumer ou sua plataforma estão inativos, expirados ou desativados.

#### `404` Não encontrado

A transação indicada não existe ou pertence a outro consumer.

#### `422` Entidade não processável

A transação não admite relatório: somente são admitidas transações finalizadas no estado `COMPLETED`.

#### `429` Muitas requisiçõ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. A operação é idempotente, portanto tentar novamente é seguro.

Nem todas as causas se resolvem tentando novamente: algumas exigem intervenção da Facephi. Se a nova tentativa continuar retornando `503`, **notifique o suporte** informando o `transactionId`.

O corpo de uma resposta de erro tem a forma descrita em [MIDAPI v2](/docs.facephi-pt-br/api-rest/midapi-v2.md#respuestas-de-error).

### Blocklists de rostos

Quando a transação confirmada como fraude inclui selfie, seu rosto é enrolado nas blocklists aplicáveis, de forma que validações futuras o detectem (códigos `200`/`201`, veja [resposta de resultado](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md)):

* **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.

{% hint style="info" %}
A participação na **blocklist global** é acordada com Facephi na contratação do serviço e não é controlada pela API. **Por padrão, a plataforma participa**; se não quiser participar, informe isso na contratação. Seu alcance é 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.
{% endhint %}

{% hint style="info" %}
Recomenda-se enviar um único relatório de fraude por transação. No entanto, tentar novamente é **seguro**: a operação é idempotente e um relatório já registrado retorna `200` sem duplicar efeitos.
{% endhint %}