Especificação da API REST

API Node.js para alimentar todos os componentes do Dashboard React

1. Endpoints por Seção

Visão Geral (Overview)

GET/api/v1/dashboard/overview

Retorna KPIs consolidados, gráficos de vendas, top produtos

GET/api/v1/dashboard/kpis

Retorna apenas os 4 KPIs principais (faturamento, margem, ticket, pedidos)

GET/api/v1/dashboard/sales-chart

Dados para gráfico de vendas por período (diário, semanal, mensal)

GET/api/v1/dashboard/top-products

Top 5 produtos mais vendidos com quantidade e percentual

Análise de Vendas

GET/api/v1/sales/analytics

Análise completa de vendas com comparativos e tendências

GET/api/v1/sales/by-channel

Vendas por canal (delivery, balcão, salão)

GET/api/v1/sales/by-store

Performance de vendas por loja (apenas para gestores de rede)

GET/api/v1/sales/comparison

Comparação entre períodos (dia anterior, semana anterior, mês anterior)

Hierarquia de Produtos

GET/api/v1/products/groups

Lista de grupos de produtos com métricas agregadas

GET/api/v1/products/types/:groupId

Tipos de produtos dentro de um grupo específico

GET/api/v1/products/sizes/:typeId

Tamanhos disponíveis para um tipo de produto

GET/api/v1/products/items/:sizeId

Produtos individuais de um tamanho específico

GET/api/v1/products/hierarchy

Hierarquia completa em estrutura aninhada (para drill-down)

Delivery

GET/api/v1/delivery/metrics

Métricas consolidadas de delivery (tempo médio, taxa de sucesso)

GET/api/v1/delivery/by-region

Entregas por região geográfica

GET/api/v1/delivery/peak-hours

Horários de pico de entregas

GET/api/v1/delivery/drivers

Performance dos entregadores

Financeiro

GET/api/v1/financial/dashboard

Dashboard financeiro completo (receita, margem, CMV, custos)

GET/api/v1/financial/payment-methods

Distribuição por forma de pagamento

GET/api/v1/financial/cash-flow

Fluxo de caixa por período

GET/api/v1/financial/costs

Custos operacionais detalhados

Insights de IA

GET/api/v1/ai/insights

Lista de insights gerados pela IA

GET/api/v1/ai/insights/:id

Detalhes de um insight específico

POST/api/v1/ai/insights/:id/feedback

Enviar feedback sobre um insight (útil, parcial, não útil)

2. Filtros Suportados

Query Parameters Padrão

startDate

Data inicial do período (formato: YYYY-MM-DD)

Exemplo: ?startDate=2024-01-01

endDate

Data final do período (formato: YYYY-MM-DD)

Exemplo: ?endDate=2024-01-31

storeId

ID da loja (obrigatório para gestores de loja)

Exemplo: ?storeId=123

groupId

Filtrar por grupo de produtos

Exemplo: ?groupId=5

typeId

Filtrar por tipo de produto

Exemplo: ?typeId=12

sizeId

Filtrar por tamanho de produto

Exemplo: ?sizeId=3

channel

Filtrar por canal de venda (delivery, balcao, salao)

Exemplo: ?channel=delivery

period

Período pré-definido (today, yesterday, week, month, year)

Exemplo: ?period=week

Exemplo de Requisição Completa

GET

/api/v1/sales/analytics?

startDate=2024-01-01&

endDate=2024-01-31&

storeId=123&

groupId=5&

channel=delivery

3. Payloads de Resposta (JSON)

Estrutura Padrão de Resposta

{
  "success": true,
  "data": { /* dados específicos do endpoint */ },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_abc123",
    "executionTime": 145
  }
}

Exemplo: KPIs Principais

