Recursos Implementados & Manual de Instruções 24-06-2026

gistfile1.txt

## 6. Recursos Implementados & Manual de Instruções

A arquitetura e os três pilares operacionais de faturamento e conveniados foram totalmente implementados e validados. Abaixo estão as instruções detalhadas de como usar os novos recursos no PlenoCRM.

### 6.1 Configuração de Credenciais Asaas (Pilar 1)
Cada entidade/sindicato (tenant) gerencia suas próprias chaves e ambiente do Asaas:
1. **Acesso**: Navegue até o painel de **Administração do Sindicato** > seção **Módulos**.
2. **Formulário de Configuração**: No módulo financeiro, clique em **Configurar**. Um modal de configurações do Asaas se abrirá.
3. **Preenchimento de Campos**:
   - **Ambiente**: Escolha entre `Sandbox` (ambiente de homologação/testes) e `Produção` (ambiente real).
   - **Chave de API (API Key)**: Insira a API Key gerada no painel do Asaas (*Integrações > API*). O CRM mascara a exibição da chave por segurança, ocultando a maior parte dos caracteres e exibindo apenas os últimos 4.
   - **Token de Acesso do Webhook**: Insira o token de webhook configurado no painel do Asaas para validar que as notificações vieram de fato do gateway.
4. **Testar Conexão**: Clique no botão **Testar Conexão** para que o backend envie uma requisição imediata de validação. O sistema retornará uma confirmação de sucesso com a razão social da conta ou uma mensagem de erro detalhada caso as credenciais estejam erradas.
5. **Salvar**: Clique em **Salvar Configurações** para persistir as credenciais na base.

### 6.2 Emissão de Cobrança e Visualização de PIX/Boleto (Pilar 2)
Uma vez configurado o Asaas para o inquilino, as cobranças do tipo `pix` e `boleto` geradas para os filiados serão integradas automaticamente:
1. **Sincronização Automática**: Na primeira emissão de cobrança, o PlenoCRM consulta o Asaas e cria o registro de cliente lá se o filiado ainda não possuir o `asaas_customer_id`. CPFs duplicados já cadastrados no Asaas são automaticamente reaproveitados.
2. **Ações na Listagem**: Na tabela de Cobranças, clique em **Visualizar** na linha da cobrança pendente.
3. **Visualizador de Pagamento**: O modal exibirá:
   - Para cobranças com método **PIX**: o código **PIX Copia e Cola** (com botão rápido para copiar) e a imagem do QR Code gerada de forma dinâmica.
   - Para cobranças com método **Boleto**: a **Linha Digitável / Código de Barras** (com botão rápido para copiar) e o link para visualização do PDF da fatura oficial gerada pelo Asaas.

### 6.3 Importação e Faturamento Consolidado de Convênios (Pilar 3)
A rotina consolida despesas de múltiplos arquivos baseados em CPF, processando descontos de exceção e aplicando as regras de limite de margem consignável automaticamente:
1. **Acesso**: Vá em **Financeiro** > aba **Cobranças** e clique no botão **Importação Consolidada**.
2. **Upload de Arquivos**: O modal permite selecionar arquivos em formato CSV para as faturas de **Unimed**, **Uniodonto** e **Mensalidades** de forma simultânea ou parcial.
3. **Geração de Prévia**: Clique em **Gerar prévia consolidada**. O backend processa os registros em memória, agregando os valores por CPF, e consulta as regras do banco:
   - **Identificação**: O CPF é cruzado com a base de filiados. Se o CPF não existir, a linha é marcada como **"CPF NÃO ENCONTRADO"** com ação bloqueada.
   - **Exceções**: Se o filiado tiver um desconto ativo na tabela `financeiro_excecoes`, esse valor é deduzido do lançamento.
   - **Avaliação de Destinação e Margem**:
     - Se o filiado tiver vínculo com um **Órgão Pagador** e o valor total couber na sua `margem_consignavel`, a cobrança é enviada integralmente para faturamento em folha (**Folha** / tipo `transfer`).
     - Se o valor total estourar a margem consignável, o lançamento é **Desdobrado** (Split): gera-se uma cobrança folha (`transfer`) no limite máximo da margem e a diferença vira uma cobrança direta automática integrada ao **Asaas** (tipo `boleto`/`pix`).
     - Se o filiado não possuir órgão pagador associado, a cobrança vai integralmente direta para o **Asaas** (tipo `boleto`/`pix`).
4. **Revisão e Confirmação**:
   - Revise o sumário consolidado de lançamentos (total de CPFs, filiados identificados, valor consignado em folha, valor Asaas e valor geral).
   - Você pode utilizar os checkboxes na lateral de cada linha da listagem para desmarcar e ignorar registros específicos antes do faturamento final.
   - Clique em **Confirmar e Aplicar Importação** para persistir as cobranças locais no banco e emitir os boletos/PIX no Asaas.