Cobrança Escritural — Boletos (API TecnoSpeed PlugBoleto)¶

Objetivo¶

Documentar o fluxo de geração, transmissão, consulta, baixa e cancelamento de boletos de cobrança escritural via API TecnoSpeed PlugBoleto, com mapeamento campo a campo.

Visão Geral¶

A cobrança escritural é gerenciada pelo método _gerar_cobranca_escritural() (linha 1794 de account.py), que monta um payload JSON enviado à API PlugBoleto via POST /api/v1/boletos/lote.

Diferença fundamental: A cobrança escritural NÃO usa TX2. Usa JSON nativo via API REST do PlugBoleto.

Cadeia de Métodos¶

Método	Linha	Descrição
`action_gerar_boleto_nfe()`	2072	Orquestrador: gera nosso número, monta boletos, transmite
`_gerar_cobranca_escritural()`	1794	Monta o payload JSON de cada boleto
`_gerar_boleto()`	2017	Hook: retorna `True` por padrão (pode ser sobrescrito)
`_get_l10n_br_cobranca_id()`	1791	Hook: permite customizar o registro de cobrança
`action_baixar_boletos()`	2020	Solicita baixa em lote
`action_boleto_nfe_situacao()`	~2188	Consulta situação dos boletos
`_check_boleto_naodisponivel()`	2188	Cron: verifica boletos pendentes

Configuração da Cobrança¶

Onde configurar: O registro de cobrança (l10n_br_cobranca_id) é vinculado via: 1. Provedor de pagamento (payment_provider_id.l10n_br_cobranca_id) — prioridade 2. Condição de pagamento (invoice_payment_term_id.l10n_br_cobranca_id) — fallback

Campos de Configuração do Registro de Cobrança¶

Campo	Descrição	Usado como
`l10n_br_cedente_conta`	Conta do cedente	`CedenteContaNumero`
`l10n_br_cedente_conta_digito`	Dígito da conta	`CedenteContaNumeroDV`
`l10n_br_cedente_convenio`	Convênio	`CedenteConvenioNumero`
`l10n_br_cedente_banco`	Código do banco	`CedenteContaCodigoBanco`
`l10n_br_carteira`	Carteira/variação	`TituloVariacaoCarteira`
`l10n_br_tipo_cobranca`	Tipo de cobrança	`TituloTipoCobranca`
`l10n_br_nosso_numero_id`	Sequência nosso número	Gera sequencialmente
`l10n_br_transmissao`	Tipo transmissão	`webservice` ou outro
`l10n_br_url`	URL base API	Base URL do PlugBoleto
`l10n_br_token`	Token de autenticação	Header `token-cedente`
`l10n_br_especie`	Espécie do título	`TituloDocEspecie`
`l10n_br_hibrido`	Boleto híbrido (PIX+boleto)	`hibrido = True`
`l10n_br_cod_emissao_bloqueto`	Código emissão	`TituloCodEmissaoBloqueto`
`l10n_br_enviar_chave_nf`	Envia chave NF no boleto	Força inclusão de dados NF
`l10n_br_mensagem_pagamento`	Local de pagamento	`TituloLocalPagamento`
`l10n_br_mensagem_01` a `_09`	Mensagens adicionais	`TituloMensagem01` a `09`

Juros¶

Campo Cobrança	Descrição	Campo API
`l10n_br_codigo_juros`	`1` valor/dia, `2` %/mês, `12` valor/dia fixo, `3` isento	`TituloCodigoJuros`
`l10n_br_percentual_juros`	Percentual/valor	`TituloValorJuros` / `TituloValorJurosTaxa`
`l10n_br_dias_juros`	Dias após vencimento	Calcula `TituloDataJuros`

Multa¶