{
  "success": true,
  "data": {
    "kpis": [
      {
        "key": "revenue",
        "label": "Faturamento Total",
        "value": 125847.50,
        "formatted": "R$ 125.847,50",
        "change": 12.5,
        "changeType": "increase",
        "icon": "ri-money-dollar-circle-line",
        "gradient": "from-emerald-500 to-teal-600"
      },
      {
        "key": "margin",
        "label": "Margem de Contribuição",
        "value": 42.3,
        "formatted": "42,3%",
        "change": 2.1,
        "changeType": "increase",
        "icon": "ri-percent-line",
        "gradient": "from-teal-500 to-cyan-600"
      },
      {
        "key": "avgTicket",
        "label": "Ticket Médio",
        "value": 67.85,
        "formatted": "R$ 67,85",
        "change": -3.2,
        "changeType": "decrease",
        "icon": "ri-shopping-cart-line",
        "gradient": "from-cyan-500 to-blue-600"
      },
      {
        "key": "orders",
        "label": "Total de Pedidos",
        "value": 1854,
        "formatted": "1.854",
        "change": 8.7,
        "changeType": "increase",
        "icon": "ri-file-list-3-line",
        "gradient": "from-blue-500 to-indigo-600"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_abc123",
    "executionTime": 145
  }
}

Exemplo: Hierarquia de Produtos

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": 1,
        "name": "Pizzas",
        "revenue": 85420.00,
        "quantity": 1247,
        "margin": 45.2,
        "percentOfTotal": 67.8,
        "types": [
          {
            "id": 5,
            "name": "Salgadas",
            "revenue": 72350.00,
            "quantity": 1089,
            "margin": 46.1,
            "sizes": [
              {
                "id": 12,
                "name": "Grande",
                "revenue": 45200.00,
                "quantity": 567,
                "margin": 47.5,
                "products": [
                  {
                    "id": 234,
                    "name": "Pizza Margherita Grande",
                    "revenue": 15680.00,
                    "quantity": 196,
                    "margin": 48.2,
                    "avgPrice": 80.00
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_def456",
    "executionTime": 287
  }
}

Exemplo: Insights de IA

{
  "success": true,
  "data": {
    "insights": [
      {
        "id": "ins_789",
        "type": "opportunity",
        "priority": "high",
        "title": "Oportunidade de Cross-sell",
        "description": "Clientes que compram Pizza Margherita têm 67% de chance de comprar Refrigerante 2L",
        "impact": "Potencial aumento de 15% no ticket médio",
        "confidence": 87,
        "action": "Criar combo promocional Pizza + Refrigerante",
        "category": "Vendas",
        "createdAt": "2024-01-15T08:00:00Z",
        "status": "active",
        "feedback": null
      },
      {
        "id": "ins_790",
        "type": "anomaly",
        "priority": "critical",
        "title": "Queda Abrupta em Vendas",
        "description": "Vendas de Pizza Calabresa caíram 34% nos últimos 3 dias",
        "impact": "Perda estimada de R$ 4.500 em receita",
        "confidence": 95,
        "action": "Verificar estoque de ingredientes e qualidade do produto",
        "category": "Operacional",
        "createdAt": "2024-01-15T09:15:00Z",
        "status": "active",
        "feedback": null
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_ghi789",
    "executionTime": 98
  }
}

4. Paginação

Parâmetros de Paginação

page

Número da página (padrão: 1)

limit

Itens por página (padrão: 20, máximo: 100)

sortBy

Campo para ordenação (ex: revenue, quantity, name)

sortOrder

Ordem de classificação (asc ou desc)

Estrutura de Resposta Paginada

{
  "success": true,
  "data": {
    "items": [ /* array de itens */ ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8,
      "hasNext": true,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_jkl012",
    "executionTime": 67
  }
}

Exemplo de Requisição Paginada

GET

/api/v1/products/items?page=2&limit=50&sortBy=revenue&sortOrder=desc

5. Padrão de Erros

Estrutura de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Parâmetros inválidos",
    "details": [
      {
        "field": "startDate",
        "message": "Data inicial é obrigatória"
      },
      {
        "field": "endDate",
        "message": "Data final deve ser posterior à data inicial"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_error123"
  }
}

Códigos de Erro HTTP

200

OK

Requisição bem-sucedida

400

Bad Request

Parâmetros inválidos ou ausentes

401

Unauthorized

Token JWT ausente ou inválido

403

Forbidden

Usuário não tem permissão para acessar o recurso

404

Not Found

Recurso não encontrado

500

Internal Server Error

Erro interno do servidor

503

Service Unavailable

Serviço temporariamente indisponível

Códigos de Erro Customizados

VALIDATION_ERRORErro de validação de parâmetros

AUTH_ERRORErro de autenticação

PERMISSION_DENIEDPermissão negada

RESOURCE_NOT_FOUNDRecurso não encontrado

DATABASE_ERRORErro ao acessar banco de dados

RATE_LIMIT_EXCEEDEDLimite de requisições excedido

6. Performance Esperada

Endpoints Rápidos

< 200ms

• /api/v1/dashboard/kpis
• /api/v1/sales/by-channel
• /api/v1/financial/payment-methods

Endpoints Médios

200ms - 500ms

• /api/v1/dashboard/overview
• /api/v1/sales/analytics
• /api/v1/delivery/metrics

Endpoints Complexos

500ms - 1s

• /api/v1/products/hierarchy
• /api/v1/financial/dashboard
• /api/v1/sales/comparison

Endpoints IA

1s - 3s

• /api/v1/ai/insights
• /api/v1/ai/generate (sob demanda)

Estratégias de Otimização

Cache Redis

TTL de 5-15 minutos para dados consolidados

Índices Otimizados

Índices compostos em data + loja + grupo

Pré-agregação

KPIs calculados em background (EOD)

Connection Pool

Pool de conexões otimizado (min: 5, max: 20)

7. Segurança (JWT + RBAC)

Autenticação JWT

Header Authorization

Todas requisições devem incluir token JWT no header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Expiração

Access Token: 1 hora | Refresh Token: 7 dias

Renovação Automática

Frontend renova token automaticamente antes da expiração

Payload do Token JWT

{
  "userId": 123,
  "email": "gestor@loja.com",
  "role": "store_manager",
  "storeId": 456,
  "networkId": 789,
  "permissions": [
    "dashboard:read",
    "sales:read",
    "products:read",
    "delivery:read"
  ],
  "iat": 1705315200,
  "exp": 1705318800
}

Controle de Acesso (RBAC)

Gestor de Rede (network_admin)

Acesso a todas lojas

Comparativos entre lojas

Dados financeiros completos

Exportação de relatórios

Configurações da rede

Gestão de usuários

Gestor de Loja (store_manager)

Acesso apenas à própria loja

Comparação com média da rede

KPIs operacionais

Insights de IA da loja

Dados de outras lojas

Margem detalhada

Analista (analyst)

Acesso a lojas autorizadas

Drill-down completo

Exportação de dados

Histórico completo

Edição de configurações

Gestão de usuários

Validação de Permissões

Middleware de Autenticação: Valida token JWT em todas requisições
Middleware de Autorização: Verifica permissões específicas por endpoint
Filtro Automático: Gestores de loja só recebem dados da própria loja
Rate Limiting: 100 requisições por minuto por usuário
Auditoria: Todas requisições são logadas com userId e timestamp

Voltar Voltar às Especificações