API RESTful v1.0

API Completa para
E-commerce Moderno

Uma API robusta e escalável construída com Ruby on Rails, oferecendo autenticação JWT, gestão de produtos, pedidos e muito mais. Pronta para produção.

Testar Demo App Documentação Completa Começar Agora GitHub 
# Exemplo de requisição - Criar um pedido
POST /storefront/v1/orders
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

{
  "order": {
    "items": [
      { "product_id": 1, "quantity": 2 },
      { "product_id": 3, "quantity": 1 }
    ]
  }
}

# Response 201 Created
{
  "id": 42,
  "status": "pending",
  "total": "299.97",
  "items_count": 3
}

Métricas do Projeto

Números que demonstram a robustez e completude desta API

25+
Endpoints REST
5
Models Completos
100%
Cobertura Auth
<50ms
Response Time
2
Namespaces API
SQLite
Database Ready
JWT
Autenticação
Docker
Container Ready

Recursos Principais

Tudo que você precisa para construir um e-commerce completo

Autenticação JWT Completa

Sistema de autenticação robusto usando Devise Token Auth com tokens JWT. Suporte a registro, login, logout, recuperação de senha e atualização de perfil.

Controle de Acesso por Perfil

Sistema de permissões com perfis de Admin e Cliente. Endpoints administrativos protegidos e área pública para navegação de produtos.

Gestão de Produtos

CRUD completo de produtos com categorização hierárquica, controle de estoque, preços e status de ativação. Filtros e busca avançada.

Sistema de Pedidos

Fluxo completo de pedidos com múltiplos itens, cálculo automático de totais, workflow de status e histórico de compras por cliente.

Categorias Hierárquicas

Sistema de categorias com suporte a subcategorias, permitindo organização flexível do catálogo de produtos.

Dashboard Administrativo

Endpoint de estatísticas com contagem de usuários, produtos, pedidos e métricas do sistema para painéis de controle.

┌─────────────────────────────────────────────────┐
│                   CLIENT                        │
│        (Web App / Mobile / Third Party)         │
└───────────────────────┬─────────────────────────┘
                        │ HTTPS
                        ▼
┌─────────────────────────────────────────────────┐
│              RAILS API SERVER                   │
│  ┌─────────────────────────────────────────┐   │
│  │           Authentication Layer           │   │
│  │         (Devise Token Auth + JWT)        │   │
│  └─────────────────────────────────────────┘   │
│                        │                        │
│  ┌──────────────┐  ┌──────────────┐            │
│  │   ADMIN      │  │  STOREFRONT  │            │
│  │   /admin/v1  │  │/storefront/v1│            │
│  │              │  │              │            │
│  │ • Categories │  │ • Products   │            │
│  │ • Products   │  │ • Categories │            │
│  │ • Orders     │  │ • Orders     │            │
│  │ • Users      │  │ • Profile    │            │
│  │ • Dashboard  │  │ • Home       │            │
│  └──────────────┘  └──────────────┘            │
│                        │                        │
│  ┌─────────────────────────────────────────┐   │
│  │              MODELS LAYER                │   │
│  │  User │ Category │ Product │ Order       │   │
│  └─────────────────────────────────────────┘   │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│                 DATABASE                        │
│             (SQLite / PostgreSQL)               │
└─────────────────────────────────────────────────┘

Arquitetura RESTful

  • API Versionada Namespaces separados (v1) para evolução sem breaking changes
  • Separação Admin/Storefront Endpoints administrativos isolados dos públicos
  • Autenticação Stateless Tokens JWT sem necessidade de sessões no servidor
  • Responses JSON Respostas padronizadas com status codes HTTP corretos

Exemplos de Uso

Veja como interagir com a API em diferentes cenários

POST /auth/v1/user

Registro de Usuário

{
  "name": "João Silva",
  "email": "joao@email.com",
  "password": "senha123",
  "password_confirmation": "senha123"
}
POST /auth/v1/user/sign_in

