# Documentação: Geração de Faturas, Envio para Omie e Rateios

## 1. GERAÇÃO DE FATURAS

### 1.1 Processo de Criação
A geração de faturas ocorre no arquivo `ProcessarFatura.php` e segue os seguintes passos:

1. **Validação de Dados**:
   - Tipo de fatura (médico ou digitador)
   - Código do profissional
   - Valor da fatura (deve ser > 0)
   - Data de vencimento (deve ser futura)
   - Exames selecionados
   - Contrato válido (PRN, MEDIMAGEM, MEDIMAGEM PALHOCA)

2. **Cálculo de Valores**:
   - **Valor Bruto (gross)**: Soma dos valores dos exames + itens manuais
   - **Valor Líquido (net)**: Valor bruto - desconto (se aplicável)
   - **Desconto**: Pode ser aplicado globalmente ou apenas em itens específicos

3. **Inserção da Fatura**:
   ```php
   INSERT INTO faturas_prest (fat_prest, fat_val, fat_val_int, fat_desc, fat_vcto, 
                             fat_tipo_prest, fat_usu, fat_ref, fat_status, fat_data, fat_val_dig)
   ```
   - `fat_val`: Valor líquido (com desconto aplicado)
   - `fat_val_int`: Valor bruto (sem desconto)
   - `fat_desc`: Percentual de desconto
   - `fat_status`: Inicialmente 'Gerada'

4. **Atualização dos Exames**:
   - Vincula os exames à fatura através de `ex_fat_med` ou `ex_fat_dig`
   - Limpa a referência do outro tipo de fatura (se houver)

---

## 2. RATEIOS E PORCENTAGENS

### 2.1 Conceito de Rateio
O rateio distribui o valor da fatura entre diferentes unidades/departamentos. Existem dois tipos:

#### **A) Rateio Proporcional**
- Distribui o valor proporcionalmente entre todas as unidades que têm exames na fatura
- O percentual é calculado baseado no valor dos exames de cada unidade
- Itens manuais são distribuídos igualmente entre as unidades existentes

#### **B) Rateio Único**
- Concentra todo o valor dos itens manuais em uma única unidade selecionada
- Útil quando um item deve ser atribuído a uma unidade específica

### 2.2 Cálculo de Percentuais (Frontend)

**Localização**: `SelecionarExames.php` (função `atualizarResumoUnidadesManual`)

**Processo**:
1. **Agrupamento por Unidade**:
   ```javascript
   unidades_summary[unidade_cod] = {
     count: número_de_exames,
     valor: soma_dos_valores,
     percent: 0.0,
     nome: nome_da_unidade
   }
   ```

2. **Cálculo Inicial de Percentuais**:
   ```javascript
   percent_raw = (valor_unidade / valor_total) * 100
   ```

3. **Ajuste para 100%**:
   - Arredonda cada percentual para 2 casas decimais
   - Se a soma não for exatamente 100%, ajusta a última unidade:
   ```javascript
   diferenca = 100 - soma_percentuais
   unidades[ultima_unidade].percent += diferenca
   ```

4. **Inclusão de Itens Manuais**:
   - **Proporcional**: Divide o valor total dos itens manuais igualmente entre as unidades
   - **Único**: Adiciona todo o valor à unidade selecionada
   - Recalcula percentuais após incluir itens manuais

### 2.3 Processamento no Backend

**Localização**: `ProcessarFatura.php` (linhas 340-429)

**Ajustes Finais**:
1. **Normalização de Valores**:
   ```php
   // Ajusta valores para somar exatamente o valor líquido (net)
   foreach ($unidades_summary as $unidade => &$data) {
       $data['valor'] = round(($data['valor'] / $sum_val_atual) * $net, 2);
   }
   ```

2. **Garantia de Soma Exata**:
   - Calcula diferença entre soma dos valores e valor líquido
   - Ajusta a última unidade para fechar exatamente:
   ```php
   $diff = round($net - $sum_ajustado, 2);
   if (abs($diff) > 0.01) {
       $unidades_summary[$last_key]['valor'] += $diff;
   }
   ```