Campo Cobrança	Descrição	Campo API
`l10n_br_codigo_multa`	`0` sem, `1` valor fixo, `2` percentual, `12` valor/dia	`TituloCodigoMulta`
`l10n_br_percentual_multa`	Percentual/valor	`TituloValorMultaTaxa`
`l10n_br_dias_multa`	Dias após vencimento	Calcula `TituloDataMulta`

Baixa e Protesto¶

Campo Cobrança	Descrição	Campo API
`l10n_br_codigo_baixa`	`1` baixar, `2` devolver	`TituloCodBaixaDevolucao`
`l10n_br_dias_baixa`	Dias após vencimento	`TituloPrazoBaixa`
`l10n_br_codigo_protesto`	Código de protesto	`TituloCodProtesto`
`l10n_br_dias_protesto`	Dias para protesto	`TituloPrazoProtesto`

Mapeamento Completo dos Campos do Boleto¶

Dados do Cedente (origem: registro de cobrança)¶

Campo API	Origem	Observação
`CedenteContaNumero`	`l10n_br_cedente_conta`	Configuração da cobrança
`CedenteContaNumeroDV`	`l10n_br_cedente_conta_digito`	Dígito verificador
`CedenteConvenioNumero`	`l10n_br_cedente_convenio`	Convênio bancário
`CedenteContaCodigoBanco`	`l10n_br_cedente_banco`	`001` BB, `033` Santander, etc.

Dados do Sacado (origem: parceiro)¶

Prioridade de parceiro: partner_invoice_id → partner_id → parent_id

Campo API	Origem	Campo Odoo
`SacadoCPFCNPJ`	Parceiro	`l10n_br_cnpj` ou `l10n_br_cpf`
`SacadoNome`	Parceiro	`l10n_br_razao_social` ou `name`
`SacadoEmail`	Parceiro	`email` (primeiro e-mail se houver `;`)
`SacadoEnderecoLogradouro`	Parceiro	`street`
`SacadoEnderecoNumero`	Parceiro	`l10n_br_endereco_numero`
`SacadoEnderecoComplemento`	Parceiro	`street2`
`SacadoEnderecoBairro`	Parceiro	`l10n_br_endereco_bairro` (máx 60)
`SacadoEnderecoCEP`	Parceiro	`zip` (sem formatação)
`SacadoEnderecoCidade`	Parceiro → Município	`name`
`SacadoEnderecoUF`	Parceiro → Estado	`code`
`SacadoTelefone`	Parceiro	`phone` (somente dígitos)

Dados do Título (origem: parcela/fatura)¶

Campo API	Origem	Observação
`TituloDataEmissao`	Calculado	`datetime.now(tz=SP)` — data de geração
`TituloDataVencimento`	Parcela	`date_maturity` — data de vencimento
`TituloNossoNumero`	Parcela ou sequência	`l10n_br_cobranca_nossonumero` (existente) ou `next_by_id()`
`TituloAceite`	Fixo	`N`
`TituloNumeroDocumento`	Calculado	`{NF}/{parcela:003}` últimos 10 chars
`TituloDocEspecie`	Cobrança/tipo doc	`02` (NF-e), `04` (NFS-e), ou fixo do registro
`TituloValor`	Parcela	`debit` (ou `amount_residual` se parcela única)

Regra especial Banco do Brasil: Quando banco 001 e transmissão webservice, o TituloNumeroDocumento usa - ao invés de /.

Dados de NF (para bancos específicos)¶

Bancos	Campo API	Origem
`000`, `224`, `246`, `637`, `707` + `l10n_br_enviar_chave_nf`	`TituloNumeroNfe`	`l10n_br_numero_nf` / `_nfce` / `_nfse`
Idem	`TituloValorNfe`	`l10n_br_total_nfe`
Idem	`TituloDataEmissaoNfe`	`invoice_date`
Idem	`TituloChaveDanfe`	`l10n_br_chave_nf`

