ADR-901: Integrations
Status: Accepted
Contexto
middag-account integra com 9 sistemas externos: HubSpot (CRM dual), Stripe (billing dual), Jira (projeto/SLA), ISSNet (emissor NFSe municipal, Brasília/DF), Cloudflare (D1/R2 edge cache), WooCommerce (commerce), SolidAffiliate (parceiros), Banco Inter (pagamentos Pix/Boleto BR), Chatwoot (chat ao vivo + contact view). Cada integração tem direção, gatilho e payload explícitos. Integrações vivem DENTRO do core (ADR-103) porque reagem a eventos de domínio e compartilham DI container.
Decisão
6 Princípios de Integração
- Webhook-first. Preferir webhooks a polling. Polling apenas quando sistema externo não suporta (ISSNet).
- Idempotência. Todo webhook recebido é reprocessável. Eventos duplicados não criam registros duplicados.
- Graceful degradation. Se HubSpot está fora, quotes funcionam localmente. Sync recupera quando conexão restaura.
- Audit trail. Todo evento registrado com timestamp, direção, hash do payload, status do resultado.
- WC como source of truth para billing. WooCommerce é autoridade para estado financeiro. Stripe alimenta WC via webhooks. Plugin lê de WC, nunca direto do Stripe para billing state.
- Prevenção de loops. Eventos de domínio disparam hooks WP — prevenção de loops obrigatória em handlers bidirecionais.
9 Integrações
| Sistema | Direção | O Que Flui | Versão |
|---|---|---|---|
| HubSpot | Bidirecional | Deals, quotes, org data, status | v5.0 |
| Stripe | Entrada+Saída | Pagamentos, invoices, subscriptions, customers | v5.0 |
| Jira | Bidirecional | SRs, status, SLA, worklogs | v5.0.x |
| ISSNet | Saída+Polling | NFSe (submissão + status) | v5.0.x |
| Cloudflare | Saída | D1 cache read, R2 object storage | v5.0.x |
| WooCommerce | Bidirecional | Orders, products, subscriptions | v5.0 |
| SolidAffiliate | Entrada | Referrals, affiliate approvals | v5.0 |
| Banco Inter | Entrada | Pagamentos Pix/Boleto via plugin externo | v5.0 |
| Chatwoot | Bidirecional | Contact view, PHP SDK, chat ao vivo | v5.0.x |
Notificações
Canal primário: email via WC nativo (templates WC, override via child theme). Auditoria: hash para auditoria@middag.com.br. Canais secundários futuros (v5.0.x): SMS/WhatsApp. NotificationPolicy define obrigatórios vs opcionais.
Escopo por Versão
v5.0:
- HubSpot sync bidirecional (deals, quotes, org)
- Stripe dual-account (5 webhook events)
- WooCommerce adapter (orders, subscriptions)
- SolidAffiliate adapter (somente leitura)
- Email notifications (WC nativo)
v5.0.x:
- Jira bidirecional (SRs, SLA, worklogs)
- ISSNet NFSe (submissão + polling)
- Cloudflare D1/R2 (edge cache, object storage)
- SMS/WhatsApp notifications
Consequências
Positivas:
- Webhook-first minimiza latência de sync
- Idempotência previne dados duplicados em retries
- Graceful degradation garante plugin funciona com sistema externo fora
- WC como billing source of truth evita conflito Stripe/plugin
Negativas:
- 9 integrações = 9 pontos de falha potenciais
- Dual-account (HubSpot + Stripe) dobra complexidade de webhook handling
- Jira bidirecional requer conflict resolution cuidadoso
- ISSNet SOAP é frágil e legado (sem webhooks, polling obrigatório)
Especificação por Integração
| Integração | Detalhes em |
|---|---|
| HubSpot | REF-901-01 |
| Stripe | REF-901-02 |
| Jira | REF-901-03 |
| Banco Inter | REF-901-04 |
| Cloudflare | REF-901-05 |
| Chatwoot | REF-901-06 |
| SolidAffiliate | REF-901-07 |
| ISSNet | REF-901-08 |
| WooCommerce | ADR-301 (Commerce motor) |
Referências
- REF-901-01 — HubSpot Sync Rules
- REF-901-02 — Stripe Dual-Account
- REF-901-03 — Jira SLA Integration
- REF-901-04 — Banco Inter Integration Contract
- REF-901-05 — Cloudflare D1/R2 Integration
- REF-901-06 — Chatwoot Integration
- REF-901-07 — SolidAffiliate Integration
- REF-901-08 — ISSNet NFSe Integration (Brasília/DF)
- ADR-103 — Plugin Ecosystem (integrações dentro do core)
- ADR-301 — Commerce (dual-entity routing)
- ADR-601 — Service Classes (Jira como SLA engine)