Construir um marketplace parece simples: catálogo + carrinho + checkout. Até você ter o segundo vendedor e descobrir que precisa: dividir o pagamento, emitir nota fiscal por venda, segurar o repasse até a entrega, devolver dinheiro de pedido cancelado sem virar uma lavadeira manual e ainda aceitar PIX (porque cliente brasileiro pede). Bem-vindo ao buraco do coelho.

Aqui está como resolvemos esses três pilares no Comércio Digital.

1. Stripe Connect: o split que evita virar banco

Se você processa o pagamento total e depois transfere para o seller via TED/PIX, você está operando como instituição de pagamento sem autorização do BACEN. Não faça isso. O Stripe Connect resolve com 3 contas:

  • Platform Account: a sua empresa
  • Connected Account: cada seller, criada via OnboardingLink
  • Customer: o comprador

Em cada pagamento, você define application_fee_amount (sua comissão) e o Stripe automaticamente:

  • Cobra o comprador
  • Retém sua comissão na conta platform
  • Credita o saldo na conta do seller (com hold period configurável)

O hold period (escrow) é o detalhe que evita 90% das dores: o seller só recebe depois da entrega confirmada, então cancelamento e reembolso são triviais. Implementamos 7 dias por padrão.

Webhooks que importam

  • checkout.session.completed — confirma o pagamento
  • charge.refunded — devolução parcial ou total
  • charge.dispute.created — chargeback (cliente abriu reclamação no cartão)
  • payout.paid — repasse efetivo para o seller
Toda mudança de estado vira evento no ledger append-only. Reconciliação no fim do mês é uma query, não três dias de planilha.

2. NFS-e: a parte chata que precisa funcionar

Cada município tem seu webservice, padrão de XML e regras. Implementamos uma state machine que abstrai isso:

NOT_CONFIGURED → READY_TO_ISSUE → ISSUED → CANCELED

O que precisa estar pronto antes do ISSUED:

  • FiscalProfile do seller: CNPJ, inscrição municipal, regime tributário, código de serviço
  • Tomador: CPF/CNPJ e endereço completos do comprador
  • Item: descrição, valor, código de serviço, retenções aplicáveis
  • Validação: ISS calculado, alíquota correta, base de cálculo conferida

Cada transição é logada no fiscal event ledger: quem disparou, quando, qual foi o payload da prefeitura, qual o número do protocolo. Auditoria fiscal vira pesquisa SQL.

Para municípios fora do padrão ABRASF (que ainda é a maioria), usamos gateways como NFE.io e Nuvem Fiscal como adaptadores — assim o core fica limpo.

3. PIX: o método que o brasileiro já assumiu

O Stripe ainda não tem PIX nativo bem integrado para o Brasil. Resolvemos com Asaas como provider secundário:

  • Cartão (crédito, débito) → Stripe
  • PIX, boleto → Asaas
  • Mesmo modelo de Order, mesmo ledger, mesmo fluxo de webhook

Para o cliente final, é um único checkout. Para o seller, um único painel. Para você operador, uma única reconciliação. O paymentOrchestrator encapsula o "qual provider".

Webhook idempotency

Webhook é entregue mais de uma vez. Sempre. Trate event.id como chave única e use UPSERT idempotente. Sua tabela WebhookEvent existe para isso — sem ela, você vai duplicar pagamentos no primeiro pico.

4. Estoque com lotes (FIFO) — o pulo do gato logístico

Em marketplace físico, dois pedidos chegam ao mesmo tempo para o último item em estoque. Quem ganha? Sem isolation level certo, ambos ganham — e você perde dinheiro reembolsando.

Implementamos:

  • InventoryLot: cada entrada vira lote com quantidade, validade, custo
  • Reserva atômica: transação SERIALIZABLE que decrementa quantityAvailable
  • FIFO: consumimos primeiro o lote mais antigo (importante para validade e custo médio)
  • Invariante: quantityAvailable >= 0 garantida no banco com CHECK

5. Logística com Melhor Envio

Cálculo de frete no carrinho, compra de etiqueta após confirmação, rastreio automático — três endpoints da API Melhor Envio + uma camada de cache para não estourar rate limit. O cliente vê o status atualizado no painel; o seller imprime a etiqueta com 1 clique.

Conclusão: peças prontas vs. construir do zero

Dá para fazer tudo isso do zero. Levamos 9 meses para a primeira versão estável. Se você está começando agora, ou usa Magento/Nuvemshop/Shopify (e aceita as limitações), ou usa uma base pronta como o Comércio Digital e foca em diferencial de produto, não em encanamento.

Para ver o sistema em ação: página do produto ou solicite uma demo.