Metadata-Version: 2.4
Name: validar-iti
Version: 1.0.0
Summary: API e cliente Python não oficial para validar assinaturas de PDFs pelo ITI VALIDAR.
Project-URL: Repository, https://github.com/marcoantonioamorelli/validar-iti-api
Project-URL: Issues, https://github.com/marcoantonioamorelli/validar-iti-api/issues
Author: Marco Antonio Amorelli
License-Expression: MIT
License-File: LICENSE
Keywords: assinatura-digital,govbr,iti,pdf,validar
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Requires-Dist: fastapi<1.0,>=0.111
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic-settings<3.0,>=2.2
Requires-Dist: python-multipart<1.0,>=0.0.9
Requires-Dist: uvicorn[standard]<1.0,>=0.30
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.2; extra == 'dev'
Requires-Dist: respx<1.0,>=0.21; extra == 'dev'
Requires-Dist: twine<7.0,>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# validar-iti

API e cliente Python não oficial para validar assinaturas de PDFs pelo
[ITI VALIDAR](https://validar.iti.gov.br/).

O projeto não implementa um verificador criptográfico próprio. Ele envia PDFs
ou URLs para os endpoints públicos usados pelo site do VALIDAR e normaliza a
resposta em JSON simples para uso em sistemas.

## Aviso

Este projeto não é oficial, não é mantido pelo ITI e não tem relação com o
Gov.br. O serviço VALIDAR não publica esses endpoints como API pública estável,
então o contrato pode mudar.

## Instalação

```bash
pip install validar-iti
```

Para desenvolvimento local:

```bash
python -m pip install -e ".[dev]"
```

## Subir a API

```bash
validar-iti serve --host 127.0.0.1 --port 8000
```

Em desenvolvimento:

```bash
validar-iti serve --reload
```

## Endpoints

### Validar um PDF

```bash
curl -F "file=@documento_assinado.pdf;type=application/pdf" \
  http://127.0.0.1:8000/validate/file
```

### Validar múltiplos PDFs

```bash
curl \
  -F "files=@um.pdf;type=application/pdf" \
  -F "files=@dois.pdf;type=application/pdf" \
  http://127.0.0.1:8000/validate/files
```

### Validar URL

```bash
curl -X POST http://127.0.0.1:8000/validate/url \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/documento.pdf"}'
```

### Healthcheck

```bash
curl http://127.0.0.1:8000/health
```

## Uso como cliente Python

```python
import asyncio
from validar_iti import ValidarClient


async def main():
    async with ValidarClient() as client:
        resultado = await client.validate_pdf("documento_assinado.pdf")
        print(resultado.valid)
        print(resultado.status_label)
        print(resultado.simple_report_text)


asyncio.run(main())
```

## Resposta

A API retorna campos estruturados e também `simple_report_text`, montado a partir
do relatório simples retornado pelo próprio VALIDAR.

Exemplo resumido:

```json
{
  "valid": true,
  "status": "approved",
  "status_label": "Aprovado",
  "report_source": "validar_simples",
  "file_name": "documento_assinado.pdf",
  "sha256": "...",
  "signatures": [
    {
      "signer_name": "NOME DO ASSINANTE",
      "authority": "Gov-Br",
      "cpf": "***.000.000-**",
      "status": "approved",
      "status_label": "Aprovado"
    }
  ]
}
```

## Configuração

Variáveis de ambiente:

- `VALIDAR_BASE_URL`, padrão `https://validar.iti.gov.br`
- `VALIDAR_TIMEOUT_SECONDS`, padrão `190`
- `VALIDAR_MAX_CONCURRENCY`, padrão `2`
- `MAX_UPLOAD_MB`, padrão `10`
- `MAX_BATCH_MB`, padrão `30`
- `MAX_FILES_PER_REQUEST`, padrão `10`
- `VALIDAR_PROXY_URL`, proxy HTTP(S) opcional para chamadas ao VALIDAR
- `VALIDAR_USE_SIMPLE_REPORT`, padrão `true`
- `USER_AGENT`, user-agent enviado ao VALIDAR

Quando `VALIDAR_USE_SIMPLE_REPORT=true`, o fluxo usa `/arquivo` ou `/url` e em
seguida `/simples`, que é a fonte dos dados da visão "Simples" do
`relatorio.html`.

Quando `VALIDAR_USE_SIMPLE_REPORT=false`, a biblioteca pula `/simples` e mapeia
localmente a resposta bruta para reduzir tráfego.

## Testes

```bash
python -m pytest
```

Teste real opcional contra o VALIDAR:

```bash
RUN_LIVE_VALIDAR_TESTS=1 python -m pytest tests/test_live_validar.py
```

## Licença

MIT
