Pular para conteúdo

Baixas, Retornos e Sincronizações

Objetivo

Documentar os fluxos de baixa de boletos, retorno de situação, sincronização de status e verificação automática de cobrança escritural.

Baixa de Boletos em Lote

Método: action_baixar_boletos() (linha 2020 de account.py)

Aspecto Detalhe
Endpoint POST /api/v1/boletos/baixa/lote
Payload Lista JSON de idintegracao
Autenticação Headers CNPJ + Token

Pré-requisitos

  • Parcela deve ter l10n_br_cobranca_idintegracao preenchido
  • Situação deve ser diferente de: REJEITADO, BAIXADO, LIQUIDADO

Fluxo

flowchart TD
    A["action_baixar_boletos()"] --> B["Filtra parcelas com idintegracao"]
    B --> C["Monta lista de idintegracoes"]
    C --> D{"Lista vazia?"}
    D -->|Sim| E["Retorna sem ação"]
    D -->|Não| F["POST /api/v1/boletos/baixa/lote"]
    F --> G{"_status == sucesso?"}
    G -->|Sim| H["Baixa aceita"]
    G -->|Não| I["UserError com mensagem"]

Consulta de Situação de Boletos

Método: action_boleto_nfe_situacao() (região linha ~2200)

Chamado automaticamente após geração de boletos e pelo cron de verificação.

Aspecto Detalhe
Endpoint GET /api/v1/boletos?situacao={situacao}&nossonumero={nossonumero} (ou similar)
Função Consulta status atualizado no banco

Status possíveis da parcela (l10n_br_cobranca_situacao)

Status Significado Ação do sistema
SALVO Registro salvo no integrador Aguarda processamento
PENDENTE_RETENTATIVA Pendente de retentativa Será reprocessado pelo cron
EMITIDO Boleto emitido Disponível para pagamento
REGISTRADO Registrado no banco Disponível para pagamento
REJEITADO Rejeitado pelo banco Necessita reprocessamento
LIQUIDADO Pago pelo sacado Concluído
BAIXADO Baixado pelo cedente Concluído

Verificação Automática (Cron)

Método: _check_boleto_naodisponivel() (linha 2188)

Aspecto Detalhe
Tipo Cron job (execução periódica)
Filtro Parcelas com situação SALVO, PENDENTE_RETENTATIVA, EMITIDO
Ação Chama action_boleto_nfe_situacao() para cada fatura 
# Filtro de busca
invoice_payments = self.env['account.move.line'].search([
    ('l10n_br_cobranca_situacao', 'in', ['SALVO','PENDENTE_RETENTATIVA','EMITIDO']),
    ('account_id.account_type', '=', 'asset_receivable'),
    ('date_maturity', '!=', False),
    ('l10n_br_cobranca_idintegracao', '!=', False)
])

Campos de Rastreamento na Parcela

Cada parcela (account.move.line) tem os seguintes campos de rastreamento de cobrança:

Campo Tipo Descrição
l10n_br_cobranca_parcela Integer Número sequencial da parcela
l10n_br_cobranca_nossonumero Char Nosso número gerado
l10n_br_cobranca_idintegracao Char ID de integração no PlugBoleto
l10n_br_cobranca_protocolo Char Protocolo de registro
l10n_br_cobranca_situacao Char Status atual (SALVO, EMITIDO, etc.)
l10n_br_cobranca_situacao_mensagem Char Mensagem de erro/retorno
l10n_br_cobranca_transmissao Char Tipo de transmissão (webservice, etc.)
l10n_br_cobranca_tipo_desconto Char Tipo de desconto configurado
l10n_br_cobranca_valor_desconto Float Valor do desconto
l10n_br_cobranca_data_desconto Date Data limite do desconto
l10n_br_cobranca_numero_cartao Char Número do cartão (para parcelas cartão)

Reprocessamento de Boletos Rejeitados

Fluxo em action_gerar_boleto_nfe() (linhas 2104-2112)

Quando uma parcela tem l10n_br_cobranca_situacao == 'REJEITADO':

  1. Gera novo nosso número (via sequência)
  2. Limpa campos: situacao, situacao_mensagem, idintegracao, protocolo
  3. Reprocessa com _gerar_cobranca_escritural()

Regra: O reprocessamento é automático ao clicar novamente em "Gerar Boleto".

Retorno de Sucesso vs. Falha na Geração

Dados de Sucesso

Quando _status == 'sucesso' e _dados._sucesso contém itens:

Campo retornado Destino Odoo
idintegracao l10n_br_cobranca_idintegracao
situacao l10n_br_cobranca_situacao
TituloNossoNumero Match para identificar parcela

Dados de Falha

Quando _dados._falha contém itens:

Campo retornado Destino Odoo
_dados.idintegracao l10n_br_cobranca_idintegracao
_dados.situacao l10n_br_cobranca_situacao
_erro.erros.boleto l10n_br_cobranca_situacao_mensagem

Parcela Única vs. Múltiplas

Regra especial: Se a fatura tem apenas uma parcela a receber: - O valor do boleto é amount_residual (saldo residual da fatura) - Em vez de debit da parcela - Isso garante que pagamentos parciais sejam corretamente refletidos

Troubleshooting

Problema Causa Solução
Boleto não aparece como EMITIDO Cron não executou Verificar cron _check_boleto_naodisponivel
Baixa não refletiu no Odoo Baixa no banco mas sem sync Executar action_boleto_nfe_situacao()
REJEITADO sem mensagem API retornou sem detalhes Verificar log do chatter da fatura
Nosso número não gerado Sequência sem próximo valor Verificar sequência l10n_br_nosso_numero_id
Parcela com status antigo Sem idintegracao Parcela nunca foi transmitida
Delay de 5s entre parcelas time.sleep(5) no código Comportamento intencional para evitar rate limit

Referências