# Manual operacional — Cobrança PJ (Pessoa Jurídica)

Este documento descreve o **módulo de cobrança para empresas (PJ) / planos** implementado no **Sigo Laravel**. Ele serve para **entender conceitos**, **regras de negócio** e **como operar** o sistema no dia a dia.

> **Escopo:** cobrança **PJ** (sacado com natureza de fatura = empresa). O fluxo de **cobrança PF** (beneficiário) é outro módulo (`cobrancapf`), com telas e APIs próprias.

---

## 1. Objetivo do módulo

Centralizar o **acompanhamento da inadimplência de empresas** vinculadas ao plano, permitindo:

- ver processos abertos e seus valores;
- registrar contatos com o devedor;
- formalizar **acordos** (à vista ou parcelado) sobre faturas selecionadas;
- gerar **parcelas de boleto** no cadastro de cobrança;
- registrar **pagamento de boletos** (v API) para atualizar acordo e processo.

Os dados ficam nas tabelas `uniod.cob_*` (processo, faturas da cobrança, acordos, pivot acordo–fatura, boletos, histórico).

---

## 2. Conceitos principais

| Termo | O que é |
|--------|---------|
| **Empresa / Plano** | No sistema, o processo amarra-se ao **código do plano** (`prc_pla_codigo`), que representa a empresa PJ. Dados cadastrais (nome, razão social, CNPJ) vêm do cadastro de plano. |
| **Fatura financeira** | Registro em `tb_fatura` (contas a receber): valor, vencimento, sacado, se está paga etc. |
| **Processo de cobrança** | “Pasta” da cobrança: um processo por linha em `cob_processo_cobranca`, com status e valor total. |
| **Fatura na cobrança** | Cópia lógica da dívida no processo: cada linha em `cob_fatura_cobranca` liga uma `fat_numero` ao processo, com valores (original, juros/multa, atualizado) e status próprio (**Aberta**, **Negociada**, **Quitada**). |
| **Acordo** | Negociação formal: tipo **À vista** ou **Parcelado**, valor total acordado, desconto, juros opcionais, número de parcelas, datas. |
| **Boleto (cobrança)** | Registro em `cob_boleto_cobranca` por parcela do acordo (valor, vencimento, status). A **impressão** pode usar o legado `sigoweb` quando houver **nosso número** cadastrado. |
| **Histórico** | Linhas de auditoria: criação, contato, acordo, cancelamento, alteração de status, pagamento. |

---

## 3. Como um processo nasce

### 3.1 Geração automática (job)

Existe o job `GerarProcessosCobrancaJob`, que:

1. **Lista empresas inadimplentes** com base em faturas em `tb_fatura`:
   - sacado PJ (`fat_naturezasacado = 'P'`);
   - **sem pagamento** (`fat_dtpagto` nulo);
   - **vencidas** (data de vencimento < hoje);
   - **não avulsas** (`fat_avulsa = 'N'`).
2. Para cada empresa encontrada:
   - se **já existir processo ativo** (status diferente de **Quitada**, **Cancelada** e **Incobrável**), **não cria** outro;
   - senão chama a criação do processo para aquele `pla_codigo`.

**Observação para operação / TI:** o job precisa estar **agendado ou disparado** (fila Laravel) no ambiente; caso contrário os processos só existirão se forem criados por outro meio (ex.: rotina futura ou criação manual via código).

### 3.2 O que a criação grava

Ao **criar** o processo para um plano:

- Busca **todas as faturas PJ em aberto** daquele sacado: não pagas, não avulsas, natureza **P** (ou seja, **não exige** neste passo que todas estejam vencidas — pode incluir faturas em aberto ainda no vencimento).
- Cria o processo com status **Aberta** e `prc_valor_total` = soma dos valores (líquido + juros/descontos da fatura).
- Para cada fatura: cria linha em `cob_fatura_cobranca` com status **Aberta**.
- Registra **histórico** de criação.

---

## 4. Status do processo

Valores possíveis (conforme modelo e banco):

| Status | Significado operacional |
|--------|-------------------------|
| **Aberta** | Processo criado; cobrança em aberto, sem acordo ativo que tenha mudado o fluxo, ou após situações iniciais. |
| **Em Negociação** | Foi criado um **acordo** (negociação formal) para pelo menos parte das faturas; o sistema atualiza o processo para este status ao criar acordo. |
| **Acordo Fechado** | Previsto no cadastro de domínio / filtros de tela; **não há fluxo automático** no código que defina este status ao fechar acordo — pode ser usado **manualmente** via API de alteração de status, conforme política interna. |
| **Quitada** | Encerramento com quitação: manualmente ou quando **não restar** nenhuma fatura da cobrança com status diferente de **Quitada** após baixa dos boletos (ver seção 7). |
| **Cancelada** | Processo encerrado sem quitação (uso discricional / manual via API). |
| **Incobrável** | Classificação de processo sem perspectiva de recebimento (uso discricional / manual via API). |

