Faturas

Uma Fatura é um registro financeiro que acompanha o que foi cobrado, quando e se foi pago. No MIDDAG Account, as faturas vêm do Stripe e são sincronizadas automaticamente via webhooks. Para operações brasileiras, uma Nota Fiscal de Serviço (NFSe) complementar também pode ser gerada para conformidade fiscal.

Como as faturas são criadas

Faturas não são criadas manualmente no MIDDAG Account. Elas se originam no Stripe quando um pagamento é processado — seja de um pedido avulso, uma renovação de assinatura ou uma conversão de proposta. O sistema escuta os webhooks do Stripe e espelha os dados da fatura localmente.

O registro local é uma projeção somente leitura da fatura do Stripe. O MIDDAG Account não modifica faturas no Stripe — ele lê e exibe.

Ciclo de vida da fatura

As faturas seguem os estados nativos do Stripe:

Status	O que significa
Draft	Fatura criada, mas ainda não finalizada. Ainda pode ser editada no Stripe.
Open	Finalizada e enviada ao cliente. Aguardando pagamento.
Paid	Pagamento confirmado.
Void	Cancelada antes do pagamento.
Uncollectible	Marcada como improvável de ser cobrada.
Overdue	Vencida sem pagamento.

O sistema processa doze tipos de eventos de webhook do Stripe para manter o registro local sincronizado: invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.payment_action_required, invoice.upcoming, invoice.voided, invoice.marked_uncollectible, invoice.deleted e invoice.overdue.

Faturas com entidade dupla

Cada fatura é marcada com a conta Stripe que a gerou:

• middag_br — entidade brasileira (BRL)
• middag_global — entidade americana (USD)

A marcação é determinada por qual endpoint de webhook recebeu o evento. Admins podem filtrar faturas por entidade para relatórios financeiros e conciliação.

Vínculo com entitlements

Faturas são vinculadas a entitlements indiretamente, por meio de pedidos:

Fatura --> Pedido (via stripe_invoice_id) --> Entitlement

Isso significa que toda fatura é rastreável até o entitlement que ela suporta, oferecendo um histórico financeiro completo para qualquer registro de acesso do cliente.

Download de PDF

PDFs de fatura estão disponíveis no Stripe. Quando um cliente ou admin solicita um PDF, o sistema redireciona para a URL hospedada do Stripe ou a URL de download do PDF. Se o PDF hospedado pelo Stripe não estiver disponível, um PDF personalizado pode ser gerado localmente e armazenado no Cloudflare R2.

Conciliação

Um cron job é executado a cada 15 minutos para conciliar registros locais de fatura com o Stripe. Isso captura quaisquer webhooks que foram perdidos ou falharam, garantindo que o banco de dados local permaneça consistente com os dados do Stripe. O cron utiliza um lock para evitar execução concorrente.

Notas Fiscais de Serviço (NFSe)

Para transações processadas pela MIDDAG BR, uma Nota Fiscal de Serviço (NFSe — Nota Fiscal de Serviço Eletrônica) pode ser emitida para conformidade fiscal brasileira. As NFSe são geradas por meio da integração com o ISSNet, o serviço web da autoridade fiscal municipal de Brasília/DF.

Quando NFSe são geradas

NFSe são acionadas automaticamente quando um pagamento é confirmado para uma transação da MIDDAG BR:

1. Webhook do Stripe confirma o pagamento.
2. O sistema identifica a transação como MIDDAG BR.
3. O serviço de nota fiscal constrói o documento XML com dados do prestador (MIDDAG) e do tomador (organização).
4. O XML é enviado ao ISSNet via API SOAP.
5. Se aceito imediatamente, a NFSe é armazenada com status issued.
6. Se pendente, um cron job consulta o ISSNet a cada 5 minutos até que o status seja resolvido.

NFSe não são geradas para transações da MIDDAG GLOBAL ou para transações de valor zero.

Estados da NFSe

Status	O que significa
Pending	Enviada ao ISSNet, aguardando confirmação.
Issued	Aceita pelo ISSNet. Código de verificação atribuído.
Rejected	ISSNet rejeitou a submissão. Admin notificado.
Cancelled	Admin cancelou a NFSe com justificativa.

Emissão manual de NFSe

Admins podem emitir NFSe manualmente a partir do admin do WordPress quando a emissão automática falha ou quando é necessário emitir para uma transação que não acionou a automação. O admin revisa os dados pré-preenchidos (prestador, tomador, descrição do serviço, alíquotas) e submete.

Acesso do cliente

Clientes veem tanto faturas comerciais (do Stripe) quanto notas fiscais (NFSe) em uma lista unificada no portal, com um indicador visual distinguindo os dois tipos. Clientes podem baixar o XML (para conformidade fiscal) e o PDF de cada NFSe.

O que os admins veem

A lista de faturas no admin do WordPress mostra:

• Número da fatura
• Organização
• Valor e moeda
• Status (com indicadores de cor)
• Entidade (MIDDAG BR ou MIDDAG GLOBAL)
• Data de emissão e data de pagamento
• Link para o pedido e entitlement associados

Admins podem filtrar por entidade, status, intervalo de datas e organização.

Páginas relacionadas

• Pedidos — as compras que geram faturas
• Entitlements — os registros de acesso aos quais as faturas são rastreadas
• Entidades Jurídicas — como transações são roteadas para a entidade correta
• Propostas — propostas que se convertem em pedidos e faturas