3. **Recálculo de Percentuais**:
   ```php
   $data['percent'] = $sum_final > 0 ? round(($data['valor'] / $sum_final) * 100, 2) : 0.00;
   ```

4. **Ajuste Final de Percentuais**:
   - Garante que a soma dos percentuais seja exatamente 100%
   - Ajusta a última unidade se necessário

5. **Inserção no Banco**:
   ```php
   INSERT INTO fat_prest_rateio (rat_fat, rat_uni, rat_val, rat_perc)
   VALUES (:rat_fat, :rat_uni, :rat_val, :rat_perc)
   ```

### 2.4 Estrutura da Tabela de Rateios

**Tabela**: `fat_prest_rateio`
- `rat_fat`: ID da fatura
- `rat_uni`: Código da unidade
- `rat_val`: Valor do rateio (R$)
- `rat_perc`: Percentual do rateio (%)

**Validações**:
- Soma dos percentuais deve ser 100% (tolerância: 99.5% - 100.5%)
- Soma dos valores deve ser igual ao valor líquido da fatura
- Cada unidade deve estar cadastrada no sistema

---

## 3. ENVIO PARA O OMIE

### 3.1 Processo de Envio

**Arquivo**: `integracaoOmie/EnviarOmie.php`

**Fluxo**:
1. **Busca da Fatura**:
   - Carrega dados da fatura (`faturas_prest`)
   - Busca dados do fornecedor/médico

2. **Validação do Fornecedor**:
   - Busca CPF/CNPJ do fornecedor no Omie
   - Obtém `codigo_cliente_omie`

3. **Busca de Rateios**:
   ```php
   SELECT rat_uni, rat_val, rat_perc 
   FROM fat_prest_rateio 
   WHERE rat_fat = :fat
   ```

4. **Agrupamento por Código Omie**:
   - Múltiplas unidades podem ter o mesmo código Omie (departamento)
   - Agrupa rateios por `uni_omie`:
   ```php
   $distrib_temp[$omie_limpo] = [
       'cCodDep' => $omie_limpo,        // Código do departamento no Omie
       'cDesDep' => $uni['uni_nome'],   // Nome do departamento
       'nValDep' => $val_arredondado,   // Valor do rateio
       'nPerDep' => $perc_arredondado   // Percentual do rateio
   ];
   ```

5. **Ajustes Finais**:
   - Garante que soma de percentuais = 100%
   - Garante que soma de valores = valor total da fatura
   - Ajusta última entrada se necessário

6. **Montagem do JSON**:
   ```json
   {
     "codigo_lancamento_integracao": "123",
     "codigo_cliente_fornecedor": "456789",
     "data_vencimento": "31/01/2026",
     "valor_documento": 1000.00,
     "data_previsao": "31/01/2026",
     "distribuicao": [
       {
         "cCodDep": "001",
         "cDesDep": "Unidade A",
         "nValDep": 600.00,
         "nPerDep": 60.00
       },
       {
         "cCodDep": "002",
         "cDesDep": "Unidade B",
         "nValDep": 400.00,
         "nPerDep": 40.00
       }
     ]
   }
   ```

7. **Envio para API Omie**:
   ```php
   $payload = [
       'call' => 'IncluirContaPagar',
       'app_key' => OMIE_APP_KEY,
       'app_secret' => OMIE_APP_SECRET,
       'param' => [$json_data]
   ];
   ```

8. **Processamento da Resposta**:
   - Se sucesso: Atualiza `fat_status = 'Enviada'` e salva `fat_lanc_omie`
   - Se erro: Atualiza `fat_status = 'Falha no processamento'`
   - Sempre salva resposta na tabela `response_omie`

### 3.2 Estrutura de Distribuição no Omie

**Campo `distribuicao`**:
- `cCodDep`: Código do departamento no Omie (vem de `unidades.uni_omie`)
- `cDesDep`: Nome do departamento (vem de `unidades.uni_nome`)
- `nValDep`: Valor do rateio em R$
- `nPerDep`: Percentual do rateio (%)

