# 03 - API REST (api.uppi.app.br) ## 1. ESTRUTURA DE DIRETORIOS ``` /var/www/api.uppi.app.br/ |-- public/ | |-- index.php # Entry point: Request -> Middleware -> Router -> Controller -> Response | |-- .htaccess # Rewrite + headers seguranca | |-- health.php # Health check (PHP + MySQL + Redis) | |-- config/ | |-- app.php # JWT_SECRET, Redis, CORS, paginacao, upload | |-- database.php # Conexao db_erp (banco unico, PDO) | |-- routes.php # 148 rotas organizadas por grupo | |-- cors.php # Origens permitidas, methods, headers | |-- src/ | |-- Core/ | | |-- Router.php # Groups, params nomeados ({uuid}), middleware por rota | | |-- Request.php # fromGlobals(), bearerToken(), pagination helpers | | |-- Response.php # ok(), created(), accepted(), paginated(), error() | | |-- MiddlewarePipeline.php # Chain of Responsibility | | |-- Container.php # DI singleton + auto-wiring via Reflection | | |-- ExceptionHandler.php # 7 tipos de excecao -> HTTP status | | | |-- Middleware/ | | |-- CorsMiddleware.php # Preflight OPTIONS, origens dinamicas | | |-- AuthMiddleware.php # JWT decode, injeta user_id/type/roles/seller_id | | |-- RoleMiddleware.php # Verifica user_type ou roles | | |-- SellerMiddleware.php # Verifica seller approved no banco | | |-- RateLimitMiddleware.php # Redis sliding window (300/min auth, 100/min anon) | | |-- IdempotencyMiddleware.php # X-Idempotency-Key, cache 24h | | |-- JsonBodyMiddleware.php # Valida Content-Type (415 se invalido) | | |-- RequestLogMiddleware.php # Tempo, metodo, path, status, IP | | | |-- Auth/ | | |-- JwtService.php # HS256, 15min TTL, refresh token rt_* | | |-- PasswordService.php # Argon2id hash/verify | | | |-- Validation/ | | |-- Validator.php # 12 regras: required|email|min|max|in|uuid|etc | | | |-- Controller/ | | |-- BaseController.php # validate(), findByUuidOrFail(), paginatedQuery() | | |-- AuthController.php # register, login, me, updateMe, logout | | |-- CatalogController.php # listProducts (fulltext), getProduct, categories (tree) | | |-- AddressController.php # CRUD + setDefault | | |-- CartController.php # show, addItem, updateItem, removeItem, clear, validateCoupon | | |-- CheckoutController.php # quoteShipping, checkout (idempotent) | | |-- OrderController.php # list, show, cancel, tracking | | |-- ReturnController.php # create, list, show | | |-- WishlistController.php # list, add, remove | | |-- NotificationController.php # list, markRead, markAllRead, unreadCount | | |-- ConversationController.php # list, create, messages, sendMessage | | |-- SearchController.php # suggestions, trending | | |-- UtilController.php # lookupZipcode (ViaCEP) | | |-- ShipmentController.php # publicTracking, create, show, generateLabel, dispatch | | |-- FiscalController.php # create (202), show, cancel, cce, danfe, xml | | |-- WebhookController.php # mercadoPago, stripe, pagarme, asaas, getnet, correios, melhorEnvio | | |-- SellerProductController.php # CRUD + publish/unpublish + stock | | |-- SellerOrderController.php # list, show, accept, reject, ship, reviews | | |-- SellerFinanceController.php # dashboard, balance, entries, settlements | | |-- AdsController.php # CRUD + activate/pause/cancel + report | | |-- WmsController.php # receiving, picking, stock, inventory (17 endpoints) | | |-- AdminController.php # dashboard, sellers, orders, finance, products, disputes, coupons, config, audit, workerHealth | | | |-- Domain/ # SERVICES COMPARTILHADOS (mesmos do mkt) | | |-- (symlink ou require para app/Services do mkt) | | | |-- Exception/ | | |-- ValidationException.php # 422 | | |-- BusinessRuleException.php # 422 | | |-- NotFoundException.php # 404 | | |-- UnauthorizedException.php # 401 | | |-- ForbiddenException.php # 403 | | |-- ConflictException.php # 409 | | |-- RateLimitException.php # 429 | |-- bin/ | |-- worker.php # Entry point CLI: php bin/worker.php | |-- cron.php # Scheduler de crons | |-- workers/ | |-- QueueManager.php # Redis BRPOP, DLQ, delayed, replay | |-- JobSerializer.php # Metadata: job_id, retry_count, hostname | |-- BaseWorker.php # Graceful shutdown, memory limit, timeout, retry | |-- SchedulerWorker.php # Promove delayed jobs cada 1s | |-- OmsWorker.php # Orquestra pedidos: timeout, splits, entrega | |-- PaymentWorker.php # Estornos: order cancelled, return, shipment lost | |-- StockWorker.php # Reserva/libera por CD | |-- FulfillmentWorker.php # Picking + shipment | |-- FiscalWorker.php # Emissao NF-e SEFAZ | |-- SettlementWorker.php # Executa repasses | |-- NotificationWorker.php # Email, push, SMS, WhatsApp | |-- AdsWorker.php # Budget, fraude | |-- ReturnWorker.php # Notifica seller, processa devolucao | |-- supervisor/ | |-- uppi-workers.conf # Config Supervisor (~21 processos) ``` --- ## 2. ENDPOINTS - 148 ROTAS ### 2.1 Auth (12 endpoints) ``` POST /v1/auth/register Publico Registro customer POST /v1/auth/login Publico Login -> JWT + refresh POST /v1/auth/refresh Publico Renovar tokens POST /v1/auth/logout Auth Encerrar sessao GET /v1/auth/me Auth Perfil PUT /v1/auth/me Auth Atualizar perfil POST /v1/auth/verify-email Publico Verificar email POST /v1/auth/forgot-password Publico Solicitar reset POST /v1/auth/reset-password Publico Resetar senha POST /v1/auth/mfa/enable Auth Ativar MFA POST /v1/auth/mfa/verify Auth Verificar MFA POST /v1/auth/mfa/disable Auth Desativar MFA ``` ### 2.2 Enderecos (6 endpoints) ``` GET /v1/addresses Auth Listar POST /v1/addresses Auth Criar GET /v1/addresses/{uuid} Auth Detalhe PUT /v1/addresses/{uuid} Auth Atualizar DELETE /v1/addresses/{uuid} Auth Remover PUT /v1/addresses/{uuid}/default Auth Definir padrao ``` ### 2.3 Catalogo Publico (6 endpoints) ``` GET /v1/categories Publico Arvore categorias GET /v1/categories/{slug} Publico Detalhe GET /v1/categories/{slug}/products Publico Produtos da categoria GET /v1/products Publico Listagem com fulltext + facets GET /v1/products/{slug} Publico Detalhe com variantes GET /v1/products/{slug}/reviews Publico Avaliacoes ``` ### 2.4 Carrinho (5 endpoints) ``` GET /v1/cart Auth Ver carrinho + summary POST /v1/cart/items Auth Adicionar item PUT /v1/cart/items/{uuid} Auth Atualizar quantidade DELETE /v1/cart/items/{uuid} Auth Remover item DELETE /v1/cart Auth Limpar ``` ### 2.5 Checkout + Frete (3 endpoints) ``` POST /v1/coupons/validate Auth Validar cupom POST /v1/shipping/quote Auth Cotacao frete (multi-carrier) POST /v1/checkout Auth+Idemp Finalizar compra ``` ### 2.6 Pedidos Customer (4 endpoints) ``` GET /v1/orders Auth Listar (filtro status) GET /v1/orders/{uuid} Auth Detalhe (items, splits, payments, timeline) POST /v1/orders/{uuid}/cancel Auth Cancelar (pending/confirmed) GET /v1/orders/{uuid}/tracking Auth Rastreamento shipments ``` ### 2.7 Devolucoes (3 endpoints) ``` POST /v1/returns Auth Solicitar devolucao GET /v1/returns Auth Listar GET /v1/returns/{uuid} Auth Detalhe ``` ### 2.8 Seller Center (20+ endpoints) ``` POST /v1/sellers/register Auth Onboarding seller GET /v1/seller/products Seller Listar produtos POST /v1/seller/products Seller Criar produto GET /v1/seller/products/{uuid} Seller Detalhe PUT /v1/seller/products/{uuid} Seller Atualizar DELETE /v1/seller/products/{uuid} Seller Soft delete POST /v1/seller/products/{uuid}/publish Seller Publicar POST /v1/seller/products/{uuid}/unpublish Seller Despublicar GET /v1/seller/stock Seller Estoque PUT /v1/seller/stock/{uuid} Seller Atualizar estoque GET /v1/seller/stock/low Seller Estoque baixo GET /v1/seller/orders Seller Pedidos (splits) GET /v1/seller/orders/{id} Seller Detalhe split POST /v1/seller/orders/{id}/accept Seller Aceitar POST /v1/seller/orders/{id}/reject Seller Rejeitar POST /v1/seller/orders/{id}/ship Seller Despachar GET /v1/seller/finance/dashboard Seller Dashboard financeiro GET /v1/seller/finance/balance Seller Saldos GET /v1/seller/finance/entries Seller Extrato GET /v1/seller/finance/settlements Seller Repasses GET /v1/seller/reviews Seller Avaliacoes recebidas POST /v1/seller/reviews/{id}/reply Seller Responder ``` ### 2.9 Ads Seller (8 endpoints) ``` GET /v1/seller/ads Seller Listar campanhas POST /v1/seller/ads Seller Criar GET /v1/seller/ads/{uuid} Seller Detalhe PUT /v1/seller/ads/{uuid} Seller Atualizar POST /v1/seller/ads/{uuid}/activate Seller Ativar POST /v1/seller/ads/{uuid}/pause Seller Pausar POST /v1/seller/ads/{uuid}/cancel Seller Cancelar GET /v1/seller/ads/{uuid}/report Seller Relatorio ``` ### 2.10 WMS - Operador CD (17 endpoints) ``` POST /v1/wms/receiving Operator Criar recebimento GET /v1/wms/receiving/{id} Operator Detalhe POST /v1/wms/receiving/{id}/check Operator Conferir item POST /v1/wms/receiving/{id}/complete Operator Finalizar GET /v1/wms/picking Operator Listar picking GET /v1/wms/picking/{id} Operator Detalhe + progresso POST /v1/wms/picking/{id}/start Operator Iniciar POST /v1/wms/picking/{id}/pick Operator Scanear item POST /v1/wms/picking/{id}/complete Operator Finalizar GET /v1/wms/stock Operator Consultar estoque GET /v1/wms/stock/{id}/movements Operator Historico movimentacoes POST /v1/wms/stock/transfer Operator Transferir locacao POST /v1/wms/inventory Operator Criar contagem GET /v1/wms/inventory/{id} Operator Detalhe POST /v1/wms/inventory/{id}/count Operator Registrar contagem POST /v1/wms/inventory/{id}/submit Operator Submeter POST /v1/wms/inventory/{id}/approve Operator Aprovar (supervisor) ``` ### 2.11 TMS + Fiscal (11 endpoints) ``` POST /v1/shipments Auth Criar envio GET /v1/shipments/{uuid} Auth Detalhe POST /v1/shipments/{uuid}/label Auth Gerar etiqueta POST /v1/shipments/{uuid}/dispatch Auth Registrar despacho GET /v1/tracking/{code} Publico Rastreamento publico POST /v1/fiscal/emit Auth Emitir NF-e (202) GET /v1/fiscal/{uuid} Auth Detalhe POST /v1/fiscal/{uuid}/cancel Auth Cancelar POST /v1/fiscal/{uuid}/cce Auth Carta correcao GET /v1/fiscal/{uuid}/danfe Auth Download PDF GET /v1/fiscal/{uuid}/xml Auth Download XML ``` ### 2.12 Webhooks (7 endpoints) ``` POST /v1/webhooks/mercadopago Publico Validacao por assinatura POST /v1/webhooks/stripe Publico Validacao por assinatura POST /v1/webhooks/pagarme Publico Validacao por assinatura POST /v1/webhooks/asaas Publico Validacao por assinatura POST /v1/webhooks/getnet Publico Validacao por assinatura POST /v1/webhooks/correios Publico Eventos tracking POST /v1/webhooks/melhor-envio Publico Eventos tracking ``` ### 2.13 Admin (26 endpoints) ``` GET /v1/admin/dashboard Admin KPIs, top sellers/produtos GET /v1/admin/sellers Admin Listar sellers GET /v1/admin/sellers/{id} Admin Detalhe POST /v1/admin/sellers/{id}/approve Admin Aprovar POST /v1/admin/sellers/{id}/suspend Admin Suspender PUT /v1/admin/sellers/{id}/commission Admin Alterar comissao GET /v1/admin/orders Admin Listar todos GET /v1/admin/orders/{uuid} Admin Detalhe POST /v1/admin/orders/{uuid}/force-status Admin Forcar status GET /v1/admin/finance/overview Admin Visao geral GET /v1/admin/finance/settlements Admin Repasses POST /v1/admin/finance/settlements/{id}/approve Admin Aprovar POST /v1/admin/finance/settlements/{id}/execute Admin Executar GET /v1/admin/finance/reconciliation Admin Conciliacao GET /v1/admin/products/pending Admin Produtos para revisao POST /v1/admin/products/{uuid}/approve Admin Aprovar POST /v1/admin/products/{uuid}/reject Admin Rejeitar GET /v1/admin/disputes Admin Disputas POST /v1/admin/disputes/{uuid}/resolve Admin Resolver GET /v1/admin/coupons Admin Listar cupons POST /v1/admin/coupons Admin Criar PUT /v1/admin/coupons/{id} Admin Atualizar DELETE /v1/admin/coupons/{id} Admin Desativar GET /v1/admin/settings Admin Configuracoes PUT /v1/admin/settings Admin Atualizar GET /v1/admin/audit Admin Log auditoria ``` ### 2.14 Utilidades (6 endpoints) ``` POST /v1/wishlist Auth Adicionar DELETE /v1/wishlist/{uuid} Auth Remover GET /v1/wishlist Auth Listar GET /v1/search/suggestions Publico Autocomplete GET /v1/search/trending Publico Top 10 GET /v1/utils/zipcode/{cep} Publico Consulta CEP (ViaCEP) ``` ### 2.15 Chat (4 endpoints) ``` GET /v1/conversations Auth Listar conversas POST /v1/conversations Auth Iniciar conversa GET /v1/conversations/{id}/messages Auth Mensagens POST /v1/conversations/{id}/messages Auth Enviar ``` --- ## 3. AUTENTICACAO E SEGURANCA ### JWT - **Algoritmo:** HS256 - **TTL Access Token:** 15 minutos - **TTL Refresh Token:** 7 dias (30 dias com "lembrar-me") - **Payload:** sub (uuid), user_id, user_type, roles, seller_id, warehouse_id, iat, exp, iss - **Secret:** via $_ENV['JWT_SECRET'] ### Rate Limiting (Redis) - Global por IP: 100 req/min - Autenticado: 300 req/min - Webhook: 1000 req/min - Search: 30 req/min - **Fail-open:** Redis indisponivel nao bloqueia ### Envelope de Resposta ```json // Sucesso { "success": true, "data": {...}, "meta": { "request_id": "...", "timestamp": "..." } } // Lista paginada { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 20, "total": 150, "total_pages": 8, "has_next": true }, "meta": {...} } // Erro { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } } ``` --- ## 4. WORKERS ASSINCRONOS ### Configuracao por Worker | Worker | Fila | Processos | Max Retries | Timeout | Memoria | |--------|------|-----------|-------------|---------|---------| | OMS | queue:oms | 2 | 5 | 120s | 256MB | | Payment | queue:payment | 2 | 5 | 60s | 128MB | | Stock | queue:stock | 3 | 3 | 30s | 128MB | | Fulfillment | queue:fulfillment | 2 | 3 | 60s | 128MB | | Fiscal | queue:fiscal | 2 | 5 | 180s | 256MB | | Settlement | queue:settlement | 1 | 3 | 120s | 128MB | | Notification | queue:notification | 3 | 3 | 30s | 128MB | | Ads | queue:ads | 2 | 2 | 15s | 128MB | | Return | queue:return | 1 | 3 | 60s | 128MB | | **Scheduler** | (delayed:*) | 1 | - | - | 64MB | | **TOTAL** | | **21** | | | | ### Mapa de Eventos -> Filas ``` order.created -> oms order.confirmed -> oms order.cancelled -> oms, stock, payment order.splits_created -> stock order.delivered -> oms payment.paid -> oms, fiscal payment.failed -> oms payment.refund_requested -> payment stock.reserved -> fulfillment stock.low -> notification picking.completed -> fulfillment shipment.shipped -> notification shipment.delivered -> settlement, notification shipment.lost -> payment fiscal.authorized -> notification return.requested -> return, notification return.refunded -> payment settlement.created -> settlement ``` ### Retry com Backoff Exponencial ``` Tentativa 1: 30s Tentativa 2: 120s (2min) Tentativa 3: 300s (5min) Tentativa 4: 900s (15min) Tentativa 5: 3600s (1h) Apos max retries: move para DLQ ```