Login

{
  "email": "joao@email.com",
  "password": "senha123"
}

// Response Headers:
// access-token: xyz123...
// client: abc789...
// uid: joao@email.com
GET /storefront/v1/products

Listar Produtos (Público)

// Query params opcionais:
?category_id=1
&search=notebook
&page=1
&per_page=10

// Response
{
  "products": [...],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 48
  }
}
GET /storefront/v1/products/:id

Detalhes do Produto

{
  "id": 1,
  "name": "MacBook Pro 14\"",
  "description": "Laptop Apple M3",
  "price": "12999.00",
  "stock_quantity": 15,
  "category": {
    "id": 2,
    "name": "Notebooks"
  }
}
POST /storefront/v1/orders

Criar Pedido (Auth Required)

// Headers necessários:
// access-token, client, uid

{
  "order": {
    "items": [
      { "product_id": 1, "quantity": 1 },
      { "product_id": 5, "quantity": 2 }
    ]
  }
}
GET /storefront/v1/orders

Meus Pedidos

{
  "orders": [
    {
      "id": 42,
      "status": "shipped",
      "total": "15498.00",
      "items_count": 3,
      "created_at": "2026-01-15..."
    }
  ]
}
POST /admin/v1/products

Criar Produto (Admin Only)

{
  "product": {
    "name": "iPhone 15 Pro",
    "description": "Smartphone Apple",
    "price": 8999.00,
    "stock_quantity": 50,
    "category_id": 3,
    "active": true
  }
}
GET /admin/v1/home

Dashboard Stats

{
  "stats": {
    "total_users": 1250,
    "total_products": 89,
    "total_orders": 3420,
    "total_categories": 15,
    "pending_orders": 23,
    "active_products": 82
  }
}

Endpoints da API

Referência completa de todos os endpoints disponíveis

🔐 Autenticação

Método Endpoint Descrição Auth
POST /auth/v1/user Registrar novo usuário Público
POST /auth/v1/user/sign_in Login (retorna tokens) Público
DELETE /auth/v1/user/sign_out Logout Token
POST /auth/v1/user/password Solicitar reset de senha Público

🛒 Storefront (Loja)

Método Endpoint Descrição Auth
GET /storefront/v1/products Listar produtos (com filtros) Público
GET /storefront/v1/products/:id Detalhes do produto Público
GET /storefront/v1/categories Listar categorias Público
GET /storefront/v1/orders Meus pedidos Token
POST /storefront/v1/orders Criar pedido Token
GET /storefront/v1/profile Ver meu perfil Token
PUT /storefront/v1/profile Atualizar perfil Token

⚙️ Admin

Método Endpoint Descrição Auth
GET /admin/v1/home Dashboard com estatísticas Admin
GET /admin/v1/categories Listar todas categorias Admin
POST /admin/v1/categories Criar categoria Admin
GET /admin/v1/products Listar todos produtos Admin
POST /admin/v1/products Criar produto Admin
GET /admin/v1/orders Listar todos pedidos Admin
PUT /admin/v1/orders/:id/status Atualizar status do pedido Admin
GET /admin/v1/users Listar usuários Admin

Stack Tecnológico

Tecnologias modernas e confiáveis

Ruby

3.2.2

Rails

7.0.x

SQLite

Database

JWT

Auth Tokens

Devise

Authentication

Docker

Container

Puma

Web Server

CORS

Cross-Origin

🚀 Quick Start

Configure e execute a API em minutos

1

Clone o Repositório

git clone https://github.com/seu-usuario/ecommerce-api.git
cd ecommerce-api
2

Com Docker (Recomendado)

docker-compose up --build

# API disponível em:
# http://localhost:3000
3

Ou Instalação Local

bundle install
rails db:create db:migrate db:seed
rails server
4

Teste a API

# Admin login:
curl -X POST http://localhost:3000/auth/v1/user/sign_in \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ecommerce.com","password":"password123"}'