**Processo “ativo”** para fins de **não duplicar** processo automático: qualquer status que **não** seja Quitada, Cancelada ou Incobrável.

---

## 5. Status das faturas dentro do processo (`cob_fatura_cobranca`)

| Status | Quando |
|--------|--------|
| **Aberta** | Logo após vincular ao processo; ou **após cancelar** um acordo que incluía essa fatura. |
| **Negociada** | Incluída em um **acordo** não cancelado. |
| **Quitada** | Após **todos** os boletos do acordo estarem **pagos** (via API de pagamento), o sistema marca as faturas daquele acordo como quitadas. |

Na tela de detalhe, faturas **Quitadas** não entram em novo acordo (checkbox desabilitado).

---

## 6. Acordo (negociação)

### 6.1 Regras gerais

- **Um acordo “em andamento” por processo:** não é permitido criar outro acordo se já existir um com status **diferente de Cancelado**.
- Na **interface**, o botão **Novo acordo** fica desabilitado se existir qualquer acordo que **não** esteja **Cancelado** (inclui acordos **Pendente**, **Quitado**, etc.). Para novo acordo após quitação, a prática esperada é alinhar com TI (pode ser necessário ajuste de regra de tela ou uso de API).
- **Faturas elegíveis:** as selecionadas devem ser do processo, identificadas por `fco_id`, e **não** podem estar **Quitadas**.

### 6.2 Dados do acordo (formulário / API)

- **Tipo:** **À vista** (`Vista`) ou **Parcelado** (`Parcelado`).
- **Parcelas:** obrigatório se parcelado; inteiro de **1 a 12**.
- **Data de vencimento da 1ª parcela:** obrigatória.
- **Desconto (R$):** opcional; reduz o total acordado.
- **Aplicar juros (1%):** opcional; se marcado, aplica **1%** sobre o total das faturas selecionadas **após** a lógica de desconto (conforme implementação atual).
- **Observações:** opcionais.

### 6.3 O que o sistema faz ao criar o acordo

1. Grava o acordo em `cob_acordo_cobranca` com status **Pendente**.
2. Associa faturas na tabela `cob_acordo_fatura`.
3. Atualiza as linhas de `cob_fatura_cobranca` selecionadas para **Negociada**.
4. Atualiza o processo para **Em Negociação**.
5. **Gera os boletos** em `cob_boleto_cobranca`: um por parcela; divide o valor total; **última parcela** absorve diferenças de arredondamento; vencimentos em **meses consecutivos** a partir da primeira data.
6. Registra **histórico** (tipo Acordo).

### 6.4 Cancelamento do acordo

- **Permitido** se **nenhum** boleto do acordo estiver **Pago**.
- Boletos não pagos passam a **Cancelado**; acordo → **Cancelado**; faturas vinculadas voltam para **Aberta**; gera-se histórico (motivo opcional).
- Depois disso é possível **criar outro acordo** (desde que a regra de “acordo ativo” e a tela permitam).

---

## 7. Boletos e pagamentos

### 7.1 Emissão / impressão

- Na tela de detalhe, cada boleto pode exibir link **Imprimir** quando existir **nosso número** (ou número) preenchido no cadastro do boleto, apontando para o relatório legado:  
  `.../sigoweb/relatorios/jasperphp/boletoNegociacao.php?nossoNumero=...`
- A criação do acordo **preenche** valor, parcela, vencimento e status **Emitido**; o **nosso número** pode depender de **integração adicional** com o módulo de boletos — se estiver vazio, a tela **não** mostra o botão de impressão.

**Status do boleto (previstos):** Emitido, Pago, Vencido, Cancelado.

### 7.2 Registrar pagamento (API)

Não há botão na tela PJ analisado para “dar baixa” no boleto; a baixa é feita via:

- **POST** `/api/v1/financeiro/cobranca/boletos/{id}/pagamento`  
  Corpo (JSON): `data_pagamento` (obrigatório), `observacoes` (opcional).  
  `{id}` = identificador do boleto (`bol_id`).

**Efeitos em cadeia:**

1. Marca o boleto como **Pago**.
2. Se **todos** os boletos daquele acordo estiverem **Pago**:
   - acordo → **Quitado**;
   - faturas da cobrança ligadas ao acordo → **Quitada**;
   - histórico de pagamento.
