Parceiros (Clientes e Fornecedores)
Objetivo
Documentar os campos e regras de negócio aplicados ao cadastro de parceiros brasileiros (res.partner), incluindo validações de documentos (CNPJ/CPF), endereçamento com município IBGE, integrações com APIs externas, e configurações fiscais específicas por parceiro.
Implementação Técnica
- Model principal:
res.partner (herança)
- Arquivo:
l10n_br_ciel_it_account/models/res_partner.py (linha 133)
- Models auxiliares:
ResAgencia, ResPartnerReferenciaComercial, ResPartnerBank, ResPartnerCNAE, ResPartnerQSA, PartnerDadosPagamento, PartnerFiscalTag
Campos Cadastrais
Documentos
| Campo |
Tipo |
Descrição |
Validação |
l10n_br_cnpj |
Char (indexed, tracked) |
CNPJ da empresa |
pycpfcnpj.cnpj.validate() |
l10n_br_cpf |
Char (indexed, tracked) |
CPF da pessoa física |
pycpfcnpj.cpf.validate() |
l10n_br_id_estrangeiro |
Char |
Identificação de estrangeiro |
— |
l10n_br_ie |
Char |
Inscrição Estadual |
— |
l10n_br_im |
Char |
Inscrição Municipal |
— |
l10n_br_is |
Char |
Inscrição Suframa |
— |
l10n_br_nire |
Char |
NIRE |
— |
l10n_br_crc |
Char |
CRC (Conselho Regional de Contabilidade) |
— |
l10n_br_razao_social |
Char (indexed, tracked) |
Razão social |
Auto-preenchido pelo nome |
l10n_br_data_nascimento |
Date |
Data de nascimento (PF) |
— |
Indicadores Fiscais
| Campo |
Tipo |
Descrição |
l10n_br_indicador_ie |
Selection |
Contribuinte / Isento / Não Contribuinte / Estrangeiro |
l10n_br_regime_tributario |
Selection |
Simples Nacional / Lucro Presumido / Lucro Real |
l10n_br_situacao_cadastral |
Selection |
Situação cadastral na RFB |
l10n_br_orgao_publico |
Selection |
Se é órgão público |
l10n_br_compra_indcom |
Selection |
Destinação de uso: uso (padrão), industrialização, comercialização |
l10n_br_inss_cprb |
Selection |
Contribuinte INSS Receita Bruta (CPRB) |
l10n_br_icms_credito_aliquota |
Float |
Alíquota de crédito ICMS (Simples Nacional) |
Endereço Brasileiro
| Campo |
Tipo |
Descrição |
l10n_br_endereco_numero |
Char |
Número do endereço |
l10n_br_endereco_bairro |
Char |
Bairro |
l10n_br_municipio_id |
Many2one |
Município IBGE (com filtro por UF) |
l10n_br_consultar_cep |
Boolean |
Trigger para consulta automática de CEP |
Mensagens Fiscais
| Campo |
Tipo |
Descrição |
l10n_br_mensagem_fiscal_01_id a _05_id |
Many2one |
Até 5 observações fiscais padrão por parceiro |
Financeiro
| Campo |
Tipo |
Descrição |
l10n_br_receber_nfe |
Boolean |
Parceiro recebe NF-e por email |
l10n_br_receber_boleto |
Boolean |
Parceiro recebe boleto (endereço pode diferir da NF) |
payment_provider_id |
Many2one |
Forma de pagamento padrão |
property_account_advance_payable_id |
Many2one |
Conta a pagar (Adiantamento) |
property_account_advance_receivable_id |
Many2one |
Conta a receber (Adiantamento) |
dados_pagamento_ids |
One2many |
Dados detalhados para pagamento (PIX, conta, etc.) |
Valores Mínimos de Retenção
| Campo |
Padrão |
Descrição |
l10n_br_irpj_ret_valor |
R$ 10,00 |
Valor mínimo para reter IRPJ |
l10n_br_csll_ret_valor |
R$ 1,00 |
Valor mínimo para reter CSLL |
l10n_br_pis_ret_valor |
R$ 0,65 |
Valor mínimo para reter PIS |
l10n_br_cofins_ret_valor |
R$ 3,00 |
Valor mínimo para reter COFINS |
Marcadores Fiscais
| Campo |
Tipo |
Descrição |
fiscal_tag_ids |
Many2many |
Tags fiscais utilizadas em regras de operação |
Imóvel Rural
| Campo |
Tipo |
Descrição |
l10n_br_inscricao_fiscal_imovel |
Char |
Inscrição fiscal do imóvel |
l10n_br_codigo_cib |
Char |
Código CIB |
Regras de Negócio
1. Validação de CNPJ/CPF
- Controlada pelo parâmetro
l10n_br_ciel_it_account.validar_cnpj_cpf
- Quando ativo, os constrains
_check_l10n_br_cnpj() e _check_l10n_br_cpf() impedem salvar documentos inválidos
- A formatação é aplicada automaticamente nos métodos
create() e write():
- CNPJ:
XX.XXX.XXX/XXXX-XX
- CPF:
XXX.XXX.XXX-XX
2. Verificação de Duplicidade
- Controlada por
l10n_br_ciel_it_account.validar_cnpj_cpf_duplicado:
"1" → Bloqueia CNPJ ou CPF duplicado"2" → Bloqueia apenas se CNPJ e IE forem iguais (permite mesma empresa com IEs diferentes para filiais)- Aplica-se em
create() e write()
3. Tipo de Pessoa
- Ao marcar
is_company = True, o CPF é limpo automaticamente
- Ao marcar
is_company = False, o CNPJ é limpo automaticamente
- Se o parceiro é estrangeiro (
country_id != BR), o indicador IE é setado para 9 (Não contribuinte)
4. Auto-preenchimento
- O campo
l10n_br_razao_social é preenchido automaticamente pelo name se estiver vazio (_onchange_name)
- Ao trocar o
l10n_br_municipio_id, o campo city e state_id são atualizados automaticamente
- Ao trocar o
state_id, se o município não pertence ao novo estado, ele é limpo
Integração: Consulta CNPJ (API CNPJA)
Configuração
- Habilitar:
l10n_br_ciel_it_account.consulta_cnpj_cnpja = "1"
- Chave de API:
l10n_br_ciel_it_account.chave_cnpj_cnpja
Método: _consulta_cnpj(cnpj, cpf, ie, uf, receita)
Arquivo: res_partner.py, linha 335
Fluxo
- Formata o CNPJ removendo pontuação
- Chama
https://api.cnpja.com/rfb?taxId={CNPJ} com o header Authorization
- Preenche automaticamente:
- Razão social, fantasia
- Endereço completo (logradouro, número, bairro, CEP, UF, município)
- Situação cadastral
- Telefone e e-mail
- Natureza jurídica e capital social
- Cria registros de CNAE (atividade principal + secundárias) em
res.partner.cnae
- Cria registros do QSA (quadro societário) em
res.partner.qsa
- Baixa o Comprovante de Inscrição (PDF) como anexo (
ir.attachment)
- Consulta se é Simples Nacional ou MEI via
https://api.cnpja.com/simples?taxId={CNPJ}
Endpoints utilizados
| Endpoint |
Método |
Finalidade |
/rfb?taxId= |
GET |
Dados cadastrais completos |
/rfb/certificate?taxId= |
GET |
Comprovante PDF do CNPJ |
/simples?taxId= |
GET |
Opção pelo Simples/MEI |
Integração: Consulta CEP
- Biblioteca:
brazilcep
- Trigger: Campo
l10n_br_consultar_cep no formulário
- Preenche automaticamente: logradouro, bairro, cidade, estado, município IBGE
Models Auxiliares
ResAgencia (l10n_br.res.agencia)
Tabela de agências bancárias brasileiras.
ResPartnerReferenciaComercial
Referências comerciais do parceiro (nome, contato, telefone).
ResPartnerBank (herança res.partner.bank)
Campos adicionais para dados bancários brasileiros (ISPB, tipo de conta, agência).
ResPartnerCNAE
| Campo |
Tipo |
Descrição |
code |
Char |
Código CNAE |
text |
Char |
Descrição da atividade |
principal |
Boolean |
Se é atividade principal |
partner_id |
Many2one |
Parceiro relacionado |
ResPartnerQSA
| Campo |
Tipo |
Descrição |
qual |
Char |
Qualificação do sócio |
nome |
Char |
Nome do sócio |
pais_origem |
Char |
País de origem |
nome_rep_legal |
Char |
Nome do representante legal |
qual_rep_legal |
Char |
Qualificação do representante legal |
PartnerDadosPagamento
Dados para pagamento do parceiro (conta, agência, chave PIX, etc.).
PartnerFiscalTag
Tags fiscais para uso em regras de operação e posições fiscais.
Cenários de Uso / Troubleshooting
1. "CNPJ duplicado, corrija o cadastro primeiro!"
- Causa: Já existe outro parceiro com o mesmo CNPJ
- Solução: Buscar o parceiro existente (incluindo arquivados com
active_test=False)
- Configuração: Desabilitar validação se necessário via
l10n_br_ciel_it_account.validar_cnpj_cpf_duplicado = "0"
2. Consulta CNPJ não busca dados
- Verificar: Parâmetro
l10n_br_ciel_it_account.consulta_cnpj_cnpja está como "1"?
- Verificar: Chave de API
chave_cnpj_cnpja está configurada?
- Verificar: O parceiro tem nome preenchido antes de consultar?
3. Indicador IE setado incorretamente
- Causa: Para parceiros estrangeiros, o
_onchange_l10n_br_country_id seta automaticamente para 9
- Solução: Verificar o
country_id do parceiro
Referências Cruzadas