MIDDAG Account

Portugues

English

Portugues

English

Appearance

Faturamento e Finanças ​

Esta página explica as operações financeiras que passam pelo MIDDAG Account: geração de faturas, emissão de notas fiscais, conciliação de pagamentos, gestão de saldo de créditos e roteamento financeiro dual-entity.

Fluxo de dados financeiros ​

Geração de faturas ​

As faturas no MIDDAG Account são reflexos somente-leitura dos dados do Stripe. O sistema não gera faturas independentemente -- ele as sincroniza do Stripe via webhooks.

O fluxo do webhook:

  1. O Stripe dispara um evento (ex.: invoice.created, invoice.paid, invoice.payment_failed).
  2. O webhook atinge o endpoint apropriado (/webhooks/stripe/br ou /webhooks/stripe/llc).
  3. O sistema válida a assinatura do webhook contra o segredo específico da conta.
  4. Os dados da fatura são persistidos localmente, vinculados à Organização via Stripe Customer ID.
  5. A fatura é marcada com a conta Stripe de origem (middag_br ou middag_global).

O sistema processa múltiplos tipos de eventos de fatura: criação, atualização, pagamento, falha de pagamento, anulação e finalização. Eventos duplicados são tratados via verificações de idempotência.

Experiência do cliente: O cliente vê uma lista unificada de faturas de ambas as entidades no portal, com um indicador visual mostrando qual entidade emitiu cada uma. Eles podem filtrar por entidade, status ou período, e baixar PDFs diretamente do Stripe.

Nota fiscal (NFSe) para operações brasileiras ​

NFSe (Nota Fiscal de Serviço Eletrônica) é uma nota fiscal brasileira obrigatória para transações de serviço. É emitida exclusivamente para transações da MIDDAG BR.

Emissão automática ​

Quando um pagamento BR é confirmado:

  1. O sistema detecta que a entidade é middag_br.
  2. Extrai detalhes do serviço, valores e informações fiscais do cliente.
  3. Submete uma requisição XML ao web service do ISSNet (autoridade municipal de Brasília/DF) via SOAP.
  4. Se o ISSNet responder imediatamente com aprovação, a NFSe é registrada como issued.
  5. Se o ISSNet enfileirar para processamento, a NFSe é registrada como pending.

Verificação de status ​

Um cron job executa a cada 5 minutos para verificar NFSe pendentes:

  • Consulta o ISSNet por status atualizado.
  • Transiciona pending para issued (com o número oficial da NFSe e código de verificação) ou para rejected (com o motivo da rejeição).
  • NFSe pendentes por mais de 24 horas acionam uma notificação ao admin.

Emissão manual ​

O admin pode emitir NFSe manualmente pelo painel admin quando a emissão automática falha ou quando circunstâncias especiais requerem ajuste manual de dados (ex.: correção da descrição do serviço ou código de tributação municipal).

O que o cliente vê ​

Clientes brasileiros veem as NFSe listadas junto às faturas do Stripe no portal, com um rótulo distinto. Eles podem baixar tanto o XML (para conformidade fiscal) quanto uma versão em PDF.

Conciliação de pagamentos ​

Os dados de pagamento fluem de múltiplas fontes e precisam ser conciliados:

FonteO que cobreMecanismo de sync
Stripe BRPagamentos por cartão para entidade BRWebhooks
Stripe GLOBALPagamentos por cartão para entidade USWebhooks
Banco InterPix e Boleto para entidade BRWebhooks / callbacks

Um cron de conciliação executa a cada 15 minutos para verificar consistência entre os registros do Stripe e os dados de fatura locais. Discrepâncias são sinalizadas para análise do admin.

Faturas sem correspondência -- Quando uma fatura do Stripe não pode ser associada a uma Organização (ex.: o Stripe Customer ID não está vinculado), a fatura é armazenada com Organização nula e o admin é notificado para vinculação manual.

Gestão de saldo de créditos ​

Para entitlements SVC, o CreditBalance rastreia o consumo de UST:

OperaçãoEfeito no saldo
Serviço ativadoSaldo inicializado (pode começar em zero)
Créditos compradosSaldo aumenta
SR abertaCréditos reservados (retidos, ainda não debitados)
SR concluídaCréditos reservados debitados do saldo
SR canceladaCréditos reservados devolvidos ao saldo
Créditos expiradosSaldo diminui (conforme CreditPolicy)

A CreditPolicy governa:

  • Período de expiração para créditos inclusos (padrão: 12 meses) vs. créditos comprados (padrão: 6 meses)
  • Ordem de consumo (FIFO por padrão -- créditos mais antigos consumidos primeiro)
  • Período de carência após expiração
  • Alertas de saldo baixo (padrão: quando restam 20%)

Roteamento financeiro dual-entity ​

Toda transação financeira é roteada para a entidade legal correta:

Ponto de decisãoComo é determinado
Conta StripeBaseado na entidade de faturamento da Organização (BR ou GLOBAL)
Métodos de pagamentoBR: cartão + Pix + Boleto. GLOBAL: apenas cartão
MoedaBR: BRL. GLOBAL: USD
Nota fiscalBR: NFSe emitida via ISSNet. GLOBAL: sem nota fiscal
Portal HubSpotBR e GLOBAL possuem portais separados

Uma Organização pode ter Stripe Customer IDs e HubSpot Company IDs para ambas as entidades simultaneamente. Isso suporta clientes com transações em ambas as moedas.

Veja Operações Multi-Entidade para a lógica completa de roteamento.

Dashboard financeiro do admin ​

O painel admin oferece uma visão financeira consolidada:

  • Receita por período (mensal, trimestral, anual)
  • Receita dividida por entidade (BR vs GLOBAL)
  • Pagamentos pendentes (boletos não pagos, cartões com falha)
  • Faturas em atraso com indicadores de urgência
  • Assinaturas ativas vs canceladas

Todos os dados são originados de registros locais do WooCommerce, não diretamente do Stripe, garantindo consistência mesmo se o Stripe estiver temporariamente inacessível.

Páginas relacionadas ​