REF-301-01: Dual-Entity Routing Rules
ADR: ADR-301 — Commerce: Quote, Order, Invoice, TaxInvoiceEscopo: Árvore de decisão de roteamento, campos da Organization, product channels block, override admin, regras de Services
1. Árvore de Decisão
Evento de compra (Quote aceito / Order criada)
│
├── Produto tem atribuição explícita de entidade?
│ ├── SIM → Usar entidade atribuída pelo produto
│ └── NÃO → Usar billing_entity da Organization
│
├── Organization tem billing_entity definido?
│ ├── SIM → Rotear para essa entidade
│ └── NÃO → Determinar a partir dos dados do cliente:
│ ├── Tem CNPJ? → MIDDAG BR
│ ├── Tem EIN/VAT/outro tax ID internacional? → MIDDAG GLOBAL
│ └── Sem tax ID? → Usar preferred_currency:
│ ├── BRL → MIDDAG BR
│ └── USD → MIDDAG GLOBAL
│
├── Override: Admin pode definir manualmente entidade por transação
│
└── Exceção: Services são SEMPRE MIDDAG BR (v5.0)2. Campos da Organization
| Campo | Tipo | Descrição |
|---|---|---|
billing_entity | enum | middag_br / middag_global / null (auto-detect) |
preferred_currency | enum | BRL / USD — fallback para roteamento e exibição |
stripe_customer_id_br | string | Customer ID na conta Stripe BR (pagamentos BRL) |
stripe_customer_id_global | string | Customer ID na conta Stripe GLOBAL (pagamentos USD) |
hubspot_company_id_br | string | Company ID no HubSpot BR |
hubspot_company_id_global | string | Company ID no HubSpot GLOBAL |
tax_id | string | CNPJ, EIN, VAT — formato livre |
tax_id_type | string | Label do tipo (CNPJ, EIN, VAT, custom) |
Nota: Organization pode ter AMBOS os Stripe customer IDs (raro: org que compra da BR E da LLC).
3. Product Channels Block
Cada produto define quais contas Stripe (e outros canais) estao habilitadas via channels block:
channels:
stripe_br:
enabled: true # Sincroniza com Stripe BR (BRL)
stripe_global:
enabled: false # Stripe US desabilitado| Channel Config | Significado | Exemplo |
|---|---|---|
channels.stripe_br.enabled | Sincroniza apenas com Stripe BR (BRL) | Planos Services, hospedagem gerenciada |
channels.stripe_global.enabled | Sincroniza apenas com Stripe US (USD) | Plugins vendidos internacionalmente |
Nota: O campo
sync.stripe.entityfoi removido. Ochannelsblock e a unica fonte de verdade para roteamento de entidade.
4. O Que Cada Entidade Lida
| Capacidade | MIDDAG BR | MIDDAG GLOBAL |
|---|---|---|
| Plugins | Sim (BRL) | Sim (USD) — prioridade |
| SaaS (Campus EAD) | Sim (mercado BR) | Futuro (internacional) |
| Services | Sim (sempre) | Raro (caso a caso, toggle) |
| Pagamento: Stripe | Sim (Stripe BR) | Sim (Stripe US) |
| Pagamento: Banco Inter | Sim (Pix, Boleto) | Não |
| Fiscal: NFSe | Sim (ISSNet, Brasília/DF) | Não |
| Fiscal: Invoice | Stripe Invoice | Stripe Invoice |
| CRM: HubSpot | Sim (instância BR) | Sim (instância LLC) |
| Moeda | BRL | USD |
5. Override Admin
| Cenário | Comportamento |
|---|---|
| Admin define entidade em Quote | Override para todas as transações desse Quote |
| Admin define entidade em Order | Override pontual para essa Order |
| Conflito produto vs org | Produto vence (tag explícita) |
| Sem tag no produto, sem billing_entity | Auto-detect por tax ID / moeda preferencial |
6. Regra de Services
Services são SEMPRE MIDDAG BR na v5.0.
Justificativa: serviços profissionais são operação brasileira. LLC para serviços é caso a caso e desabilitado por default. Toggle admin permite habilitar Services via LLC se necessário no futuro.
7. Filosofia de Configuração
Tudo pode existir tanto na BR quanto na LLC. Limites são configuráveis no WP, não hardcoded.
| Configuração | Default | Configurável |
|---|---|---|
| LLC vende serviços | Desabilitado | Toggle admin |
| LLC vende SaaS | Desabilitado | Toggle admin |
| BR cobra em USD | Desabilitado | Toggle admin (raro) |
| Atribuição de entidade no produto | Auto (da org) | Override por produto |