Impostos e Faturas

O tratamento de impostos e a geração de faturas no MIDDAG Account envolvem três sistemas: WooCommerce (cálculo de impostos), Stripe (geração de faturas) e ISSNet (notas fiscais brasileiras). Quais sistemas estão envolvidos depende da entidade de faturamento da transação.

Roteamento de imposto dual-entity

Toda transação é roteada para a MIDDAG BR (entidade brasileira) ou MIDDAG GLOBAL (LLC nos EUA). A entidade determina quais sistemas de imposto e faturamento se aplicam:

Capacidade	MIDDAG BR	MIDDAG GLOBAL
Moeda	BRL	USD
Conta Stripe	Stripe BR	Stripe US
Fatura	Fatura Stripe (BRL)	Fatura Stripe (USD)
Nota fiscal (NFSe)	Sim -- ISSNet, Brasília/DF	Não
Métodos de pagamento	Cartão de crédito, Pix, Boleto	Cartão de crédito
Regras tributárias	Imposto municipal (ISS) + federal	Imposto dos EUA (varia por estado)

A decisão de roteamento segue esta hierarquia:

1. Atribuição explícita de entidade do produto (se o bloco de canais do produto habilita apenas uma entidade)
2. Configuração billing_entity da organização
3. Auto-detecção pelo tax ID (CNPJ = BR; EIN/VAT = GLOBAL)
4. Fallback para moeda preferida (BRL = BR; USD = GLOBAL)

O admin pode sobrescrever a entidade por transação.

Tratamento de impostos no WooCommerce

O WooCommerce gerencia o cálculo de impostos para pedidos:

• Alíquotas são configuradas em WooCommerce > Configurações > Imposto
• Classes de imposto mapeiam para tipos de produto (padrão, reduzido, isento)
• Cálculo automático de impostos usa o motor nativo do WooCommerce ou um plugin de impostos

O MIDDAG Account não sobrescreve nem duplica as configurações de imposto do WooCommerce. A configuração tributária permanece inteiramente no WooCommerce.

Faturas Stripe

O Stripe gera uma fatura para cada pagamento. O MIDDAG Account sincroniza essas faturas localmente através de webhooks:

Quando faturas são criadas

Evento	Fatura criada por
Pagamento avulso concluído	Stripe (automaticamente com a cobrança)
Renovação de assinatura paga	Stripe (automaticamente com a assinatura)
Fatura manual enviada	Admin cria no Stripe

Sincronização via webhook

O InvoiceStripeService processa webhooks de ambas as contas Stripe (BR e GLOBAL). Eventos principais:

Evento de webhook	Ação no MIDDAG Account
invoice.created	Registro local de fatura criado
invoice.finalized	Fatura marcada como finalizada (imutável)
invoice.paid	Fatura marcada como paga, vinculada ao pedido e entitlement
invoice.payment_failed	Falha de pagamento registrada, dispara política de recuperação
invoice.voided	Fatura anulada localmente
invoice.marked_uncollectible	Fatura marcada como incobrável
invoice.overdue	Fatura marcada como vencida, admin notificado

Um cron job de reconciliação roda a cada 15 minutos para capturar webhooks perdidos e resolver inconsistências de estado entre o Stripe e os registros locais.

Vínculo fatura-entitlement

Faturas são vinculadas a entitlements indiretamente através de pedidos:

Fatura Stripe -> Pedido WooCommerce -> Entitlement

Não há entitlement_id diretamente no registro da fatura. A cadeia é: a fatura referência uma cobrança Stripe, a cobrança mapeia para um pedido WC, e o pedido mapeia para o entitlement.

PDF da fatura

O Stripe gera PDFs de fatura automaticamente. Esses PDFs ficam disponíveis para download pelo cliente através do portal. O MIDDAG Account não gera seus próprios PDFs de fatura — utiliza os do Stripe.

Notas fiscais (NFSe) -- somente operações brasileiras

Para transações processadas pela MIDDAG BR, uma TaxInvoice (NFSe) -- Nota Fiscal de Serviço Eletrônica -- é emitida via sistema municipal de tributos ISSNet em Brasília/DF.

Quando a NFSe é emitida

Uma NFSe é emitida após uma fatura Stripe ser paga para uma transação da entidade BR. O fluxo:

Integração ISSNet

O domínio TaxInvoice integra com o ISSNet através de chamadas à API SOAP:

Operação	Descrição
Emitir NFSe	Submeter XML com prestador, tomador, serviço, valores de imposto
Consultar NFSe	Verificar status da NFSe submetida (autorizada, rejeitada)
Cancelar NFSe	Cancelar NFSe previamente autorizada (requer justificativa)

Como o ISSNet não suporta webhooks, um cron job de polling roda a cada 5 minutos para verificar o status de submissões de NFSe pendentes.

Armazenamento do PDF da NFSe

PDFs de NFSe autorizadas são gerados e armazenados no Cloudflare R2. Uma URL em cache fica disponível pela API REST para download no portal. Cada PDF de TaxInvoice referência a fatura Stripe de origem para rastreabilidade.

Prontidão NFSe do produto

Cada YAML de produto pode incluir campos específicos de NFSe:

nfse:
  city_service_code: "01.07"
  federal_service_code: "1.07"
  description: "Licenciamento de software"

Produtos sem esses códigos não podem ter NFSe emitida automaticamente. O relatório do catálogo (composer catalog:report) sinaliza produtos que precisam de códigos NFSe.

O que o admin vê

• Lista de faturas -- Todas as faturas Stripe sincronizadas com status, valor, moeda e entidade
• Lista de TaxInvoice -- Todos os registros de NFSe com status ISSNet (pendente, autorizada, rejeitada, cancelada)
• Visão por entitlement -- Faturas e notas fiscais vinculadas a um entitlement específico via seu pedido
• Dashboard de reconciliação -- Exibe status de sincronização entre Stripe e registros locais

Páginas relacionadas

• O Papel do WooCommerce -- fronteira entre WooCommerce e MIDDAG Account
• Mapeamento de Status de Pagamento -- mapeamento completo de status
• Reembolsos e Cancelamentos -- impacto de reembolsos nas faturas
• Pedidos -- referência do conceito de pedido