💳 Crédito — Contas a Receber¶

1. O que é este módulo?¶

O módulo de Crédito é responsável pelo processamento de dados de Contas a Receber. Ele permite que a equipe financeira envie planilhas com registros de recebíveis — títulos, duplicatas e valores em aberto — que são validados contra a base de clientes da Lavoro antes de serem carregados no Datalake.

A principal preocupação deste módulo é a integridade referencial: antes de aceitar qualquer registro, o sistema verifica se a combinação Código do Cliente + CPF/CNPJ + Código da Empresa realmente existe na dim_cliente do BigQuery. Isso evita que dados "órfãos" (sem vínculo com clientes reais) entrem no sistema e contaminem os relatórios financeiros.

Exemplo prático: O analista de crédito envia uma planilha com 500 títulos a receber. O sistema verifica se cada cliente informado existe na base, valida CPFs e CNPJs, converte valores monetários do formato brasileiro e carrega os dados validados no BigQuery para atualização dos saldos dos clientes.

2. Telas Disponíveis¶

Aba	Finalidade
📤 Contas a Receber	Upload de planilhas de contas a receber com validação completa

Nota: Este módulo possui apenas a aba de upload, sem tela de consulta separada.

3. Como Usar — Passo a Passo¶

📤 Enviando dados de Contas a Receber¶

Passo a passo:

Acesse o módulo "Crédito" no Dashboard
Baixe o template de preenchimento clicando no botão de download:
O arquivo .xlsx gerado possui abas de referência com listas de empresas e investidas
As células possuem dropdowns nativos (Data Validation) já vinculados à estrutura comercial, facilitando o preenchimento correto
Preencha a planilha com os dados de contas a receber:
codigo_empresa — Código da empresa emissora
codigo_loja — Código da loja (filial)
codigo_cliente — Código do cliente devedor
cpf_cnpj — CPF (11 dígitos) ou CNPJ (14 dígitos) do cliente
valor — Valor total do título
valor_em_aberto — Valor ainda em aberto (pendente de pagamento)
data_de_pagamento — Data do pagamento (se houver)
Outros campos conforme template
Faça o upload do arquivo (aceita .xlsx, .xls e .csv)
Para CSV, o sistema detecta automaticamente o delimitador (vírgula ou ponto-e-vírgula) e o encoding
Aguarde a validação completa:
O sistema verifica a existência de cada cliente cruzando com a dim_cliente do BigQuery
CPFs e CNPJs são validados quanto ao formato (tamanho de dígitos)
Valores monetários são convertidos do formato brasileiro
Se houver erros, um relatório detalhado será exibido indicando a linha exata, a coluna e o motivo (ex: "Empresa inexistente", "CPF com menos de 11 dígitos")
Revise a pré-visualização dos dados validados
Clique em "Processar" para enviar ao BigQuery

4. Validações¶

Validação Cruzada (Cross-Check)¶

A validação principal do módulo é feita em lote (batch query): o sistema extrai todas as combinações únicas Código Cliente + CPF/CNPJ + Código Empresa do arquivo enviado e consulta a dim_cliente do BigQuery para verificar se cada combinação existe.

Regra	Descrição
Existência de Empresa	O `codigo_empresa` deve estar cadastrado na estrutura comercial
Existência de Cliente	A combinação `codigo_cliente + cpf_cnpj + codigo_empresa` deve existir na `dim_cliente` do BigQuery
CPF	O campo é limpo de caracteres especiais e deve possuir exatamente 11 dígitos
CNPJ	O campo é limpo de caracteres especiais e deve possuir exatamente 14 dígitos
Colunas obrigatórias	O arquivo deve conter todos os campos do schema definido

Validações de Formato¶

Regra	Descrição
Parsing Monetário	Strings como `R$ 1.250,50` são convertidas para `1250.50` (float). O parser trata separadores de milhar (ponto) e decimal (vírgula) brasileiros
Preservação de Zeros	Colunas de códigos (`codigo_cliente`, `codigo_empresa`, `cpf_cnpj`) são lidas como texto para preservar zeros à esquerda
Normalização de Colunas	O sistema reconhece variações como "cod_empresa", "codigo empresa" e "empresa" e mapeia automaticamente para o nome padrão
Datas Flexíveis	Suporte a múltiplos formatos de data com tratamento de fuso horário para compatibilidade com BigQuery

5. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Finalidade
Silver	`lavoro_portal_contas_a_receber`	Armazena os registros processados com schema rígido e metadados de auditoria
Dimensional	`dim_cliente`	Base de clientes utilizada para validação cruzada (cliente + CPF/CNPJ + empresa)
Dimensional	`dim_estrutura_comercial`	Estrutura comercial para validação de empresas e lojas

Schema de Dados¶

O schema é estritamente tipado, garantindo compatibilidade total com o BigQuery: - Campos STRING: codigo_empresa, codigo_loja, codigo_cliente, cpf_cnpj - Campos FLOAT64: valor, valor_em_aberto - Campos DATE: data_de_pagamento - Campos TIMESTAMP: uploaded_at

Campos de Auditoria¶

uploaded_at — Data e hora UTC do upload
uploaded_by — E-mail do usuário responsável

6. Controle de Acesso¶

Role	Permissões
admin	Acesso completo
credito	Acesso ao módulo de Contas a Receber

7. Tratamento de Erros¶

Cenário	Como o sistema reage
Cliente não encontrado	Tabela detalhada com a linha do Excel, coluna e motivo ("Cliente inexistente na dim_cliente")
CPF/CNPJ inválido	Indica a linha, o valor informado e o motivo (ex: "CPF com 9 dígitos — esperado 11")
Valor negativo	Alerta com indicação do campo e linha problemática
CSV com encoding incorreto	Detecção automática de delimitadores e encodings, com fallback para UTF-8
Falha de conexão BQ	Captura de exceção com mensagem amigável e log técnico expansível

📅 Documentação atualizada em Março 2026.