96 lines
3.9 KiB
Plaintext
96 lines
3.9 KiB
Plaintext
# Documentação Técnica: Integração Banco Inter API (Pix V2)
|
|
|
|
Esta documentação descreve a integração com a API de Parceiros do Banco Inter (CDPJ) para processamento de pagamentos via Pix, implementada no ecossistema Captain/Chatwoot.
|
|
|
|
## 🔑 Autenticação e Segurança
|
|
|
|
A API do Banco Inter utiliza um modelo de segurança robusto baseado em **Mutual TLS (mTLS)** e **OAuth2**.
|
|
|
|
- **Protocolo**: HTTPS com Certificado Digital (Chave Pública e Privada).
|
|
- **OAuth2 Flow**: `client_credentials`.
|
|
- **Scopes Utilizados**: `cob.write`, `cob.read`, `webhook.write`, `webhook.read`, `extrato.read`.
|
|
- **Headers Mandatórios**:
|
|
- `x-conta-corrente`: Número da conta corrente do parceiro.
|
|
- `Authorization`: Token Bearer obtido via OAuth2.
|
|
|
|
### Credenciais
|
|
As credenciais são configuradas por Unidade (`Captain::Unit`) e incluem:
|
|
- `client_id` / `client_secret`
|
|
- `inter_cert_path` e `inter_key_path` (Caminhos para arquivos `.pem`)
|
|
- `inter_pix_key` (Chave Pix CPF/CNPJ/E-mail/EVP)
|
|
|
|
---
|
|
|
|
## 🚀 Fluxo de Cobrança Pix (Cobrança Imediata)
|
|
|
|
O sistema utiliza o endpoint de **Cobrança Imediata (Cob)** para gerar faturas Pix para reservas.
|
|
|
|
### 1. Geração da Cobrança
|
|
**Endpoint**: `POST https://cdpj.partners.bancointer.com.br/pix/v2/cob`
|
|
**Serviços Locais**: `Captain::Inter::CobService` e `Captain::InterService`.
|
|
|
|
**Payload Exemplo**:
|
|
```json
|
|
{
|
|
"calendario": { "expiracao": 3600 },
|
|
"devedor": {
|
|
"cpf": "12345678900",
|
|
"nome": "Nome do Cliente"
|
|
},
|
|
"valor": { "original": "150.00" },
|
|
"chave": "sua-chave-pix@email.com",
|
|
"solicitacaoPagador": "Reserva #12345"
|
|
}
|
|
```
|
|
|
|
### 2. Pix One-Tap (Link Seguro)
|
|
Para melhorar a UX no WhatsApp, foi implementado o fluxo **One-Tap**:
|
|
- Em vez de enviar o código bruto (geralmente muito longo), o bot envia um link curto: `https://seu-dominio/r/:token`.
|
|
- O `:token` é um **SGID (Signed Global ID)** com expiração de 2 horas.
|
|
- Ao abrir o link, o cliente vê uma página otimizada com o botão "Copiar Pix" e feedback visual.
|
|
|
|
---
|
|
|
|
## 🔗 Webhooks e Confirmação
|
|
|
|
O Banco Inter notifica o sistema sobre o pagamento através de webhooks.
|
|
|
|
- **Endpoint**: `POST /public/api/v1/captain/inter_webhooks`
|
|
- **Controller**: `Public::Api::V1::Captain::InterWebhooksController`
|
|
|
|
**Processamento**:
|
|
1. Extração do `txid` (Transaction ID) e `endToEndId` (Identificador E2E do Banco Central).
|
|
2. Verificação de idempotência (evita processar o mesmo pagamento duas vezes).
|
|
3. Atualização do status da `Captain::PixCharge` para `paid`.
|
|
4. Disparo do `Captain::Payments::ConfirmationService` para validar a reserva.
|
|
5. Mensagem automática enviada via Chatwoot confirmando o pagamento para o cliente.
|
|
|
|
---
|
|
|
|
## 🛠️ Modelos de Dados Principais
|
|
|
|
### `Captain::PixCharge`
|
|
- Atributos: `txid`, `e2eid`, `status` (active, paid, expired, failed), `pix_copia_e_cola`.
|
|
- Relações: `belongs_to :reservation`, `belongs_to :unit`.
|
|
|
|
---
|
|
|
|
## 📂 Localização dos Arquivos
|
|
|
|
| Componente | Caminho |
|
|
| :--- | :--- |
|
|
| **Service Principal** | `app/services/captain/inter_service.rb` |
|
|
| **Service Enterprise** | `enterprise/app/services/captain/inter/cob_service.rb` |
|
|
| **Controller Webhook** | `app/controllers/public/api/v1/captain/inter_webhooks_controller.rb` |
|
|
| **Model** | `enterprise/app/models/captain/pix_charge.rb` |
|
|
| **Página de Pagamento** | `app/views/public/api/v1/captain/payments/show.html.erb` |
|
|
|
|
---
|
|
|
|
## 📝 Notas de Manutenção (Ressalvas)
|
|
- **Encoding**: Foi corrigido um bug crítico onde a API do Inter retornava caracteres em encoding binário que causavam falha no Rails ao renderizar JSON. Sempre use `.force_encoding('UTF-8')` ao lidar com a resposta da API do Inter.
|
|
- **Ambiente de Dev**: No ambiente de desenvolvimento local, o sistema sanitiza URLs de `0.0.0.0` para `127.0.0.1` para garantir que o link One-Tap seja acessível localmente.
|
|
|
|
---
|
|
*Documentação gerada em 23/02/2026 baseada na análise técnica do repositório local devido à instabilidade do Notion.*
|