Ir para o conteúdo

Mapa de endpoints

Toda a API REST do marketplace numa tabela só, pronta pra colar no contrato do frontend.

Convenções

  • Auth: público (sem token), user (JWT bearer), org:<role> (membro da org no role mínimo).
  • Idem: ✅ = aceita Idempotency-Key (cacheado pelo IdempotencyMiddleware).
  • Paginação: cursor por padrão; offset onde explícito.
  • Erros: todo erro vem no envelope SDK {detail, code, details}.
  • Regras X-NN: os códigos citados nas descrições (ex.: regra O-02, regra D-01) remetem à página de regras de negócio, onde cada regra está detalhada.

Auth

Método Path Auth Idem Status Descrição
POST /auth/signup público ✅ 201 Cadastro de usuário.
POST /auth/login público — 200 Login com email + senha.
POST /auth/refresh público — 200 Troca refresh por par novo.
POST /auth/logout user — 204 Revoga tokens (lista negra de jti).
GET /users/me user — 200 Perfil do usuário corrente.
PATCH /users/me user — 200 Atualiza nome / foto.
DELETE /users/me user — 204 Soft-delete (regra U-08).

Organizações

Método Path Auth Idem Status Descrição
GET /organizations user — 200 Lista orgs onde o user é membro.
POST /organizations user ✅ 201 Cria nova organização (regra O-02 ≤ 2).
GET /organizations/{id} org:MEMBER — 200 Detalhe da org.
PATCH /organizations/{id} org:OWNER — 200 Atualiza nome / slug.
DELETE /organizations/{id} org:OWNER — 202 Soft-delete + cleanup async.
POST /organizations/{id}/transfer-ownership org:OWNER ✅ 200 Passa o OWNER pra outro membro.

Membros + convites

Método Path Auth Idem Status Descrição
GET /organizations/{id}/members org:MEMBER — 200 Lista membros + role.
PATCH /organizations/{id}/members/{user_id} org:OWNER — 200 Muda role (regra M-06).
DELETE /organizations/{id}/members/{user_id} org:OWNER — 204 Remove membro.
DELETE /organizations/{id}/members/me org:MEMBER — 204 Saída voluntária (regra M-08).
POST /organizations/{id}/invitations org:ADMIN ✅ 201 Cria convite (regra I-02).
GET /organizations/{id}/invitations org:ADMIN — 200 Lista convites da org.
DELETE /organizations/{id}/invitations/{inv_id} org:ADMIN — 204 Revoga convite.
POST /invitations/{token}/accept user ✅ 200 Aceita convite (regra I-04).
POST /invitations/{token}/reject user — 204 Rejeita convite.

Catálogo público

Método Path Auth Idem Status Descrição
GET /catalog público — 200 Lista produtos ativos com estoque > 0. Cursor pagination.
GET /catalog/{product_id} público — 200 Detalhe completo do produto + variantes + preços.
GET /catalog/{product_id}/reviews público — 200 Reviews do produto, paginado.

Produtos (vendedor)

Método Path Auth Idem Status Descrição
GET /organizations/{id}/products org:MEMBER — 200 Catálogo da própria org (inclui inativos).
POST /organizations/{id}/products org:ADMIN ✅ 201 Cria produto + variantes + preço inicial (atômico).
GET /products/{id} org:MEMBER — 200 Detalhe completo.
PATCH /products/{id} org:ADMIN — 200 Atualiza metadata.
DELETE /products/{id} org:ADMIN — 204 Soft-delete.

Imagens

Método Path Auth Idem Status Descrição
POST /products/{id}/images/presign org:ADMIN — 200 Devolve URL presigned PUT (15min).
PATCH /products/{id}/images org:ADMIN — 200 Anexa lista de image_keys ao produto (max 8).
DELETE /products/{id}/images/{key} org:ADMIN — 204 Remove imagem do MinIO + da lista.

Variantes

Método Path Auth Idem Status Descrição
POST /products/{id}/variants org:ADMIN ✅ 201 Adiciona nova variante.
PATCH /variants/{id} org:ADMIN — 200 Atualiza atributos.
POST /variants/{id}/prices org:ADMIN ✅ 201 Cria nova versão de preço (regra P-05).
GET /variants/{id}/prices org:MEMBER — 200 Histórico de preços.

Estoque

Método Path Auth Idem Status Descrição
POST /variants/{id}/stock/movements org:MEMBER ✅ 201 Cria movimento (IN/OUT/ADJUST/RESERVATION/RELEASE).
GET /variants/{id}/stock/movements org:MEMBER — 200 Livro-razão, cursor pagination.
GET /variants/{id}/stock/balance org:MEMBER — 200 Saldo derivado.

