inter-pj v0.4.0

Pagamentos: boletos, contas e tributos, DARF e lotes, com os trilhos de segurança do Pix.

Adicionado

• inter-pj pagamento boleto pagar <codigo>: paga ou agenda (--data) boletos, contas de consumo e tributos pela linha digitável ou pelo código de barras, conferidos localmente. Valor e vencimento vêm do código quando ele os traz, e o resumo avisa, mostrando os dois lados, quando --valor ou --vencimento diferem dele, e também quando o pagamento fica para depois do vencimento; --beneficiario pede à API que confira o CPF/CNPJ de quem recebe. Mesmos trilhos do Pix: confirmação, --sim, --simular e limite_por_operacao. Como a API não tem chave de idempotência, um resultado incerto sai com o código 9 e vem com o comando que confere o pagamento antes de repeti-lo, na mesma conta (com -p, --config, --ambiente e as demais opções da linha de comando que escolheram a conta) e com o aviso de que uma lista vazia logo depois do erro não prova que nada foi pago (#23, #336).
• inter-pj pagamento boleto listar: pagamentos por código de barras de um período (até 90 dias; padrão: incluídos nos últimos 30 dias), por data de inclusão, pagamento ou vencimento (--filtrar-por), código (--codigo) ou transação (--codigo-transacao), em texto, JSON ou CSV (#24).
• inter-pj pagamento boleto cancelar <codigo-transacao>: cancela um agendamento depois de mostrá-lo (beneficiário, valor, data e status) e pedir confirmação; sem terminal, exige --sim e não faz nenhuma requisição (#24).
• inter-pj pagamento darf pagar: DARF sem código de barras pelas opções ou por --arquivo (JSON com os campos da API, ou - para a entrada padrão), validado localmente com mensagens que apontam o campo; campos desconhecidos no arquivo são recusados. O resumo mostra principal, multa, juros e o total por extenso, e avisa sobre DARF vencido sem acréscimos. Mesmos trilhos dos demais pagamentos. Misturar --arquivo com uma opção do DARF, ou dar uma opção sem as outras, é recusado com o que fazer (--multa vai em valorMulta no arquivo). Os textos da resposta aparecem sem quebras de linha nem caracteres de controle (#25, #355, #360).
• inter-pj pagamento darf listar: DARFs pagos em um período, ou incluídos nos últimos 30 dias, por código da receita ou da solicitação, em texto, JSON ou CSV; o CSV mostrado no terminal passa pelo filtro da saída em texto (#25, #355).
• inter-pj pagamento lote enviar --arquivo: lotes de 2 a 150 boletos, contas, tributos e DARFs a partir de um arquivo JSON (os campos da API, com tipoPagamento) ou de uma planilha CSV (, ou ;, com ou sem BOM, como o Excel salva). O lote inteiro é conferido antes do envio, e todos os problemas são listados com a linha ou a posição e o campo, sem enviar nada; o resumo mostra os totais por tipo, cada pagamento e avisos (vencimentos passados, valores diferentes dos do código). Pagamentos repetidos no arquivo (o mesmo código, ou o mesmo DARF) são recusados, porque com --sim um aviso não impediria o pagamento em dobro; --permitir-repetidos os aceita. Mesmos trilhos dos demais pagamentos; os comandos sugeridos levam as opções que escolheram a conta (#26, #372, #381).
• inter-pj pagamento lote consultar <id-lote>: status do lote e de cada pagamento; com --aguardar [--timeout 5m], decide pelo status de cada pagamento: sai com 0 quando todos foram pagos ou agendados (avisando dos agendados), 5 quando algum não foi feito ou tem um status desconhecido, e 8 quando o tempo acabou com o lote em processamento ou com pagamentos aguardando aprovação. Uma consulta que falha durante a espera (429, 5xx, rede) não a interrompe (#26, #369, #376).
• inter-pj pagamento lote modelo [json|csv]: arquivos de exemplo com dados fictícios e os códigos de teste do sandbox. No CSV, as células que o Excel estraga ao abrir o arquivo (números longos em notação científica, códigos da receita sem o zero à esquerda) são recusadas com a explicação (#26).
• Biblioteca: boleto::CodigoBarras valida e decodifica localmente a linha digitável (47 dígitos para boletos, 48 para contas e tributos) e o código de barras (44 dígitos): dígitos verificadores (módulos 10 e 11), conversão entre linha e código, banco, segmento, valor e vencimento, considerando o reinício do fator de vencimento em 22/02/2025 (#23).
• Biblioteca: Banking::pagar_boleto (boletos, contas e tributos com código de barras, com validação local do valor), Banking::pagamentos (filtros por período, tipo de data, código e transação) e Banking::cancelar_pagamento (agendamentos) (#23, #24).
• Biblioteca: Banking::pagar_darf (DARF sem código de barras, com validação local do código da receita, da referência, dos textos e dos valores; PagamentoDarfError::campo diz qual campo falhou) e Banking::darfs (filtros por período, código da receita e solicitação) (#25).
• Biblioteca: Banking::enviar_lote (lotes de 2 a 150 boletos e DARFs, validados item a item) e Banking::consultar_lote (status do lote e de cada pagamento) (#26).
• Biblioteca: Error::may_have_been_processed diz se uma operação pode ter sido processada apesar do erro (só depois que a requisição dela foi enviada), para quem decide se pode repeti-la (#338).

Alterado

• limite_por_operacao vale também para os pagamentos: boletos, DARFs e cada pagamento de um lote.
• Os códigos de saída 5 e 8 valem também para pagamento lote consultar --aguardar (algum pagamento não foi feito; tempo esgotado, também com pagamentos aguardando aprovação).
• Novo código de saída 9: um envio cujo resultado ficou incerto (tempo esgotado, erro 5xx, resposta ilegível depois do envio) sai com ele, e não mais com 6 ou 1, para que um script distinga "pode ter sido feito, confira" de "não foi feito, pode repetir" (um 429 ou uma conexão recusada continuam com 6). Vale para os pagamentos e para pix enviar. Uma falha ao pedir o token de acesso não é mais tomada por um envio incerto, porque nada foi enviado (#335, #338).
• Biblioteca: as falhas de rede do pedido do token de acesso são Error::TokenTransport, e não mais Error::Transport, que fica para as da própria operação (#338).
• Os erros de uso (uma opção desconhecida, um valor inválido, opções que não combinam, um argumento que falta) saem em português, como todas as outras mensagens, com as mesmas dicas e a linha de uso; o clap os escrevia em inglês. O código de saída continua 2 (#360).

Corrigido

• As datas seguem o calendário do banco: "hoje" é o dia em Brasília, qualquer que seja o fuso da máquina, em pagamento boleto pagar (agendamento, data passada, aviso de vencimento), nos períodos padrão das listagens e em pix enviar. Num servidor em UTC perto da meia-noite, um agendamento para amanhã era tomado por um pagamento de hoje e pago na hora (#337).
• A saída em texto troca por � os caracteres de controle vindos da API (nomes, descrições, status, mensagens de erro): as sequências de escape não chegam mais ao terminal, onde poderiam reescrever a tela, e uma quebra de linha num campo do extrato ou das consultas não simula mais uma linha. O filtro tem limites: as mensagens de erro da API ainda podem ocupar mais de uma linha, e os caracteres que invertem ou escondem texto (bidirecionais, de largura zero) não são trocados. O JSON continua com o texto exato; o CSV também, salvo o apóstrofo que protege as planilhas de fórmulas (#403).