relatorios-sivwin 0.3.1

Consultas SQL reutilizaveis para o ecossistema SivWin/Otimiza.

Relatorios SivWin

Biblioteca Python para centralizar consultas SQL parametrizadas do ecossistema SivWin/Otimiza.

Instalacao

pip install relatorios-sivwin

O pacote requer Python 3.10 ou superior. O nome publicado usa hifen, mas o import Python usa underscore:

from relatorios_sivwin import FormaPagamento, RelatoriosSivWin

Dominios

RelatoriosSivWin organiza as consultas em cinco grupos:

• gerais: ARTs, declaracoes e relatorios transversais;
• servicos: servicos, inspecoes, escopos, normas e o relatorio completo;
• veiculos: consultas cadastrais e tecnicas por placa, chassi ou RENAVAM;
• pessoas: consulta por CPF/CNPJ;
• financeiro: consultas financeiras, inicialmente por nota fiscal.

relatorios = RelatoriosSivWin()

relatorios.servicos.relatorio_completo(
    inicio="2026-02-01",
    fim="2026-02-28",
)
relatorios.servicos.por_os(103167)
relatorios.servicos.por_ri(12345)
relatorios.servicos.por_placa("ABC-1D23")
relatorios.servicos.por_chassi("9BWZZZ377VT004251")
relatorios.servicos.ris_emitidos("2026-02-01", "2026-02-28")

relatorios.veiculos.por_placa("ABC-1D23")
relatorios.veiculos.por_chassi("9BWZZZ377VT004251")
relatorios.veiculos.por_renavam("00012345679")

relatorios.pessoas.por_cpf_cnpj("529.982.247-25")
relatorios.financeiro.por_os(103167)
relatorios.financeiro.por_nota_fiscal("12345")
relatorios.financeiro.por_periodo("2026-02-01", "2026-02-28")
relatorios.financeiro.por_forma_pagamento(
    "2026-02-01",
    "2026-02-28",
    FormaPagamento.PIX,
)

Cada metodo retorna um SQLQuery com SQL parametrizada, parametros normalizados, nome da consulta e aliases das colunas.

Os aliases seguem o padrao <entidade><eventoOuAtributo><tipo> em camelCase. Em relatorios de dominio especifico, a entidade principal mantem o prefixo do dominio, como pessoaNomeCompleto, pessoaCidadeNome, veiculoPlaca e veiculoMarcaModeloNome. Entidades relacionadas usam o papel que ocupam no relatorio, como contratanteCpfCnpj, proprietarioEmail e condutorCelularNumero.

Relatorio completo

O relatorio completo pertence ao dominio de servicos e combina fragmentos de servico, veiculo, pessoas e os dados financeiros diretamente associados ao servico. Ele e o consumidor mais abrangente dos fragmentos; consultas especificas usam somente os campos e JOINs necessarios.

consulta = relatorios.servicos.relatorio_completo(
    inicio="2026-02-01",
    fim="2026-02-28",
)

print(consulta.sql)
print(consulta.params)
print(consulta.columns)

Os principais timestamps da inspecao sao:

• inspecaoAberturaDataHora;
• inspecaoRegistradoDataHora;
• inspecaoConclusaoDataHora;
• inspecaoCorrecaoDataHora.

veiculoSituacaoNome representa o resultado do veiculo inspecionado, enquanto inspecaoSituacaoNome representa o estado da inspecao.

Os dados financeiros do relatorio completo se limitam a notaFiscalNumero, servicoValorBruto e servicoValorLiquido. Formas de pagamento e parcelas nao fazem parte dessa consulta, pois uma OS pode possuir varios lancamentos e eles alterariam indevidamente a quantidade de linhas por inspecao.

Relatorios financeiros

As consultas financeiras partem dos servicos e associam somente lancamentos do SIVWIN com Excluido = 0. Cada lancamento ativo gera uma linha; quando uma OS nao possui lancamento, ela ainda e retornada uma vez com os dados financeiros do lancamento nulos. As consultas podem ser filtradas por OS, nota fiscal, periodo de abertura da OS ou forma de pagamento dentro do periodo de entrada.

As primeiras colunas identificam a OS e o veiculo. Em seguida sao retornados a nota fiscal, os valores bruto e liquido do servico, os dados do lancamento, o contratante, os valores bruto e liquido do lancamento e a forma de pagamento. O contratante inclui contratanteId, contratanteNome, contratanteCpfCnpj, contratanteTelefoneNumero, contratanteCelularNumero e contratanteEmail. Parcelas permanecem identificadas individualmente por lancamentoReferencia e lancamentoVencimentoData.

por_forma_pagamento() aceita texto ou FormaPagamento. As formas padronizadas sao:

