REF-901-04: Banco Inter Integration Contract

ADR: ADR-901 — IntegrationsEscopo: Field-level mapping entre woocommerce-banco-inter e middag-account, rate limits, timeouts, reconciliation, B2B override detalhado

---

1. Arquitetura de Integração

┌──────────────────────────────────┐     ┌──────────────────────────────────┐
│  Plugin: woocommerce-banco-inter │     │  Plugin: middag-account          │
│  (gateway WC independente)       │     │  (B2B overlay + presentation)    │
│                                  │     │                                  │
│  BancoInterGateway               │◄────│  BancoInterPayerAdapter          │
│  ├── process_payment()           │     │  ├── filter: prepare_payer       │
│  ├── process_webhook()           │     │  └── filter: prepare_debtor      │
│  ├── generate_boleto()           │     │                                  │
│  └── generate_pix()              │     │  BancoInterWebhookHandler [SPEC] │
│                                  │     │  └── action: payment_complete    │
│  API Inter v2                    │     │                                  │
│  ├── POST /banking/v2/boleto     │     │  BancoInterPaymentService [SPEC] │
│  └── POST /banking/v2/pix       │     │  └── REST: /orders/{id}/payment  │
└──────────────────────────────────┘     └──────────────────────────────────┘
         │                                         │
         │  WC Hooks (filters + actions)           │
         └─────────────────────────────────────────┘

Princípio: woocommerce-banco-inter funciona standalone em qualquer WooCommerce B2C. middag-account adiciona B2B sem modificar o plugin externo.

---

2. Boleto — Field Mapping (13 campos)

Mapeamento dos campos enviados à API Inter v2 para criação de boleto bancário.

#	Campo API Inter	Tipo	Max	Origem middag-account (B2B)	Fallback (B2C)
1	pagador.cpfCnpj	string	14	Organization.org_documentnumber1 (CNPJ)	Order.billing_cpf
2	pagador.tipoPessoa	enum	—	JURIDICA (quando CNPJ)	FISICA
3	pagador.nome	string	100	Organization.org_trade_name	Order.billing_first_name + billing_last_name
4	pagador.endereco	string	100	Organization.org_address_line1	Order.billing_address_1
5	pagador.complemento	string	30	Organization.org_address_line2	Order.billing_address_2
6	pagador.bairro	string	60	Organization.org_neighborhood	Order.billing_neighborhood
7	pagador.cidade	string	60	Organization.org_city	Order.billing_city
8	pagador.uf	string	2	Organization.org_state	Order.billing_state
9	pagador.cep	string	8	Organization.org_postcode (sem hífen)	Order.billing_postcode
10	pagador.email	string	100	Organization.org_email	Order.billing_email
11	pagador.telefone	string	15	Organization.org_phone	Order.billing_phone
12	seuNumero	string	15	Order.id (prefixado)	Order.id
13	valorNominal	decimal	—	Order.total	Order.total

Regras de Override B2B

1. Order tem meta `_organization`?
   └── NÃO → bypass (B2C normal, dados do billing)
   └── SIM → resolve Organization via ID
       └── Organization tem `org_documentnumber1` (CNPJ)?
           └── NÃO → bypass (pessoa física na org, usa billing)
           └── SIM → override campos 1-11 com dados da Organization
               └── tipoPessoa = JURIDICA
               └── nome = org_trade_name (razão social / trade name)

---

3. Pix — Field Mapping (8 campos)

Mapeamento para criação de cobrança Pix via API Inter v2.

#	Campo API Inter	Tipo	Max	Origem middag-account (B2B)	Fallback (B2C)
1	devedor.cpf ou devedor.cnpj	string	14	Organization.org_documentnumber1	Order.billing_cpf
2	devedor.nome	string	100	Organization.org_trade_name	Order.billing_first_name + billing_last_name
3	valor.original	string	—	Order.total (formato "123.45")	Order.total
4	chave	string	77	Env var BANCO_INTER_PIX_KEY	Env var
5	solicitacaoPagador	string	140	Pedido #{Order.id} - {org_trade_name}	Pedido #{Order.id}
6	calendario.expiracao	int	—	1800 (30 minutos)	1800
7	txid	string	35	middag{Order.id}{timestamp}	Gerado pelo gateway
8	infoAdicionais	array	50	[{nome: "Pedido", valor: Order.id}]	—

Diferença Pix B2B

Quando CNPJ presente, usa campo devedor.cnpj (14 dígitos) em vez de devedor.cpf (11 dígitos). API Inter distingue pelo campo enviado, não por flag.

---

4. Rate Limits — API Banco Inter v2