Carrinho + Pedidos (comprador)

Método Path Auth Idem Status Descrição
GET /cart user — 200 Lista carrinhos abertos do user (1 por org).
POST /cart/items user ✅ 201 Adiciona variante ao carrinho da org dela.
PATCH /cart/items/{id} user — 200 Atualiza qty.
DELETE /cart/items/{id} user — 204 Remove item.
POST /orders user ✅ 201 Checkout — converte carrinho em pedido (regra D-01).
GET /orders user — 200 Lista pedidos do user, cursor pagination.
GET /orders/{id} user — 200 Detalhe + items + status atual.
GET /orders/{id}/events user — 200 SSE com transições de status em tempo real.
POST /orders/{id}/cancel user (buyer) ✅ 200 Cancela enquanto PENDING ou PAID.
POST /orders/{id}/confirm-delivery user (buyer) ✅ 200 Marca como DELIVERED.

Pedidos (vendedor)

Método Path Auth Idem Status Descrição
GET /organizations/{id}/orders org:MEMBER — 200 Lista pedidos da org, filtros por status.
POST /orders/{id}/mark-paid org:ADMIN ✅ 200 Mock de pagamento (regra D-09).
POST /orders/{id}/ship org:ADMIN ✅ 200 Marca como expedido + tracking.

Reviews

Método Path Auth Idem Status Descrição
POST /variants/{id}/reviews user (com order DELIVERED) ✅ 201 Avalia variante (regra R-01).
GET /variants/{id}/reviews público — 200 Reviews públicos.
DELETE /reviews/{id} user (autor) — 204 Apaga avaliação própria.

Notificações (mensageria em tempo real)

Um evento de domínio (pedido pago/expedido, convite, novo review) é entregue em dois canais com o mesmo payload — SSE pro app aberto (foreground) e Web Push pro app fechado (background). Detalhes no fluxo "Notificações: SSE + Web Push" em Fluxos críticos.

Método Path Auth Idem Status Descrição
GET /notifications/stream user — 200 SSE — canal por usuário (SSEBroker, channel = str(user.id)); devolve broker.response(...). Recebe todos os eventos do usuário ao vivo.
POST /api/push/subscribe user ✅ 201 Registra dispositivo no Web Push (o PushSubscription.toJSON() do browser: endpoint + chaves p256dh/auth); responde {"status": "subscribed"}. make_web_push_router.
POST /api/push/unsubscribe user — 200 Remove a inscrição do dispositivo (pelo endpoint do mesmo corpo); responde {"status": "unsubscribed"}. make_web_push_router.
GET /api/push/vapid-public-key público — 200 Chave pública VAPID ({"public_key": ...}); só montada quando make_web_push_router(vapid_public_key=...) recebe a chave.

Extras necessários

SSE (/notifications/stream) é core — não precisa de extra. As rotas /api/push/* vêm de make_web_push_router (o prefixo é o default prefix="/api/push") e precisam do extra [webpush] (uv add "tempest-fastapi-sdk[webpush]"). SSE multi-worker (Redis fan-out) precisa de [cache].

Endpoints técnicos (SDK)

Método Path Auth Descrição
GET /health/liveness público make_health_router — viva?
GET /health/readiness público viva + DB ok + Redis ok?
GET /logs X-Token make_logs_router — lê logs/*.log.
GET /metrics público (interno) Prometheus scrape (v0.28+).
GET /admin/* session admin AdminSite Jinja+HTMX.
GET /docs público Swagger UI.
GET /redoc público Redoc.

Exemplo: payload de checkout

POST /orders HTTP/1.1
Authorization: Bearer <jwt>
Idempotency-Key: chk_3e8f1c2a-9d4b-4f0a-8e7c-1234567890ab
Content-Type: application/json

{
  "cart_id": "0b9bd1b8-7e0e-4c3a-9f2c-8a1234567890",
  "shipping_address": "Av. Paulista 1000, São Paulo SP, 01310-100"
}

Resposta:

{
  "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "buyer_id": "...",
  "organization_id": "...",
  "status": "PENDING",
  "total_cents": 18990,
  "items": [
    {
      "variant_id": "...",
      "sku": "TSHIRT-M-BLACK",
      "qty": 2,
      "unit_price_cents": 9495
    }
  ],
  "idempotency_key": "chk_3e8f1c2a-9d4b-4f0a-8e7c-1234567890ab",
  "created_at": "2026-06-04T13:42:18.512Z"
}

Retentando com a mesma Idempotency-Key → mesma resposta (mesmo order.id, mesmo total_cents, sem nova RESERVATION no estoque).

Próximo passo

Volta pro índice do projeto e comece a implementar — a ordem recomendada está lá.