> 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/sdks/backend-sdk/iad/release_notes/2.0.0_release_notes.md).

# 2.0.0

**Data de lançamento:** 25 de maio de 2026

## Visão geral

**Facephi IAD Service 2.0.0** é uma versão principal que introduz um novo contrato REST público para os fluxos de avaliação e extração. Esta versão **não é retrocompatível** com a série 1.x.x.

## Alterações incompatíveis

### Alterações nos endpoints públicos

| Endpoint 1.x.x                   | Endpoint 2.0.0                       |
| -------------------------------- | ------------------------------------ |
| `POST /api/v1/iad/check-capture` | `POST /api/v1/iad/liveness/evaluate` |
| `POST /api/v1/iad/extract-image` | `POST /api/v1/iad/extract`           |

### Alterações no contrato multipart

* As solicitações multipart agora exigem o campo `capture`.
* As solicitações que incluem apenas o campo legado `file` sem `capture` são rejeitadas.

### Alterações no payload de sucesso

* Os payloads públicos de sucesso agora expõem campos no estilo Facephi, como `diagnostic`, `reason`, `probability`, `score`, `faceProbability`, `sdkDuration` e `queueDuration`.
* Os campos legados no formato do Engine, como `capture_liveness`, `capture_type`, `rejection` e `mime_type`, não são mais retornados nas respostas públicas de sucesso.

## Novidades

### Normalização do contrato público

* As respostas de avaliação são mapeadas para um contrato público estável, centrado nos campos de integração da Facephi.
* Os valores públicos de `reason` são documentados explicitamente como `None`, `Unknown`, `UntrustedEnvironment`, `SuspiciousActivity`, `UntrustedDevice`, `SdkIntegrityViolation`, `UntrustedCorruptedPayload`, `UntrustedContent` e `UntrustedContentLowConfidence`.
* Os erros de validação da captura são normalizados para valores no estilo Facephi/SelphID.

### Mitigação experimental de ataques de repetição (replay)

* O serviço pode aplicar uma janela de validade (freshness window) aos payloads de captura recebidos.
* As variáveis de ambiente de inicialização `FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED` e `FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME` ativam e configuram o recurso.
* A janela de validade padrão é de `300` segundos.
* Quando a janela de validade é excedida, os endpoints de processamento de capturas retornam HTTP `400` com `message` igual a `Replay attack detected`.

### Confiabilidade e comportamento em tempo de execução

* As falhas na inicialização do serviço são propagadas para `main` em vez de encerrar a execução dentro dos componentes internos de inicialização.
* O tratamento de sinais não realiza mais operações não seguras para sinais, como logging, lógica de desligamento ou `std::exit`, diretamente nos handlers.

### Garantia da qualidade

* Foram adicionados testes unitários para o mapeamento do payload de sucesso público e a prevenção de vazamento de campos privados.
* Foram adicionados testes unitários para verificar o comportamento do campo multipart obrigatório `capture`.

## Guia de migração (da versão 1.x.x)

1. Atualize as rotas dos endpoints nas integrações do cliente.
2. Renomeie o campo do formulário multipart de `file` para `capture`.
3. Atualize a análise das respostas para que as solicitações de avaliação bem-sucedidas usem os novos campos públicos.
4. Valide o comportamento da integração com `GET /api/v1/iad/version` e os testes de ponta a ponta no seu ambiente.

## Implantação

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.0.0

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.0.0
```

## Requisitos

| Componente          | Requisito                                |
| ------------------- | ---------------------------------------- |
| Sistema operacional | Linux x86\_64 (Ubuntu 24.04 recomendado) |
| Licença             | Arquivo de licença válido da Facephi     |
| Docker              | Para implantação em contêineres          |

## Suporte

Para obter Suporte Técnico, entre em contato com seu representante da Facephi.

## Documentação

* [Referência de configuração](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/iad.md)
* [Guia de instalação](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/iad/installation/installation_instructions.md)
* [Referência da API](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/iad/technical_documentation/api_reference.md)
* [Registro de alterações](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/iad/changelog.md)
