# Documentação Técnica e Operacional: Integração Bancária Santander (033)

> **Documento Interno de Engenharia e Operações Financeiras**  
> **Sistema:** Integra Viman (Vitória Hospitalar)  
> **Data de Criação:** 14/09/2026  
> **Status:** Implementado (Pronto para Homologação / Produção)  
> **Módulos Abrangidos:** Pix Automático (Bacen), Transferências TED/TEF, Débito Direto Autorizado (DDA)

---

## 1. Visão Geral e Objetivos

Esta documentação consolida a implementação técnica, arquitetura de software, fluxos operacionais e guia de evolução contínua da integração direta via API com o **Banco Santander (Brasil) S.A. (Código de Compensação 033)** no sistema **Integra Viman**.

### Objetivos do Projeto
1. **Substituição de Arquivos de Remessa/Retorno CNAB**: Eliminar a troca manual de arquivos CNAB 240/400 para operações diárias de pagamentos e consultas.
2. **Automação do Contas a Pagar**:
   - Liquidação pontual ou em lote de duplicatas via PIX, TED e TEF com confirmação em tempo real.
   - Captura eletrônica de boletos emitidos contra o CNPJ da empresa através do Débito Direto Autorizado (DDA).
   - Eliminação da digitação manual de linhas digitáveis e códigos de barras.
3. **Cobrança Recorrente via Pix Automático**:
   - Implantação da modalidade de Pix Automático conforme especificações normativas do Banco Central do Brasil (Bacen) e do Santander para contratos recorrentes e faturamentos programados.

---

## 2. Arquitetura da Solução no Integra Viman

A arquitetura foi desenvolvida seguindo os padrões **Driver / Strategy** e **Service Layer**, mantendo o desacoplamento entre o ERP Viman e as particularidades de cada instituição financeira.

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                            Camada de Apresentação                            │
│  - Painel Contas a Pagar (/modulos/financeiro/contas)                        │
│  - Configurações Santander (/modulos/financeiro/configuracoes/santander)     │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       │
┌──────────────────────────────────────▼───────────────────────────────────────┐
│                      Gerenciador Central (BankApiManager)                     │
│                  Resolve o driver por código FEBRABAN ('033')                │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       │
┌──────────────────────────────────────▼───────────────────────────────────────┐
│                             SantanderApiDriver                               │
│       Fachada que implementa BankApiDriverInterface e orquestra os serviços  │
└───────┬───────────────────────┬───────────────────────┬──────────────────────┘
        │                       │                       │
┌───────▼────────┐      ┌───────▼────────┐      ┌───────▼────────┐
│  Transferência │      │   Boletos DDA  │      │ Pix Automático │
│    Service     │      │    Service     │      │    Service     │
└───────┬────────┘      └───────┬────────┘      └───────┬────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────────────────────┐
│                    SantanderAuthService (mTLS + OAuth 2.0)                   │
│     - Certificado Digital A1 (.pfx / .crt / .key)                            │
│     - Bearer Token em Cache                                                  │
│     - Headers: X-Application-Key & Workspace ID                              │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────────────────────┐
│                      APIs Externas Banco Santander (033)                     │
│  - /management_payments_partners/v1 (TED / DDA / Boletos)                    │
│  - /pix/v2 (Pix Pontual e Pix Automático Bacen)                              │
│  - /auth/oauth/v2/token (Emissão de Token)                                   │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## 3. Estrutura de Arquivos e Responsabilidades

### 3.1 Camada de Serviços Bancários (`app/Services/Banking/`)
* **`BankApiManager.php`**: Registra e entrega os drivers bancários (Santander `033`, Bradesco `237`, etc.).
* **`Drivers/Santander/SantanderApiDriver.php`**: Fachada principal Santander. Expõe métodos unificados (`payPix`, `payTransfer`, `payBoletoDda`, `listDdaBoletos`, `pixAutomatico`, `testConnection`).
* **`Drivers/Santander/SantanderAuthService.php`**:
  * Autenticação OAuth 2.0 (`POST /auth/oauth/v2/token`) com cache inteligente;
  * Configuração de cliente HTTP mTLS (Guzzle) com certificados digitais ICP-Brasil;
  * Injeção automática dos headers obrigatórios: `X-Application-Key` e `Authorization: Bearer <token>`;
  * Gerenciamento de credenciais da conta centralizada matriz (Agência, Conta, CNPJ, Workspace ID).
