# ADR-001 — Billing Broker (precificação por mensagem)

| Campo | Valor |
| :---- | :---- |
| Status | Aceito (desenho) — implementação pendente |
| Data | 2026-07-24 |
| Decisores | Time OmniMeta |

## Contexto

A partir de **01/10/2026**, mensagens de serviço e utility dentro da janela de atendimento passam a ser cobradas no modelo **per-message pricing (PMP)** da Meta (e equivalentes nos parceiros, ex.: Gupshup). O OmniMeta já persiste metadados `pricing` em `messages`, mas **não calcula valores monetários**, não mantém rate card dinâmico e não entrega custo consolidado ao cliente.

Hoje `messages` pode ser apagado por comando (`DeleteOldMessageData`); billing exige retenção própria e auditoria.

## Decisão

1. Introduzir um **ledger imutável** `billing_events`, desacoplado de `messages`.
2. Calcular custo real: `total = meta_fee + partner_fee + omni_fee` (no go-live, `omni_fee = 0`), com markup futuro via `billing_markup_rules`.
3. Persistir preços em collections configuráveis (`billing_rate_cards`, `billing_partner_fees`), sem deploy para mudança de tabela.
4. Entregar dados por **API REST + webhook** `BILLING_UPDATE` (ambos).
5. Guardar valores na **moeda de origem**; converter FX apenas na consulta, se pedido.
6. Idempotência por `idempotency_key` estável + `revision` (revisão reenvia webhook com mesmo `id` / `eventId`).
7. Mensagens `billable=false` **fora** do ledger por padrão; toggle `include_non_billable` em `billing_settings`.
8. **Meta Business Agent** fora da v1 (apenas slot de `category` no schema).
9. Modelo legado (conversation-based) **fora de escopo**.

## Consequências

### Positivas

- Cliente consome contrato unificado independente do parceiro.
- Reconciliação alinhada à fatura do parceiro (mesma moeda no ledger).
- Extensível a novos parceiros via adapter + rate card.

### Negativas / trade-offs

- Mais collections e jobs de resolução de preço.
- Cliente precisa tratar revisões (`revision`) no consumidor do webhook.
- Rate cards desatualizados geram eventos com `price_resolved=false` até backfill.

## Alternativas consideradas

| Alternativa | Motivo da rejeição |
| :---------- | :----------------- |
| Só enriquecer `messages.pricing` | Retenção curta / comando de purge; sem ledger auditável |
| Só API (sem webhook) | Cliente precisa de push em tempo real, como status de mensagem |
| Só webhook (sem API) | Sem auditoria/reconciliação histórica adequada |
| FX no momento do cálculo | Divergência vs fatura do parceiro |

## Referências

- [BILLING_BROKER](../modules/BILLING_BROKER.md)
- [NAMING_CONVENTIONS](../standards/NAMING_CONVENTIONS.md)
- Evidência atual de `pricing` em `messages`: `api/app/Models/Message.php`, `MessageProcessing.php`, `NormalizeIncomingWebhookPayloadUseCase.php`