validar-iti

API e cliente Python não oficial para validar assinaturas de PDFs pelo ITI VALIDAR.

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

pip install validar-iti

Para desenvolvimento local:

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

Subir a API

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

Em desenvolvimento:

validar-iti serve --reload

Endpoints

Validar um PDF

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

Validar múltiplos PDFs

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

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

Healthcheck

curl http://127.0.0.1:8000/health

Uso como cliente 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:

{
  "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

python -m pytest

Teste real opcional contra o VALIDAR:

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

Licença

MIT