REF-301-04: Invoice & TaxInvoice Spec

ADR: ADR-301 — CommerceEscopo: Invoice Stripe adapter (12 webhooks, dual-account, cron sync), TaxInvoice ISSNet (emissor NFSe municipal, Brasília/DF) — SOAP integration (emissão, consulta, cancelamento), PDF generation

---

1. Invoice — Stripe Adapter

1.1 Webhooks Processados

12 tipos de webhook Stripe processados pelo InvoiceStripeService:

#	Evento	Descrição
1	invoice.created	Invoice criada no Stripe
2	invoice.updated	Campos da invoice alterados
3	invoice.finalized	Invoice finalizada (imutável)
4	invoice.sent	Invoice enviada ao cliente
5	invoice.paid	Pagamento confirmado
6	invoice.payment_failed	Tentativa de pagamento falhou
7	invoice.payment_action_required	Ação do cliente necessária (3DS, etc.)
8	invoice.upcoming	Invoice será gerada em breve (subscription)
9	invoice.voided	Invoice anulada
10	invoice.marked_uncollectible	Invoice marcada como incobrável
11	invoice.deleted	Invoice deletada (draft)
12	invoice.overdue	Invoice vencida sem pagamento

Cada evento atualiza o registro local e mantém eventual consistency entre Stripe e o domínio Invoice.

1.2 Dual Stripe Account

Invoices são taggeadas com a conta Stripe de origem:

• middag_br — Entidade brasileira (BRL)
• middag_global — Entidade LLC (USD)

Webhook handlers identificam a conta pelo endpoint secret configurado. Relatórios financeiros podem ser segregados por conta para reconciliação contábil.

1.3 Cron Sync (15 min)

Reconciliação periódica entre Stripe e registros locais:

• Intervalo: 15 minutos
• Detecta e trata divergências (webhooks perdidos, estados inconsistentes)
• Lock para evitar execução concorrente (wp_cron single-instance)

1.4 Relação com Entitlement

Invoices herdam vinculação com Entitlement via Order:

Invoice → Order (stripe_invoice_id) → Order.entitlement_id → Entitlement

• Não há campo direto entitlement_id em Invoice
• A relação é indireta: faturas vinculadas a um Order são rastreáveis até o Entitlement de origem
• PDF do Stripe disponível para download no portal do cliente

---

2. TaxInvoice — ISSNet SOAP Integration

2.1 Operações SOAP

Integração completa com API SOAP do ISSNet:

1. Emissão de NFSe — Request XML completo com todos os campos obrigatórios (prestador, tomador, serviço, valores, ISS)
2. Consulta de NFSe — Verificação de status e download do XML autorizado
3. Cancelamento de NFSe — Fluxo completo com justificativa obrigatória
4. Certificado digital — Renovação e validação automatizadas; gestão segura de chaves privadas
5. Tratamento de erros SOAP — Parsing de fault codes específicos do ISSNet
6. Logging estruturado — Todas as chamadas SOAP logadas para auditoria

2.2 Cron Sync (5 min)

Polling de NFSe pendentes no ISSNet:

• Intervalo: 5 minutos (mais frequente que Invoice por causa do polling — ISSNet não suporta webhooks)
• Verifica status de NFSe submetidas e atualiza registros locais
• Lock para evitar execução concorrente

2.3 PDF Generation

• PDFs de NFSe gerados e armazenados em R2 (Cloudflare)
• URL acessível via API REST para download no portal
• Cache de PDFs para evitar regeneração desnecessária
• Vinculação: cada TaxInvoice PDF referencia o Invoice de origem