Operação	Limite	Período	Ação no Excesso
Criar boleto	100 req	1 min	HTTP 429, Retry-After
Criar Pix	100 req	1 min	HTTP 429, Retry-After
Consultar status	300 req	1 min	HTTP 429, Retry-After
Cancelar boleto	50 req	1 min	HTTP 429, Retry-After

Plugin woocommerce-banco-inter implementa retry com backoff exponencial (1s, 2s, 4s, max 3 tentativas).

---

5. Timeouts e Expiração

Método	Timeout API	Expiração Cobrança	Baixa Automática
Pix	30s	30 minutos (configurável via calendario.expiracao)	Imediata após expiração
Boleto	30s	D+3 após vencimento (padrão Inter)	D+5 após vencimento (baixa automática)

Cenários de Expiração

Cenário	Ação plugin wc-banco-inter	Ação middag-account
Pix expirado (30min)	Order status → failed	Quote status mantém payment_pending
Pix pago	Order status → processing → completed	Quote → paid, sync HubSpot
Boleto vencido (D+3)	Nenhuma (aguarda baixa)	Nenhuma
Boleto baixado (D+5)	Order status → cancelled	Quote → expired (via cron)
Boleto pago	Order status → processing → completed	Quote → paid, sync HubSpot

---

6. Webhook Flow Detalhado

Banco Inter API
│
├── Pix: callback URL configurada no painel Inter
│   POST /wc-api/banco-inter-webhook
│   Headers: x-inter-webhook-signature: {HMAC-SHA256}
│   Body: { "pix": [{ "txid": "...", "valor": "123.45", "horario": "..." }] }
│
└── Boleto: callback URL configurada no painel Inter
    POST /wc-api/banco-inter-webhook
    Headers: x-inter-webhook-signature: {HMAC-SHA256}
    Body: { "codigoSolicitacao": "...", "codigoBarras": "...", "situacao": "PAGO" }

Plugin wc-banco-inter
│
├── Valida HMAC signature
├── Identifica tipo (pix ou boleto)
├── Localiza WC Order via txid/seuNumero
├── Atualiza Order status
│   └── payment_complete() → woocommerce_payment_complete action
│
└── middag-account (via hook woocommerce_payment_complete)
    │
    ├── BancoInterWebhookHandler::onPaymentComplete($orderId)
    │   ├── Verifica meta _quote_id no Order
    │   ├── Se existe: Quote.status → paid
    │   ├── Dispara EntitlementProvisioningService (auto-criação)
    │   └── Sync HubSpot: Deal → Closed Won
    │
    └── (Outros handlers: Invoice generation, email notification, etc.)

---

7. Reconciliation

Cron job no middag-account para tratar webhooks perdidos:

Frequência	Ação	Escopo
A cada 30 min	Buscar Orders com status on-hold há mais de 2h	Pix (podem ter expirado sem webhook)
Diário	Buscar boletos pendentes com vencimento D-1 ou anterior	Boletos que expiraram
Diário	Verificar Orders completed sem Quote paid correspondente	Inconsistência webhook

Lógica de Reconciliation

Para cada Order pendente encontrada:
  1. Consultar status no wc-banco-inter (que consulta API Inter)
  2. Se pago: disparar payment_complete manualmente
  3. Se expirado: marcar Order como cancelled/failed
  4. Se pendente: manter (ainda dentro do prazo)

---

8. Environment Variables

Variável	Responsável	Descrição
BANCO_INTER_CLIENT_ID	wc-banco-inter	OAuth2 client ID
BANCO_INTER_CLIENT_SECRET	wc-banco-inter	OAuth2 client secret
BANCO_INTER_CERT_PATH	wc-banco-inter	Caminho certificado .crt
BANCO_INTER_KEY_PATH	wc-banco-inter	Caminho chave .key
BANCO_INTER_PIX_KEY	wc-banco-inter	Chave Pix (CNPJ, email, etc.)
BANCO_INTER_WEBHOOK_SECRET	wc-banco-inter	HMAC secret para validação
BANCO_INTER_ENVIRONMENT	wc-banco-inter	sandbox ou production

middag-account NÃO gerencia essas variáveis. São configuração exclusiva do plugin externo.

---

9. Escopo de Implementação

Componente	Status	Versão
BancoInterPayerAdapter (B2B override)	Implementado	v5.0
BancoInterWebhookHandler (Quote sync)	Spec	v5.0
BancoInterPaymentService (API v1)	Spec	v5.0
Reconciliation cron	Spec	v5.0.x
Admin UI (payment status view)	Spec	v5.0.x