API HTTP/JSON (Rust + axum) para os Web Services do SEI.
Consultas read-only de processos, documentos e andamentos — em JSON limpo.

A eusei traduz os Web Services SOAP do SEI (Sistema Eletrônico de Informações) em JSON. Roda em um servidor com acesso liberado ao SEI e espelha as consultas do pacote R rsei. Atrás de um nginx, fica acessível em https://SEU-DOMINIO/eusei/.

Veja PLAN.md para a arquitetura e o roadmap.

Destaques

• Read-only completo: processos, documentos, publicações, blocos, andamentos e 15 listas auxiliares.
• Auto-contido: um binário único serve a API, a landing (Tailwind v4) e a documentação — sem CDN.
• Falha graciosa: erros com codigo estável e mensagens claras (incl. “SEI indisponível”).
• Seguro: Bearer token; a chave do SEI nunca é exposta ao cliente.

Instalação

Os artefatos saem prontos em cada release (o CI gera e anexa automaticamente nas tags v*):

Artefato	Para quê
eusei_<versão>_amd64.deb	Debian/Ubuntu amd64 (glibc ≥ 2.35) — produção
eusei-linux-x86_64	binário avulso (Ubuntu 22.04)
fórmula Homebrew	macOS/Linux (compila do fonte) — uso local/dev

1. Debian/Ubuntu — pacote .deb (recomendado)

# baixar o .deb da última release (precisa do gh CLI)
gh release download --repo StrategicProjects/eusei --pattern '*.deb'
# … ou baixe manualmente em /releases/latest

sudo apt install ./eusei_*_amd64.deb

O pacote, via postinst, cria o usuário de sistema eusei, gera /etc/eusei.env com um token aleatório (impresso uma vez) e habilita o serviço (sem iniciar). Em seguida:

sudo nano /etc/eusei.env      # defina SEI_IDENTIFICACAO_SERVICO (e SEI_URL/SIGLA se não for o PE)
sudo systemctl start eusei
curl -s http://127.0.0.1:18088/health

Conteúdo instalado: binário em /usr/bin/eusei, unit eusei.service, e os modelos eusei.env.example / eusei.nginx.conf em /usr/share/eusei/. Para expor publicamente, inclua o snippet do nginx (deploy/eusei.nginx.conf).

Atualizar: baixe o .deb novo e sudo apt install ./eusei_*_amd64.deb (o /etc/eusei.env é preservado). Remover: sudo apt remove eusei (ou purge).

2. Homebrew (macOS / Linux) — uso local/dev

brew tap StrategicProjects/eusei https://github.com/StrategicProjects/eusei
brew install eusei
EUSEI_TOKENS=meu-token SEI_IDENTIFICACAO_SERVICO=minha-chave eusei

A fórmula compila do fonte (precisa do Rust, instalado como dependência de build). É voltada a execução manual/dev — para servidor de produção, prefira o .deb.

3. Binário avulso

Baixe eusei-linux-x86_64 da release, coloque em /usr/local/bin/eusei, crie /etc/eusei.env (modelo em .env.example) e rode. O script deploy/02-deploy-sudo.sh automatiza usuário, env, systemd e o proxy nginx (defina EUSEI_NGINX_SITE).

Desenvolvimento

Só o servidor fala com o SEI e compila o binário Linux de destino. Ciclo:

# 1. editar local (mac)
# 2. sincronizar para o servidor — use SEMPRE caminho ABSOLUTO na origem;
#    com `./` e um cwd "sujo", o --delete pode apagar a pasta errada no destino.
rsync -az --delete --exclude target --exclude .git /caminho/abs/eusei/ servidor:~/eusei_dev/
# 3. no servidor
ssh servidor 'cd ~/eusei_dev && ~/.cargo/bin/cargo build && cp .env.example .env && ~/.cargo/bin/cargo run'

Configuração

Veja .env.example. Em produção, as variáveis vêm de /etc/eusei.env via systemd. A chave de acesso do SEI (SEI_IDENTIFICACAO_SERVICO) fica só no servidor e nunca é exposta ao cliente.

Funciona com qualquer instância do SEI. O endpoint, a sigla e a chave são 100% configuráveis (SEI_URL, SEI_SIGLA_SISTEMA, SEI_IDENTIFICACAO_SERVICO, SEI_ID_UNIDADE e SEI_SIP_*). Os defaults apontam para o SEI de Pernambuco, mas o envelope SOAP e as operações são padrão do SEI — basta apontar SEI_URL para outra instalação. Nada de específico do PE está embutido no código.

Autenticação