Exceção: Banco ABC (246) não envia chave NF para NFS-e (ticket #23385).

Sacrador/Avalista (se fundo emissor)¶

Condição	Campo API	Origem
`fundo_emissor_id` preenchido	`TituloSacadorAvalista`	`emissor_id.l10n_br_razao_social`
Idem	`TituloSacadorAvalistaEndereco`	`emissor_id.street`
Idem	`TituloInscricaoSacadorAvalista`	`emissor_id.l10n_br_cnpj`

Desconto (se configurado na parcela)¶

Campo API	Origem	Campo Odoo
`TituloCodDesconto`	Parcela	`l10n_br_cobranca_tipo_desconto`
`TituloValorDescontoTaxa`	Parcela	`l10n_br_cobranca_valor_desconto`
`TituloDataDesconto`	Parcela	`l10n_br_cobranca_data_desconto`

Autenticação PlugBoleto¶

Header	Origem	Observação
`Content-Type`	Fixo	`application/json`
`cnpj-cedente`	`fundo_emissor_id` ou `emissor_id`	CNPJ sem formatação
`cnpj-sh`	Fixo	`28653792000112` (CIEL IT)
`token-cedente`	Cobrança	`l10n_br_token`

Fluxo de Geração¶

flowchart TD
    A["action_gerar_boleto_nfe()"] --> B["Gera nosso número por parcela"]
    B --> C["_gerar_cobranca_escritural()"]
    C --> D["POST /api/v1/boletos/lote"]
    D --> E{"Resposta?"}
    E -->|sucesso| F["Atualiza idintegracao, situacao"]
    F --> G["action_boleto_nfe_situacao()"]
    E -->|falha| H["Registra erro, raise UserError"]

Filtros de Parcelas¶

O sistema gera boleto apenas para parcelas (account.move.line) que: 1. account_type == 'asset_receivable' 2. date_maturity preenchido 3. date_maturity > invoice_date 4. l10n_br_cobranca_idintegracao vazio (não gerado anteriormente) 5. l10n_br_cobranca_situacao vazio 6. _gerar_boleto(invoice_payment) retorna True

Baixa de Boletos¶

Método: `action_baixar_boletos()` (linha 2020)¶

Aspecto	Detalhe
Endpoint	`POST /api/v1/boletos/baixa/lote`
Payload	Lista de `l10n_br_cobranca_idintegracao`
Filtro	Apenas parcelas com situação ≠ `REJEITADO`, `BAIXADO`, `LIQUIDADO`

Retorno de Baixa¶

Se _status == 'sucesso', o sistema considera a baixa processada. Caso contrário, exibe erro.

Cron de Verificação¶

Método: `_check_boleto_naodisponivel()` (linha 2188)¶

Busca parcelas com situação SALVO, PENDENTE_RETENTATIVA, EMITIDO
Para cada fatura, chama action_boleto_nfe_situacao() para atualizar o status

Troubleshooting¶

Problema	Causa Provável	Solução
Boleto não gerado	Cobrança não vinculada à condição de pagamento	Vincular `l10n_br_cobranca_id`
Parcela ignorada	`date_maturity <= invoice_date`	Verificar vencimento da parcela
Parcela já processada	`l10n_br_cobranca_idintegracao` já preenchido	Limpar se rejeitado
Nosso número duplicado	Sequência desatualizada	Verificar sequência `l10n_br_nosso_numero_id`
CPF/CNPJ inválido	Parceiro sem CNPJ/CPF	Preencher cadastro do parceiro
Token expirado	Token do cedente inválido	Renovar `l10n_br_token`
Sacado sem CEP	CEP em branco	Preencher endereço do parceiro
Multa/juros incorretos	Configuração errada no registro de cobrança	Revisar percentuais e códigos
Banco do Brasil com `/`	BB webservice rejeita `/`	Sistema substitui por `-` automaticamente

Referências Cruzadas¶

NF-e TX2: NF-e Geração TX2
Cancelamentos: Cancelamentos e Eventos
Wiki principal: Pagamentos e Integrações
Índice: Sumário Geral