Introdução ao faturamento 3PL
A cadeia de faturamento: itens → tabelas → regras por merchant → faturas, e as lacunas atuais (quantidades manuais, sem UI de faturas ainda).
A cadeia de faturamento#
Cadeia: itens de cobrança → tabelas → regras de faturamento por merchant → geração de faturas (wms_merchant_invoices + linhas). Tudo é desktop; não há faturamento no celular.
Itens de cobrança#
WMS → Billing → Itens. Criar: code (único por organização) / nome / categoria (8: storage, inbound, outbound, pick, pack, value_added, freight, other) / pricing_method (6: per_pallet_day, per_unit, per_order, per_weight, per_cubic_ft, flat) / unit_price / currency (padrão USD) / uom / is_active.
Tabelas de preços#
- WMS → Billing → Tabelas: nome + merchant_id (NULL = global, vale para todos) + versão + effective_date/expiry_date + is_active. Suporta várias versões.
- Cada linha vincula um item; unit_price_override vazio = usa o preço original. Uma linha pode ter seu próprio effective/expiry (vazio = segue a tabela).
Regras de faturamento por merchant#
WMS → Billing → Regras: uma regra por merchant (única por organização×merchant), apontando para um rate_sheet_id. Trocar de versão = trocar o rate_sheet_id.
Gerar uma fatura#
Chame POST /api/wms/billing/invoices/generate; atualmente não há página de geração no desktop, as faturas são geradas por API.
- Body: merchant_id, period_from, period_to (YYYY-MM-DD), rate_sheet_id opcional, quantities (uso, manual), notes.
- Resolução da tabela: a passada explicitamente vence; senão, usa-se a regra ativa do merchant. Sem regra → 400.
- Proteção contra duplicatas: uma fatura do mesmo período já existente é rejeitada (única por organização×merchant×período).
- Cálculo linha a linha (recalculável): unit_price = override ?? preço do item; qty de quantities (flat sem qty = 1 por padrão; linhas com qty 0 não são salvas); amount = round(qty × unit_price, 2). Cada linha carrega sua fórmula para conferência manual.
- Numeração: MINV-000001 em diante (numeração atômica); o cabeçalho é salvo com status=draft mais um snapshot da tabela, depois as linhas.
- Lacunas conhecidas: a fatura gerada para em draft; a transição sent/paid não está implementada; não há páginas de desktop de lista/detalhe/geração (as APIs GET existem); sem vínculo com o AR contábil (acc_invoices); a moeda é transportada, não convertida (Fase 1).