* **`Drivers/Santander/SantanderTransferService.php`**:
  * Implementação oficial da esteira **Management Payments Partners v1** (`POST /workspaces/{workspace_id}/transfer`);
  * Header de Idempotência `X-Idempotency-Key` (UUIDv4);
  * Formatação estrita de agência (4 dígitos), conta corrente (20 dígitos zero-padded) e códigos de finalidade;
  * Tratamento de transferências intrabancárias (`TEF`) e interbancárias (`TED`).
* **`Drivers/Santander/SantanderDdaService.php`**:
  * Varredura de boletos registrados na CIP via `GET /workspaces/{workspace_id}/authorized_direct_debits`;
  * Filtros por intervalo de vencimento (`initialDueDate`, `finalDueDate`), situação e paginação;
  * Consulta detalhada de encargos/abatimentos via `/authorized_direct_debits/{code}`;
  * Liquidação eletrônica de boletos via `POST /workspaces/{workspace_id}/bank_slips`.
* **`Drivers/Santander/SantanderPixAutomaticoService.php`**:
  * **Jornada de Adesão**: Criação de mandatos de autorização (`POST /pix/v2/solicitacoes-adesao`) e geração de link/QR Code EMV;
  * **Cobrança Programada**: Envio prévio de cobranças recorrentes (`POST /pix/v2/cobrancas-recorrentes`);
  * **Gestão de Mandatos**: Consulta e revogação/cancelamento de autorizações;
  * **Webhooks**: Roteamento de eventos assíncronos (`adesão`, `rejeição`, `liquidação`).

### 3.2 Modelos e Banco de Dados (`app/Models/` e `database/migrations/`)
* **`PagamentoTransacao`** (`pagamentos_transacoes`): Registra cada ordem de pagamento executada com payload de envio, retorno bancário, status e ID da transação.
* **`PagamentoErro`** (`pagamentos_erros`): Registra rejeições ou falhas de comunicação com triagem automatizada (ex: `DADOS_BANCARIOS_INVALIDOS`, `SALDO_INSUFICIENTE`).
* **`DdaBoletoRecebido`** (`dda_boletos_recebidos`): Tabela de espelho para armazenar todos os boletos capturados no Santander DDA, permitindo indexação rápida e vinculação com o ERP Viman.
* **`PixAutomaticoMandato`** (`pix_automatico_mandatos`): Armazena as autorizações de débito contínuo assinadas pelos clientes/devedores.

### 3.3 Interface e Controladores Web
* **`app/Http/Controllers/Web/SantanderConfigController.php`**: Gerencia a configuração da conta Matriz, teste de conectividade mTLS e credenciais no banco criptografado.
* **`resources/views/modulos/financeiro/configuracoes/santander.blade.php`**: Painel visual para configuração do Workspace ID, ambiente (Sandbox/Produção), certificados e chaves.
* **`app/Http/Controllers/Web/ContasPagarController.php`**: Painel operacional do Contas a Pagar com consulta do DDA e disparo de pagamentos unitários e em lote.

---

## 4. Detalhamento dos Fluxos Operacionais

### 4.1 Fluxo de Transferência TED / TEF (Santander Partners v1)

```mermaid
sequenceDiagram
    autonumber
    actor Op as Operador Financeiro
    participant Viman as ERP Viman
    participant Driver as SantanderTransferService
    participant Bank as API Santander (v1)

    Op->>Viman: Seleciona Duplicatas para pagamento via TED
    Viman->>Driver: execute(PaymentInstructionDTO)
    Driver->>Driver: Valida dados bancários e gera X-Idempotency-Key
    Driver->>Bank: POST /workspaces/{workspace_id}/transfer
    alt Sucesso no Processamento
        Bank-->>Driver: Retorno 201 (Status: CREATED / READY_TO_PAY / COMPLETED)
        Driver->>Viman: Registra transacao_id e efetua baixa no ERP
    else Erro ou Inconsistência
        Bank-->>Driver: HTTP 4xx/5xx com detalhes do erro
        Driver->>Viman: Registra falha na tabela `pagamentos_erros` com sugestão de correção
    end
```

