YepAPI/skills - Marketplace

Marketplace

Regras

• Modelo de dados multi-vendedor: User possui um perfil Seller — produtos pertencem a vendedores, pedidos vinculam comprador + vendedor
• Stripe Connect para pagamentos: integre vendedores com Connect Express — gerencia KYC, formulários fiscais, contas bancárias
• Comissão: calcule taxa da plataforma como porcentagem — use application_fee_amount em PaymentIntents ou Checkout Sessions
• Fluxo de garantia: capture pagamento na compra, mantenha fundos retidos, transfira para o vendedor após confirmação de entrega ou após janela de disputa
• Painel do vendedor: layout separado com análises de vendas, gerenciamento de pedidos, CRUD de produtos, histórico de pagamentos
• Avaliações comprador/vendedor: uma avaliação por pedido, em ambas as direções — agregue classificações com média ponderada
• Pesquisa com filtro por vendedor: inclua nome do vendedor, classificação, localização nos filtros de pesquisa
• Onboarding de vendedor: fluxo em várias etapas — informações comerciais → Stripe Connect → listagem de produtos → ativação

Padrões

// Stripe Connect: criar conta conectada para o vendedor
const account = await stripe.accounts.create({
  type: "express",
  email: seller.email,
  metadata: { sellerId: seller.id },
});

// Criar link de onboarding
const accountLink = await stripe.accountLinks.create({
  account: account.id,
  refresh_url: `${baseUrl}/seller/onboarding?refresh=true`,
  return_url: `${baseUrl}/seller/onboarding/complete`,
  type: "account_onboarding",
});

// Checkout com taxa da plataforma
const session = await stripe.checkout.sessions.create({
  line_items: [{ price: priceId, quantity: 1 }],
  payment_intent_data: {
    application_fee_amount: Math.round(price * 0.10), // 10% de taxa da plataforma
    transfer_data: { destination: seller.stripeAccountId },
  },
  mode: "payment",
  success_url: `${baseUrl}/orders/{CHECKOUT_SESSION_ID}`,
  cancel_url: `${baseUrl}/cart`,
});

// Esboço do modelo de dados
// sellers: id, userId, stripeAccountId, businessName, rating, status (pending|active|suspended)
// products: id, sellerId, title, price, inventory, status
// orders: id, buyerId, sellerId, status (pending|paid|shipped|delivered|disputed)
// reviews: id, orderId, reviewerId, rating, comment, type (buyer_to_seller|seller_to_buyer)

Evitar

• Transferências diretas sem garantia — retenha fundos até confirmação de entrega ou fim da janela de disputa
• Conta Stripe única para todos os vendedores — cada vendedor precisa de sua própria conta Connect para conformidade
• Deixar vendedores definirem cronogramas de pagamento — use pagamentos controlados pela plataforma para proteção contra fraudes
• Ignorar verificação do vendedor — exija conclusão do onboarding Stripe Connect antes de ativar
• Plataforma lidar com impostos dos vendedores — Stripe Connect Express gerencia a declaração fiscal dos vendedores