3. Se **não** sobrar nenhuma fatura do processo com status diferente de **Quitada**:
   - processo → **Quitada**, preenche data de fechamento;
   - histórico informando quitação automática do processo.

**Importante:** esse fluxo atualiza as tabelas **`cob_*`**. A baixa na **fatura original** (`tb_fatura` / contas a receber “oficial”) pode exigir **processo complementar** ou conciliação, conforme definição da cooperativa.

---

## 8. Registrar contato

Na tela de detalhe: **Registrar contato**.

**Campos:**

- **Tipo:** Ligação, WhatsApp ou E-mail (obrigatório).
- **Detalhes:** opcional (ex.: telefone, e-mail usado).
- **Observações:** obrigatório.

O sistema grava no **histórico** (tipo **Contato**) com usuário vinculado ao token (`usu_codigo` do SigoWeb quando disponível).

---

## 9. Alterar status do processo (API)

Para cenários como **Cancelada**, **Incobrável** ou **Acordo Fechado** (se adotado manualmente):

- **PUT** `/api/v1/financeiro/cobranca/processos/{id}/status`  
  Corpo: `status` (obrigatório), `observacoes` (opcional).

Se o novo status for **Quitada**, o sistema também preenche **data de fechamento** e registra histórico.

---

## 10. Telas (operador)

| O quê | Onde |
|-------|------|
| Lista de processos com filtros | Rota web do financeiro: **Processos de Cobrança** — `financeiro/cobranca` (nome da rota Laravel: `financeiro.cobranca.index`). |
| Detalhe do processo | `financeiro/cobranca/{id}` — faturas, acordos, boletos, histórico, modais de contato e acordo. |

**Filtros na lista:** status, texto (nome/CNPJ), valor mínimo e máximo. A busca chama a API com token JWT armazenado (ex.: `localStorage`).

---

## 11. APIs resumidas (integração / TI)

Prefixo comum: **`/api/v1/financeiro/`** (autenticação **JWT**).

| Método | Caminho | Uso |
|--------|---------|-----|
| GET | `cobranca/processos` | Lista processos (query: status, busca, valor_minimo, valor_maximo, datas, pla_codigo). |
| GET | `cobranca/processos/{id}` | Detalhe completo. |
| PUT | `cobranca/processos/{id}/status` | Altera status do processo. |
| POST | `cobranca/processos/{id}/contato` | Registra contato (JSON). |
| POST | `cobranca/acordos` | Cria acordo (ver validações no sistema). |
| POST | `cobranca/acordos/{id}/cancelar` | Cancela acordo (body opcional: `motivo`). |
| POST | `cobranca/boletos/{id}/pagamento` | Baixa boleto. |

*(O front legado nas views pode usar base `/sigo-laravel/public/api/v1/...` — ajustar conforme URL publicada no servidor.)*

---

## 12. Histórico — tipos de ação

- **Criação** — processo criado.
- **Contato** — ligação, WhatsApp, e-mail.
- **Acordo** — novo acordo.
- **Cancelamento** — acordo cancelado.
- **Alteração** — mudança de status do processo (via serviço de atualização).
- **Pagamento** — quitação de acordo ou processo após baixa de boletos.

---

## 13. Limitações e pontos de atenção (transparência)

1. **Job de abertura em massa:** depende de estar efetivamente **rodando** no ambiente.
2. **Critério “inadimplente” vs “faturas no processo”:** a lista do job usa faturas **vencidas**; a criação do processo **inclui todas as faturas PJ em aberto** da empresa.
3. **Status “Acordo Fechado”:** aparece em filtro e modelo, mas **não** é atribuído automaticamente pelo fluxo de acordo/boleto atual.
4. **Nova negociação após acordo quitado:** a tela trata “acordo ativo” como qualquer acordo **não cancelado**; validar com o negócio se após **Quitado** deve permitir novo acordo sem ajuste.
5. **Baixa de boleto** na tela: **não implementada** no front analisado — uso da **API** ou evolução futura da interface.
6. **Integração financeira formal (`tb_fatura`):** não descrita no fluxo de `BoletoService`; pode ser etapa separada.

---

## 14. Diferença rápida em relação à cobrança PF

- **PJ:** foco em **faturas de empresa** + **acordos com boletos** em `cob_*`.
- **PF:** rotas `cobrancapf/...`, negociação com **mensalidades**, parcelas e títulos próprios do fluxo PF.

---

*Documento gerado com base na implementação do módulo no repositório Sigo Laravel. Para dúvidas de implantação (URLs exatas, permissões de perfil, agendamento do job), consulte a equipe de TI responsável pelo ambiente.*