#### Regras de Formatação Obrigatórias:
| Campo | Tipo | Regra Santander | Exemplo no Código |
|---|---|---|---|
| `bankCode` | String | 4 dígitos numéricos (zero à esquerda) | `str_pad($banco, 4, '0', STR_PAD_LEFT)` => `"0033"` |
| `branchCode` | String | 4 dígitos numéricos (sem dígito verificador) | `str_pad($agencia, 4, '0', STR_PAD_LEFT)` => `"2245"` |
| `accountNumber`| String | 20 dígitos numéricos (zero-padded à esquerda) | `str_pad($conta, 20, '0', STR_PAD_LEFT)` |
| `transferType` | String | `"TEF"` para contas Santander / `"TED"` para outros bancos | Detectado automaticamente |
| `purposeCode` | String | Código de finalidade Bacen | Padrão `"00001"` (Crédito em Conta) |
| `X-Idempotency-Key` | Header | UUID v4 único por requisição | `(string) Str::uuid()` |

---

### 4.2 Fluxo de Débito Direto Autorizado (DDA)

```mermaid
sequenceDiagram
    autonumber
    participant Cron as Rotina Automática (Job)
    participant DdaService as SantanderDdaService
    participant Bank as Santander DDA API
    participant DB as Tabela `dda_boletos_recebidos`
    participant ERP as Duplicatas ERP Viman

    Cron->>DdaService: listBoletos(cnpjMatriz, D-5, D+30)
    DdaService->>Bank: GET /workspaces/{workspace_id}/authorized_direct_debits
    Bank-->>DdaService: Array de boletos registrados na CIP
    loop Para cada boleto retornado
        DdaService->>DB: Salva/Atualiza registro do boleto
        DdaService->>ERP: Busca duplicata correspondente (CNPJ + Valor + Vencimento)
        alt Match Encontrado
            DB->>ERP: Preenche automaticamente Código de Barras e Linha Digitável
            DB->>DB: Marca situacao = 'VINCULADO'
        end
    end
    Note over ERP: Duplicatas prontas para pagamento em lote com 1 clique
```

#### Regras de Match Automático:
1. **Match Perfeito (100% Confiança)**:
   - CNPJ do Beneficiário (DDA) == CNPJ do Fornecedor (ERP);
   - Valor Nominal (DDA) == Valor Aberto da Parcela (ERP);
   - Data de Vencimento (DDA) == Data de Vencimento da Parcela (ERP).
2. **Match com Tolerância**:
   - Vencimento no próximo dia útil caso o original caia em final de semana ou feriado bancário.
   - Diferença de valor por descontos/abatimentos contratuais ou acréscimo de juros informados na CIP.

---

### 4.3 Fluxo de Pix Automático (Regulamentação Bacen)

O Pix Automático se divide em duas etapas distintas:

#### Fase 1: Jornada de Adesão (Autorização do Pagador)
1. O Integra Viman gera a proposta de mandato:
   `POST /pix/v2/solicitacoes-adesao`
2. O Santander responde com o identificador do mandato e o código **EMV (Pix Copia e Cola / QR Code)**.
3. O pagador escaneia o QR Code ou clica no link dentro do app do seu próprio banco (seja Santander, Itaú, Nubank, etc.) e confirma o débito periódico.
4. O Santander notifica a ativação via Webhook (`status: ATIVA`).

#### Fase 2: Cobrança Recorrente e Liquidação
1. **Antecedência Mínima (D-2 a D-10 dias)**: O Integra Viman envia a cobrança vinculada ao mandato ativo:
   `POST /pix/v2/cobrancas-recorrentes`
2. O Bacen notifica o pagador com antecedência sobre o débito programado.
3. **No dia do Vencimento (D-0)**: O Bacen e o Santander realizam o débito na conta do cliente e o crédito imediato na conta da Matriz.
4. O Webhook confirma a liquidação e o Integra Viman dá baixa automática na duplicata.

---

