REF-301-02: Multi-Currency Model
ADR: ADR-301 — Commerce: Quote, Order, Invoice, TaxInvoiceEscopo: BRL+USD simultâneo, preço fixo vs conversão, faixas de câmbio, cascata de fator, preço BR mais alto, sentinel, UST multi-moeda, exibição no portal
1. Princípios
| Princípio | Detalhe |
|---|---|
| Duas moedas: BRL e USD | Todo ponto de preço pode existir em ambas |
| Organization tem moeda preferencial | Definida na org, determina exibição no portal |
| Entidade BR cobra BRL, LLC cobra USD | Moeda de pagamento segue roteamento de entidade |
| Preço BR intencionalmente mais alto | Incentiva clientes internacionais a comprar diretamente da LLC |
| Cliente vê moeda do pagamento | Se pagou em BRL, vê BRL. Se pagou em USD, vê USD. Misto possível. |
2. Preço Fixo por Moeda (Preferido)
Maioria dos produtos terá preço fixo explícito em BRL E USD:
Produto: "MIDDAG Moodle Connector — FULL"
├── BRL: R$ XXX (definido no WC)
├── USD: $ YY (definido no WC)
└── Sem conversão dinâmica — preços independentesVantagem: Preços estáveis, sem surpresas de câmbio. Admin controla diferencial BR vs LLC explicitamente.
3. Conversão Automática (Fallback)
Para produtos sem preço fixo dual-currency, conversão via faixas de câmbio:
3.1 Faixas de Câmbio
| Faixa | Uso |
|---|---|
| Low | Conversão favorável ao cliente (promoções, incentivos) |
| Medium | Próximo da cotação real (média 30 dias) — padrão |
| High | Conversão conservadora (proteção de margem) |
Valores editáveis no admin. Sem dependência de API externa — admin define manualmente.
3.2 Cascata de Fator de Conversão
Override de produto > Override de subcategoria > Override de categoria > GlobalSe produto tem fator próprio, usa esse. Senão sobe para subcategoria, categoria, e finalmente global.
3.3 Câmbio Fixo por Produto
Admin pode definir câmbio fixo por produto (ex: "1 USD = 5.00 BRL"), independente das faixas.
4. Sentinel de Preço
| Valor | Significado |
|---|---|
0.01 | "Preço sob demanda" — requer orçamento via solicitação (Jira/Quote) |
middag-account detecta sentinel 0.01 e alerta admin. Portal exibe "Entre em contato para cotação" em vez do preço.
5. UST Multi-Moeda
| Aspecto | BRL (BR) | USD (LLC) |
|---|---|---|
| Valor base do crédito | Configurável | Independente por moeda (não apenas conversão) |
| Fatores de complexidade | 1x / 1.5x / 2x | Mesmos fatores em ambas as moedas |
| Taxa de adesão | Configurável | Independente por moeda |
| Mensalidade base | Configurável | Independente por moeda |
Decisão: UST existe em ambas as moedas com valores independentes. Permite precificação específica por mercado. Serviços LLC são raros mas possíveis.
6. Moeda na Organization
| Campo | Tipo | Descrição |
|---|---|---|
preferred_currency | enum | BRL / USD — determina exibição no portal |
billing_entity | enum | middag_br / middag_global — determina moeda de pagamento |
Exibição no Portal
| Contexto | Moeda exibida |
|---|---|
| Faturas | Moeda de cada fatura (conforme pago) |
| Quotes | Moeda preferencial da Organization |
| Entitlements | Valor na moeda de compra original |
| Relatórios | Separados por entidade (colunas BRL / USD), consolidáveis |
7. Consolidação de Relatórios
| Aspecto | Detalhe |
|---|---|
| Relatórios por entidade | BR e LLC separados (padrão) |
| Visão consolidada | Opcional — converte usando faixa Medium (default) |
| Taxa de câmbio diária | Armazenada para relatórios históricos consolidados |
| Fonte da taxa | Manual (admin define) — sem API externa |