PyAria

Introdução

Biblioteca Python para integração com o ecossistema ARIA (APIs corporativas, Persona, SEI, SIAFI etc.). Fornece:

  • Cliente genérico Aria para qualquer endpoint cadastrado

  • Suporte a autenticação com token (cache e renovação)

  • Suporte a OTP (one-time password) em modos manual e interativos (console e janela Tkinter)

  • Paginação automática transparente (auto_pagination=True)

  • Wrappers especializados: Persona, Sei, Siafi e ChatLogos

  • Conversão de modelos (SIAFI) entre snake_case e camelCase

Documentação gerada: https://cdn.tesouro.gov.br/doc/pyarialib/

Instalação

Via repositório Nexus privado:

pip install -i https://nexus.tesouro.gov.br/repository/pypi-private/simple pyarialib

Requer Python 3.6+ (recomenda-se 3.10+).

Atualizar / Publicar nova versão

  1. Ajuste a versão em setup.py (version="X.Y.Z").

  2. Commit / push para o branch que dispara o pipeline.

  3. O CI/CD empacota e publica no Nexus.

Sugestão de versionamento: Semantic Versioning (MAJOR.MINOR.PATCH).

Uso Básico (Cliente Genérico)

Crie uma instância de Aria informando credenciais:

from pyarialib import Aria

aria = Aria("usuario", "senha")

resposta = aria.request(
	method='get',
	version=1,
	project='corporativo',
	endpoint='uf',
	query_string_params={'sg_uf': 'DF'}
)

dados = resposta.json()
print(dados)

Enviar corpo (string) ou JSON:

resposta = aria.request(
	'post', 1, 'corporativo', 'uf',
	headers={'Content-Type': 'application/json'},
	json_body={'campo1': 'valor1'}
)

Resposta:

resposta.json()   # dict
resposta.text()   # string (texto cru)
resposta.status_code  # HTTP status

Paginação Automática

Se o endpoint seguir o padrão (page, pageSize, registros), ative:

resposta = aria.request('get', 1, 'sei', 'admin/modelosHtml', auto_pagination=True)
todos = resposta.json()['registros']

OTP (One-Time Password)

Modos disponíveis:

Modo

Comportamento

manual

Envia type/value/flow_id (se fornecidos) em uma única chamada

interactive-console

2 etapas: obtém flowId e solicita código no console

interactive-window

Igual ao anterior, mas janela GUI (Tkinter). Fallback para console se indisponível

 
from pyarialib import Aria, Otp

aria = Aria("user", "senha")

# Modo manual (já tenho código)
otp = Otp(type='webauthn2steps', value='123456')
res = aria.request('get', 1, 'projeto', 'endpoint', otp=otp)

# Modo interativo console
otp = Otp(type='webauthn2steps', mode='interactive-console')
res = aria.request('get', 1, 'projeto', 'endpoint', otp=otp)

# Modo interativo janela
otp = Otp(type='webauthn2steps', mode='interactive-window')
res = aria.request('get', 1, 'projeto', 'endpoint', otp=otp)

Em fluxos interativos: a primeira requisição devolve flowId; o usuário informa o código na segunda etapa.

Persona (Recursos de RH / Estrutura Organizacional)

from pyarialib import Aria

aria = Aria("user", "senha")
persona = aria.get_persona()

col = persona.get_colaborador(cpf=12345678900, inclui_funcoes=True)
print(col['nome'])

uorg = persona.get_uorg(sigla='COGEP', inclui_subuorgs=True)
print(uorg['sigla'])

Parâmetros booleanos adicionam seções opcionais (funções, dependentes, frequência etc.).

SEI (Modelos, Procedimentos, Documentos)

from pyarialib import Aria

aria = Aria("user", "senha")
sei = aria.get_sei()

modelos = sei.get_modelos_html(id_unidade_stn=1)
for m in modelos:
	print(m['idModeloHtml'], m['nome'])

proc = sei.gerar_procedimento(id_tipo_procedimento=100000206)
codigo_proc = proc['codigoProcedimentoSei']

doc_html = sei.gravar_documento_html(
	codigo_procedimento_sei=codigo_proc,
	descricao="Documento Teste",
	id_serie_sei=1247,
	html="<p>Teste</p>"
)
print("Documento HTML criado:", doc_html)

Para anexar arquivo binário (ex.: PDF) use gravar_documento_arquivo.

SIAFI (Operações Financeiras / Tabelas)

O wrapper Siafi abstrai conversão de campos e OTP automático em operações mutáveis.

from pyarialib import Aria
from pyarialib import Siafi  # também acessível via aria.get_siafi() se exposto
from pyarialib.siafi import TabAlterarChavesPixRequestModel, Otp

aria = Aria("user", "senha")
siafi = Siafi(aria, ug="160001", env="siafi2025")

resp = siafi.consultar_ug(codigo_ug="160001")
print(resp)

payload = TabAlterarChavesPixRequestModel(
	credor="12345678901",
	chaves_pix=["chave@dominio"]
)
resultado = siafi.alterar_chaves_pix(payload, otp=Otp(type='webauthn2steps', mode='interactive-console'))
print(resultado)

Em métodos POST/PUT/DELETE o OTP default (webauthn2steps, janela) é aplicado se não for informado.

Tratamento de Erros

  • Erros HTTP retornam AriaResponse.status_code (cliente genérico) ou geram ValueError em wrappers (Siafi, Sei).

  • Em OTP interativo, cancelar a janela/entrada aborta antes da segunda chamada (sem código definido).

Exemplo simples:

try:
	resposta = aria.request('get', 1, 'corporativo', 'uf', query_string_params={'sg_uf': 'XX'})
	dados = resposta.json()
except Exception as e:
	print("Falha:", e)

Boas Práticas

  • Reutilize a mesma instância Aria para aproveitar cache de token.

  • Use auto_pagination=True apenas quando realmente precisar de todos os registros.

  • Prefira json_body em vez de body para conteúdo JSON (define Content-Type automaticamente).

  • Em ambientes sem interface gráfica use interactive-console.

Roadmap (Sugestões)

  • Expor método helper aria.get_siafi() (se ainda não disponível publicamente)

  • Tipagem de retorno unificada em AriaResponse

  • Logging estruturado (opcional)

  • Retries configuráveis para erros transitórios

Contribuindo

  1. Crie branch de feature (feat/nome)

  2. Adicione testes (quando aplicável)

  3. Atualize README / docs Sphinx se necessário

  4. Abra Pull Request

Licença

MIT (ver setup.py).

Referência Rápida

Objeto

Propósito

Aria

Cliente genérico de requisições

Otp

Suporte a modos manual e interativos de OTP

Persona

Dados de colaboradores e UORGs

Sei

Modelos, procedimentos e documentos SEI

Siafi

Operações e tabelas SIAFI (financeiro)

ChatLogos

Integração conversacional (detalhes no código)

Em caso de dúvidas consulte a documentação completa ou abra uma issue.