## 5. Matriz de Endpoints Santander vs. Métodos do Sistema

| Funcionalidade | Método HTTP | Endpoint Oficial Santander | Classe / Método no Integra Viman |
|---|---|---|---|
| **OAuth2 Token** | `POST` | `/auth/oauth/v2/token` | `SantanderAuthService::getAccessToken()` |
| **Iniciar TED/TEF** | `POST` | `/management_payments_partners/v1/workspaces/{id}/transfer` | `SantanderTransferService::execute()` |
| **Listar Boletos DDA** | `GET` | `/management_payments_partners/v1/workspaces/{id}/authorized_direct_debits` | `SantanderDdaService::listBoletos()` |
| **Detalhes Boleto DDA** | `GET` | `/management_payments_partners/v1/workspaces/{id}/authorized_direct_debits/{code}` | `SantanderDdaService::getBoletoDetail()` |
| **Pagar Boleto DDA** | `POST` | `/management_payments_partners/v1/workspaces/{id}/bank_slips` | `SantanderDdaService::execute()` |
| **Pix Pontual** | `POST` | `/pix/v1/pagamentos` (ou `/pix/v2/pix`) | `SantanderPixService::execute()` |
| **Criar Adesão Pix Auto**| `POST` | `/pix/v2/solicitacoes-adesao` | `SantanderPixAutomaticoService::criarSolicitacaoAdesao()` |
| **Consultar Adesão** | `GET` | `/pix/v2/solicitacoes-adesao/{id}` | `SantanderPixAutomaticoService::consultarSolicitacaoAdesao()` |
| **Revogar Adesão** | `DELETE`| `/pix/v2/solicitacoes-adesao/{id}` | `SantanderPixAutomaticoService::cancelarSolicitacaoAdesao()` |
| **Agendar Cobrança Pix** | `POST` | `/pix/v2/cobrancas-recorrentes` | `SantanderPixAutomaticoService::agendarCobrancaRecorrente()` |
| **Consultar Cobrança Pix**| `GET` | `/pix/v2/cobrancas-recorrentes/{id}` | `SantanderPixAutomaticoService::consultarCobrancaRecorrente()` |

---

## 6. Configuração de Ambientes e Checklist de Produção

As configurações do Santander no Integra Viman são divididas em duas camadas para maximizar a facilidade de gestão e a segurança bancária:

### 6.1 Configurações Gerenciadas na Interface Web (`/modulos/financeiro/configuracoes/santander`)
Acessível a partir do botão **"⚙️ Configurar API Santander"** na tela de Contas a Pagar:
* **Ambiente & Modo de Operação**:
  * Alternância entre `🧪 Sandbox (Homologação)` e `🚀 Produção (Liquidação Real)`;
  * Flag de ativação de transmissão automática (quando desmarcado, opera em modo simulado seguro);
* **URLs Base Oficiais Santander**:
  * Sandbox / Homologação: `https://trust-sandbox.api.santander.com.br`
  * Produção: `https://trust-open.api.santander.com.br`
* **Credenciais Santander Developer Portal**:
  * `Client ID` (Application Key enviada no header `X-Application-Key`);
  * `Client Secret` (armazenado de forma criptografada no banco Oracle);
  * `Workspace ID` (identificador corporativo obrigatório para rotas `/workspaces/{workspace_id}/...`);
* **Dados da Conta Matriz (Filial 01 - Vitória Hospitalar)**:
  * CNPJ Titular: `05.432.100/0001-99`
  * Agência Santander: `2245`
  * Conta Corrente: `13009876` / Dígito: `5`
  * Chave PIX Matriz: `05432100000199`
  * Código de Convênio / Transmissão: `1234567`

### 6.2 Certificados Digitais ICP-Brasil (Configurados no Servidor via `.env`)
Por segurança estrita, os arquivos de certificado físico A1 (`.pfx` ou `.crt` + `.key`) e senhas residem diretamente no servidor de hospedagem e são declarados no arquivo `.env`, sem necessidade de digitação ou upload via navegador:
```env
# Certificado Digital ICP-Brasil (mTLS Santander)
SANTANDER_CERT_PATH="C:\certificados\santander_matriz.pfx"
SANTANDER_CERT_PASSWORD="senha_do_certificado"
SANTANDER_SSL_KEY_PATH=""
```
> **Nota de Auditoria**: A tela de configurações web possui um card de status que verifica automaticamente se o arquivo especificado em `SANTANDER_CERT_PATH` está presente no disco do servidor e acessível para o handshake mTLS.

