MOTO ROTAS/ Documentação
← Voltar
Motorotas Backend API

Documentação da API

Referência completa da API RESTful para gerenciar estabelecimentos, motoboys, pedidos e avaliações com segurança empresarial.

🛡️
Segurança
Autenticação JWT com RBAC completo, validações Zod e proteção de rotas sensíveis
📊
Observabilidade
Eventos de entrega, métricas em tempo real e relatórios consolidados para administradores
🚀
Escalabilidade
Arquitetura modular, Prisma ORM compatível com múltiplos bancos e estrutura preparada para crescimento

Início Rápido

Configure o ambiente em minutos

1
npm install

Instala dependências do projeto

2
cp config/env.example .env

Configura variáveis de ambiente

3
npx prisma migrate dev

Aplica migrações (exige DIRECT_DATABASE_URL com acesso Postgres direto)

4
npm run dev

Inicia servidor de desenvolvimento

Documentação

Explore os recursos e funcionalidades da API

🏗️

Arquitetura

Camada backend baseada em Next.js 15 (App Router) com Prisma ORM e autenticação JWT. Utiliza TypeScript integral e validações com Zod para garantir contratos consistentes.

  • Prisma + Postgres (Neon) por padrão
  • Bootstrap automático de usuário administrador baseado em variáveis de ambiente
  • Utilitários centralizados em '@/lib' (auth, erros, RBAC, cliente Prisma)
  • Estrutura REST modular em 'src/app/api', separada por domínio
⚙️

Variáveis de Ambiente

Defina o arquivo .env a partir de config/env.example antes de executar o projeto.

  • DATABASE_URL – string do Prisma Data Proxy (Prisma Accelerate)
  • JWT_SECRET – segredo de assinatura JWT (mínimo 16 caracteres)
  • DEFAULT_ADMIN_EMAIL / DEFAULT_ADMIN_PASSWORD – credenciais iniciais do administrador
🔐

Fluxo de Autenticação

O login retorna um token JWT que deve ser enviado no header Authorization com o formato Bearer. Utilizamos RBAC para filtrar acesso por papéis.

  • POST /api/auth/register – cadastro de usuário (motoboy ou estabelecimento)
  • POST /api/auth/login – autenticação e emissão de token
  • GET /api/auth/me – informações do usuário autenticado
  • Papéis disponíveis: ADMIN, ESTABLISHMENT, MOTOBOY
📦

Módulos Principais

Cada módulo possui validações dedicadas (Zod) e regras de negócio aplicadas em handlers Next.js.

  • Estabelecimentos – cadastro completo, métricas, planos, ativação
  • Motoboys – documentação, disponibilidade em tempo real, métricas de desempenho
  • Pedidos – criação, atualização de status, eventos e rastreamento público
  • Avaliações – feedback bidirecional entre empresas e motoboys
  • Relatórios – visão consolidada para administradores

Referência da API

Endpoints principais e suas permissões de acesso

MétodoEndpointDescriçãoPermissões
POST/api/auth/loginAutenticação e emissão de token JWTPúblico
POST/api/auth/registerCadastro de novo usuário (estabelecimento ou motoboy)Público
GET/api/auth/meInformações do usuário autenticadoAutenticado
GET/api/establishmentsLista estabelecimentos com métricas agregadasAdmin / Dono
POST/api/establishmentsCria novo estabelecimentoAdmin
GET/api/motoboysLista motoboys com métricas de desempenhoAdmin / Estab.
POST/api/motoboysCadastra novo motoboy com validaçõesAdmin
GET/api/ordersLista pedidos filtrados por papel do usuárioAdmin / Estab. / Motoboy
POST/api/ordersCria novo pedido de entregaAdmin / Estab.
POST/api/orders/:id/assignAtribui motoboy ao pedido e registra eventoAdmin / Estab.
PATCH/api/orders/:id/assignMotoboy aceita, rejeita ou completa entregaMotoboy
GET/api/tracking/:codeRastreamento público de entrega por códigoPúblico
GET/api/reports/summaryResumo executivo para painel administrativoAdmin
🛡️

Segurança

Autenticação JWT com RBAC completo, validações Zod e proteção de rotas sensíveis

📊

Observabilidade

Eventos de entrega, métricas em tempo real e relatórios consolidados para administradores

🚀

Escalabilidade

Arquitetura modular, Prisma ORM compatível com múltiplos bancos e estrutura preparada para crescimento