As rotas de dados /v1/* exigem Authorization: Bearer <token>, validado contra EUSEI_TOKENS (comparação em tempo constante). O nome do esquema é case-insensitive (Bearer/bearer). São públicas (sem token): /health, a landing (/), a documentação (/__docs__), o /openapi.json e os assets (CSS/fontes).

Uso

Base pública: https://SEU-DOMINIO/eusei/.

Importante: consulte processo/documento/bloco pela query string (?protocolo=...), não pelo path. A barra (/) do número do processo não sobrevive como %2F no path através do nginx; na query ela passa intacta.

# consultar um processo (forma recomendada)
curl -H 'Authorization: Bearer SEU-TOKEN' \
  'https://SEU-DOMINIO/eusei/v1/procedimento?protocolo=0011108545.000056/2022-49'

# listas
curl -H 'Authorization: Bearer SEU-TOKEN' \
  'https://SEU-DOMINIO/eusei/v1/paises'

Endpoints

Rota	Descrição
GET /health	liveness (sem auth)
GET /v1/procedimento?protocolo=	consulta um processo (flags sin_retornar_* opcionais)
GET /v1/procedimentos?protocolos=A,B	lote (cada item com dados/erro)
GET /v1/procedimento-individual?...	processo individual mais recente
GET /v1/documento?protocolo=	consulta um documento
GET /v1/publicacao?...	consulta publicação (id_publicacao/id_documento/protocolo_documento)
GET /v1/bloco?id=	consulta um bloco
GET /v1/andamentos?protocolo=	linha do tempo (fatiada em lotes; resposta inclui resumo)
GET /v1/andamentos/stream?protocolo=	mesma consulta via SSE (eventos progresso/concluido)
GET /v1/documentos-processo?protocolo=	documentos do processo (heurística da timeline)
GET /v1/publicacoes-processo?protocolo=	publicações do processo (heurística da timeline)
GET /v1/permissao?...	SIP — permissões (requer SEI_SIP_*)
GET /v1/{paises,estados,cidades,unidades,series,tipos-procedimento,...}	listas read-only

As variantes com path (/v1/procedimento/{protocolo}) existem para uso interno (127.0.0.1:18088), onde o %2F é preservado.

Campos derivados / extras: /v1/procedimento inclui concluido (true/false/null) derivado de UnidadesProcedimentoAberto; /v1/andamentos (e docs/publicações-processo) incluem um resumo dos lotes (lotes, registros, parciais).

Cache: respostas de /v1/* são cacheadas em memória (read-only) com single-flight e serve-stale quando o SEI cai. As respostas JSON trazem X-Cache: HIT|MISS|STALE|PARTIAL e Cache-Control/Age coerentes com o TTL; envie Cache-Control: no-cache para revalidar ou no-store para buscar fresco sem persistir. Ajustável por env (EUSEI_CACHE*, ver .env.example); /health expõe estatísticas do cache.

O endpoint SSE /v1/andamentos/stream é a exceção: por ser um fluxo de eventos, a resposta não carrega X-Cache/Cache-Control (o status do cache não é exposto por evento), mas ele respeita no-cache/no-store da requisição para revalidar/buscar fresco.

Formato da resposta

Sucesso devolve { ok, dados }, com os nomes originais do SEI (xsi:nil → null, arrays como listas JSON). Algumas rotas acrescentam campos derivados ao lado de dados (ex.: concluido em processos; resumo em andamentos). Abaixo, a estrutura de um processo:

Erros (falha graciosa)

Erros vêm como JSON { "ok": false, "codigo", "erro", "detalhe" } com o status HTTP apropriado. O campo codigo é estável para tratamento pelo cliente:

codigo	HTTP	Quando
nao_autorizado	401	token ausente/inválido
parametro_invalido	400	falta um parâmetro obrigatório
sei_fault	400	o SEI rejeitou (ex.: processo inexistente) — erro traz a mensagem do SEI
sei_indisponivel	503	SEI fora do ar / sem conexão (após 1 retentativa)
sei_timeout	504	o SEI demorou demais
sei_erro_http	502	o SEI respondeu HTTP de erro
resposta_invalida	502	resposta do SEI não pôde ser interpretada

Exemplo (SEI fora do ar):

{ "ok": false, "codigo": "sei_indisponivel",
  "erro": "O SEI está temporariamente indisponível. Não foi possível conectar ao servidor do SEI; tente novamente em alguns minutos.",
  "detalhe": null }

Frontend

• Landing: https://SEU-DOMINIO/eusei/ — página inicial em Tailwind CSS v4 (CSS gerado/tree-shaken e embutido no binário, sem CDN), com hero, início rápido e cards de endpoints.
• Referência: …/eusei/__docs__ — documentação custom em Tailwind v4 (cards por endpoint, diagramas SVG de fluxo e da resposta, navegação lateral).

Tudo é servido pelo próprio binário (Tailwind e fontes vendorizados, sem dependência de rede externa). O CSS do Tailwind (cobre index.html e docs.html) é regenerado com:

cd /tmp && npm i tailwindcss @tailwindcss/cli && \
  cp <repo>/static/{tw-input.css,index.html,docs.html} . && \
  npx @tailwindcss/cli -i tw-input.css -o tailwind.css --minify && \
  cp tailwind.css <repo>/static/tailwind.css

Como citar

Se você usar o eusei em trabalho acadêmico, cite-o pelo seu registro no Zenodo. O concept DOI 10.5281/zenodo.21366552 sempre resolve para o último release; cada versão também tem o seu próprio DOI. O “Cite this repository” do GitHub lê o CITATION.cff (BibTeX/APA).

@software{leite_eusei,
  author    = {Leite, André},
  title     = {{eusei: an HTTP/JSON API (Rust + axum) for the SEI SOAP Web Services}},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21366552},
  url       = {https://github.com/StrategicProjects/eusei}
}