### 6.3 Checklist de Habilitação Comercial e Técnica com o Santander
- [ ] **Adesão ao DDA Eletrônico**: Solicitar ao Gerente Corporate Santander a habilitação formal do CNPJ matriz no serviço DDA de Débito Direto Autorizado;
- [ ] **Liberação de Escopos da API no Portal Santander**:
  - `management_payments_partners` (TED e Pagamento de Boletos);
  - `authorized_direct_debit` (Consulta DDA);
  - `pix_automatico` e `pix_pagamentos`;
- [ ] **Whitelisting de IP**: Cadastrar o IP fixo de saída do servidor do Integra Viman no Portal Santander Developer;
- [ ] **Certificado Digital A1**: Fazer upload da chave pública do certificado ICP-Brasil no portal para vinculação com a aplicação.

---

## 7. Verificação e Testes Automatizados

O sistema conta com testes automatizados cobrindo tanto o modo simulado (sandbox) quanto a estrutura dos DTOs e regras de validação.

### Execução dos Testes via Terminal:
```bash
# 1. Execução do Teste Unitário do Driver Santander
php vendor/phpunit/phpunit/phpunit tests/Unit/Banking/SantanderApiDriverTest.php

# 2. Execução dos Testes de Integração Web do Contas a Pagar
php vendor/phpunit/phpunit/phpunit tests/Feature/ContasPagarWebTest.php
```

### Cenários Cobertos nos Testes:
1. **Resolução de Driver**: Garante que o `BankApiManager` resolve o código `033` como padrão e com as interfaces corretas;
2. **Validações de TED/TEF**:
   - Rejeição quando faltam agência ou conta do favorecido;
   - Simulação de TEF (transferência interna entre contas Santander);
   - Simulação de TED (transferência para outros bancos via COMPE/ISPB);
3. **Validações de DDA**:
   - Rejeição de duplicatas sem código de barras/linha digitável;
   - Simulação de pagamento e geração de autenticação bancária `DDA033...`;
4. **Validações de Pix Automático**:
   - Criação de proposta de mandato de adesão com geração do payload EMV;
   - Consulta e verificação do status `ATIVA`;
   - Agendamento de cobrança recorrente com vencimento futuro;
   - Consulta de liquidação com retorno do identificador `endToEndId`.

---

## 8. Quadro de Progresso e Evoluções Futuras (Roadmap)

| Item / Funcionalidade | Status | Observações |
|---|---|---|
| **Arquitetura de Drivers Santander** | ✅ Concluído | Camada extensível para múltiplos bancos |
| **Autenticação mTLS + OAuth2** | ✅ Concluído | Suporte a certificados A1 e header `X-Application-Key` |
| **Transferências TED / TEF (v1)** | ✅ Concluído | Endpoint `/workspaces/{id}/transfer` e idempotência |
| **Consulta e Pagamento Boletos DDA** | ✅ Concluído | Endpoints `/authorized_direct_debits` e `/bank_slips` |
| **Pix Automático (Mandatos Bacen)** | ✅ Concluído | Endpoints `/solicitacoes-adesao` e `/cobrancas-recorrentes` |
| **Banco de Dados (Migrations & Models)** | ✅ Concluído | Tabelas `dda_boletos_recebidos` e `pix_automatico_mandatos` |
| **Painel de Configuração com Workspace ID**| ✅ Concluído | Formulário atualizado em `configuracoes/santander.blade.php` |
| **Job de Sincronização Noturna DDA** | ⏳ Próximo Passo | Criar comando Artisan agendado (`santander:sync-dda`) |
| **Endpoint Webhook Público com Validação** | ⏳ Próximo Passo | Rota pública para notificações assíncronas do Santander |
| **Conciliação Automática de Extrato (OFX)** | 📋 Planejado | Importação ou consulta de extrato para baixa financeira total |