• FormaPagamento.CARTAO_CREDITO: CARTÃO DE CRÉDITO;
• FormaPagamento.CARTAO_DEBITO: CARTÃO DE DÉBITO;
• FormaPagamento.DINHEIRO: DINHEIRO;
• FormaPagamento.NOTA_FATURADA: NOTA FATURADA;
• FormaPagamento.PIX: PIX.

O relatorio por periodo considera a abertura da OS e inclui servicos com inspecoes ativas, aprovadas, reprovadas, corrigidas ou reprovadas pelo SISCSV. Inspecoes apenas canceladas ou vencidas nao participam desse recorte.

Caracteristicas veiculares

Os dados tecnicos priorizam SivWin_CaracteristicasSerpro. Quando um campo esta nulo ou vazio, a consulta usa o valor equivalente de Caracteristicas. O fallback ocorre campo a campo, atendendo tambem veiculos de laudos SISLIT.

Placa, chassi e RENAVAM sao retornados sem mascara. O RENAVAM e preenchido com zeros a esquerda ate 11 posicoes.

Os relatorios de veiculos tambem retornam os dados basicos do proprietario: proprietarioNome, proprietarioCpfCnpj, proprietarioTelefoneNumero, proprietarioCelularNumero e proprietarioEmail. O vinculo do proprietario e feito com LEFT JOIN, preservando o veiculo mesmo quando o cadastro vinculado estiver ausente.

Validacao

• CPF e CNPJ aceitam valores com ou sem mascara e sao validados por digito;
• placas aceitam os formatos antigo e Mercosul;
• RENAVAM aceita mascara, recebe zeros a esquerda e tem o digito validado;
• chassi e normalizado sem impor a regra moderna de VIN com 17 caracteres;
• periodos aceitam date ou texto YYYY-MM-DD e usam os argumentos inicio/fim;
• OS e RI devem ser inteiros positivos.

Entradas invalidas geram TypeError ou ValueError antes da execucao SQL.

Execucao com cursor

O pacote nao gerencia conexoes ou credenciais. Uma consulta pode ser executada com qualquer cursor DB-API compativel:

from relatorios_sivwin import RelatoriosSivWin, fetch_all

relatorios = RelatoriosSivWin()
consulta = relatorios.servicos.por_os(103167)

with connections["otimiza"].cursor() as cursor:
    dados = fetch_all(cursor, consulta)

Tambem e possivel executar diretamente:

cursor.execute(consulta.sql, consulta.params)
linhas = cursor.fetchall()

Banco para inspecao da SQL

O banco padrao usado por to_sql_raw() e otimiza:

relatorios = RelatoriosSivWin(database="sivwin_homolog")
consulta = relatorios.servicos.por_os(103167)

print(consulta.to_sql_raw())

O nome do banco nao e incorporado ao SQL executado; ele serve apenas para a representacao bruta destinada a inspecao e depuracao.

Evolucoes futuras

Os seguintes pontos ficam registrados para uma versao posterior:

• tornar servicos.por_ri() deterministicamente limitado a ultima inspecao aprovada ou corrigida;
• revisar os relatorios que usam ROW_NUMBER() diante de relacionamentos 1:N, selecionando primeiro a inspecao e compondo os demais fragmentos depois;
• executar uma validacao integrada de todas as consultas no SQL Server real;
• confirmar o mapeamento completo dos campos equivalentes entre SivWin_CaracteristicasSerpro e Caracteristicas.

Mudancas da versao 0.3.1

• o relatorio completo deixou de consultar formas de pagamento e parcelas;
• notaFiscalNumero, servicoValorBruto e servicoValorLiquido foram preservados;
• os lancamentos financeiros nao multiplicam mais as linhas das inspecoes no relatorio completo;
• foram adicionadas consultas financeiras por OS, nota fiscal, periodo de abertura da OS e forma de pagamento;
• FormaPagamento foi adicionado para padronizar os filtros de forma de pagamento;
• os relatorios financeiros retornam documento e contatos do contratante;
• os relatorios de veiculos retornam documento e contatos do proprietario;
• o alias pessoaNome foi substituido por pessoaNomeCompleto;
• consultas por OS, nota fiscal e periodo preservam servicos sem lancamento, mantendo disponiveis os valores bruto e liquido do servico;
• o relatorio de declaracoes deixou de consultar formas de pagamento, evitando multiplicacao por parcelas ou pagamentos mistos.

Mudancas da versao 0.3.0

A versao 0.3.0 nao mantem aliases de compatibilidade da serie 0.2.x:

• start e end foram substituidos por inicio e fim;
• relatorios_gerais e relatorios_servicos foram removidos;
• os grupos veiculos, pessoas e financeiro foram adicionados;
• o relatorio completo passou a ser composto por fragmentos de dominio;
• os aliases de status e timestamps seguem a nova semantica da inspecao.