Backend API - Documentação Técnica

Status (pronto x faltando)

Pronto

Conteúdo descrito neste documento.

Faltando

Confirmar no código o estado real das funcionalidades e atualizar esta seção conforme necessário.

Visão Geral

API de alta performance em Go para o marketplace SaveInMed. Implementa Clean Architecture com foco em operações críticas de negócio.

Arquitetura

cmd/api/           → Ponto de entrada
internal/
├── config/        → Configurações e env vars
├── domain/        → Entidades e regras de negócio
├── http/
│   ├── handler/   → HTTP handlers (controllers)
│   └── middleware/→ Auth JWT, CORS, logging
├── payments/      → Gateways: Stripe, MercadoPago, Mock
├── repository/    → Camada de persistência (PostgreSQL)
├── server/        → Setup do servidor HTTP
└── usecase/       → Casos de uso (serviços)

Taxa Invisível do Marketplace

O sistema aplica uma taxa invisível ao comprador (6%) e uma comissão do vendedor (6%). O comprador vê apenas o valor final, sem linha separada de taxa:

Vendedor cadastra:  R$ 10,00
Comprador vê:       R$ 10,60 (+6% buyer fee invisível)
Marketplace recebe: R$ 1,20 (6% buyer + 6% seller)
Vendedor recebe:    R$ 9,40

Configuração: BUYER_FEE_RATE=0.06 e SELLER_FEE_RATE=0.06

Gateways de Pagamento

Gateway	Arquivo	Descrição
Stripe	`stripe.go`	Cartões internacionais
MercadoPago	`mercadopago.go`	Pix, boleto, cartões
Mock	`mock.go`	Testes (auto-aprova)

Endpoints Principais

Autenticação

POST /api/v1/auth/register - Cadastro
POST /api/v1/auth/login - Login
POST /api/v1/auth/refresh-token - Renovar token

Produtos

GET /api/v1/products - Listar (preço final com taxa invisível de 6% para compradores)
GET /api/v1/products/search - Busca avançada
POST /api/v1/products - Cadastrar

Pedidos

GET /api/v1/orders - Listar
POST /api/v1/orders - Criar

Variáveis de Ambiente

DATABASE_URL=postgres://...
JWT_SECRET=your-secret
BUYER_FEE_RATE=0.06
SELLER_FEE_RATE=0.06
MARKETPLACE_COMMISSION=2.5
BACKEND_PORT=8080

Executar

cd backend
go run ./cmd/api

Testes

go test ./... -cover

Para matriz completa (com/sem banco e Playwright), veja: docs/TESTES.md

2.4 KiB Raw Blame History