**Importante**:
- Múltiplas unidades físicas podem ter o mesmo código Omie
- O sistema agrupa automaticamente rateios com mesmo `uni_omie`
- Valores e percentuais são somados quando agrupados

### 3.3 Validações no Envio

1. **Fornecedor**:
   - Deve ter CPF/CNPJ cadastrado
   - Deve existir no Omie

2. **Unidades**:
   - Todas as unidades devem ter código Omie (`uni_omie`)
   - Código Omie não pode estar vazio

3. **Rateios**:
   - Deve haver pelo menos um rateio
   - Soma de percentuais deve ser 100%
   - Soma de valores deve ser igual ao valor da fatura

---

## 4. EXEMPLO PRÁTICO

### Cenário:
- Fatura de R$ 1.000,00
- 3 exames da Unidade A (R$ 600,00)
- 2 exames da Unidade B (R$ 400,00)
- 1 item manual de R$ 100,00 (rateio proporcional)

### Processo:

1. **Frontend calcula**:
   - Unidade A: R$ 600,00 (60%)
   - Unidade B: R$ 400,00 (40%)
   - Item manual: R$ 50,00 para cada unidade

2. **Valores finais**:
   - Unidade A: R$ 650,00 (65%)
   - Unidade B: R$ 450,00 (45%)
   - Total: R$ 1.100,00

3. **Se houver desconto de 10%**:
   - Valor líquido: R$ 990,00
   - Backend ajusta proporcionalmente:
     - Unidade A: R$ 585,00 (59,09%)
     - Unidade B: R$ 405,00 (40,91%)
   - Última unidade ajustada para fechar: R$ 405,00 (40,91%)

4. **Envio para Omie**:
   - Se Unidade A e B têm códigos Omie diferentes:
     - Departamento 001: R$ 585,00 (59,09%)
     - Departamento 002: R$ 405,00 (40,91%)
   - Se ambas têm mesmo código Omie:
     - Departamento 001: R$ 990,00 (100%)

---

## 5. PONTOS DE ATENÇÃO

### 5.1 Arredondamentos
- Todos os valores são arredondados para 2 casas decimais
- Percentuais são arredondados para 2 casas decimais
- Diferenças de arredondamento são ajustadas na última unidade

### 5.2 Tolerâncias
- Percentuais: tolerância de 0,01% (99,99% - 100,01%)
- Valores: tolerância de R$ 0,01

### 5.3 Itens Manuais
- Podem ter rateio proporcional ou único
- Rateio proporcional: divide igualmente entre unidades existentes
- Rateio único: concentra em uma unidade específica
- Itens manuais podem ter desconto aplicado ou não (configurável por item)

### 5.4 Descontos
- Desconto pode ser aplicado globalmente ou por item
- Desconto é aplicado sobre o valor bruto
- Valor líquido = valor bruto - desconto
- Rateios são calculados sobre o valor líquido

---

## 6. LOGS E DEBUG

### 6.1 Logs do Sistema
- `ProcessarFatura.php`: Salva logs em `processar_fatura.log`
- `EnviarOmie.php`: Salva respostas em `response_omie`
- `relatorio.php`: Gera logs de debug para validação de rateios

### 6.2 Validações de Debug
- Verifica se soma de percentuais = 100%
- Verifica se soma de valores = valor da fatura
- Loga ajustes realizados na última unidade
- Valida se rateios têm valores/percentuais inválidos (≤ 0)

---

## 7. TABELAS RELACIONADAS

1. **faturas_prest**: Faturas de prestadores
2. **fat_prest_rateio**: Rateios das faturas
3. **unidades**: Unidades/departamentos (com `uni_omie`)
4. **exames**: Exames vinculados às faturas
5. **response_omie**: Respostas da API Omie
6. **fornecedores**: Dados dos fornecedores/médicos

---

**Última atualização**: 27/01/2026