Documentação da API

Guia completo para integrar com a Ecommerce API. Esta documentação cobre todos os endpoints, autenticação, modelos de dados e exemplos de uso.

🚀 Começando

A Ecommerce API é uma API RESTful construída com Ruby on Rails que fornece todos os endpoints necessários para um e-commerce completo.

📦 Instalação

Com Docker (Recomendado)

git clone https://github.com/seu-usuario/ecommerce-api.git
cd ecommerce-api
docker-compose up --build

Instalação Local

# Instalar dependências
bundle install

# Criar e popular banco de dados
rails db:create db:migrate db:seed

# Iniciar servidor
rails server

🔐 Autenticação

A API utiliza autenticação JWT (JSON Web Tokens) via Devise Token Auth. Após o login, você recebe tokens nos headers da resposta que devem ser incluídos em todas as requisições autenticadas.

Registro de Usuário

{
  "name": "João Silva",
  "email": "joao@email.com",
  "password": "minhasenha123",
  "password_confirmation": "minhasenha123"
}

{
  "status": "success",
  "data": {
    "id": 1,
    "email": "joao@email.com",
    "name": "João Silva",
    "profile": "client",
    "provider": "email",
    "uid": "joao@email.com"
  }
}

Login

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

access-token: eyJhbGciOiJIUzI1NiJ9...
token-type: Bearer
client: abc123xyz789...
expiry: 1705612800
uid: joao@email.com

Headers de Autenticação

Inclua estes headers em todas as requisições que exigem autenticação:

Exemplo com cURL

curl -X GET http://localhost:3000/storefront/v1/profile \
  -H "Content-Type: application/json" \
  -H "access-token: eyJhbGciOiJIUzI1NiJ9..." \
  -H "client: abc123xyz789..." \
  -H "uid: joao@email.com"

Logout

Recuperar Senha

{
  "email": "joao@email.com",
  "redirect_url": "http://seusite.com/reset-password"
}

🛒 Storefront API - Produtos

Endpoints públicos para navegação de produtos no catálogo.

{
  "products": [
    {
      "id": 1,
      "name": "MacBook Pro 14\"",
      "description": "Laptop Apple M3 Pro",
      "price": "12999.00",
      "stock_quantity": 15,
      "category": {
        "id": 2,
        "name": "Notebooks"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 5,
    "total_count": 48
  }
}

🏷️ Storefront API - Categorias

{
  "categories": [
    {
      "id": 1,
      "name": "Eletrônicos",
      "description": "Dispositivos eletrônicos",
      "subcategories": [
        { "id": 2, "name": "Notebooks" },
        { "id": 3, "name": "Smartphones" }
      ]
    }
  ]
}

📦 Storefront API - Pedidos

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

{
  "id": 42,
  "status": "pending",
  "total": "26997.00",
  "created_at": "2026-01-17T10:30:00Z",
  "items": [
    {
      "product_id": 1,
      "product_name": "MacBook Pro",
      "quantity": 2,
      "unit_price": "12999.00",
      "subtotal": "25998.00"
    },
    {
      "product_id": 5,
      "product_name": "Mouse Magic",
      "quantity": 1,
      "unit_price": "999.00",
      "subtotal": "999.00"
    }
  ]
}

👤 Storefront API - Perfil

{
  "user": {
    "name": "João Silva Santos",
    "password": "novasenha123",
    "password_confirmation": "novasenha123"
  }
}

⚙️ Admin API

Dashboard

{
  "stats": {
    "total_users": 1250,
    "total_products": 89,
    "total_orders": 3420,
    "total_categories": 15,
    "pending_orders": 23,
    "processing_orders": 12,
    "shipped_orders": 45,
    "active_products": 82,
    "out_of_stock_products": 7
  }
}

Gerenciar Produtos

Criar Produto

{
  "product": {
    "name": "iPhone 15 Pro Max",
    "description": "Smartphone Apple com chip A17 Pro",
    "price": 9999.00,
    "stock_quantity": 50,
    "category_id": 3,
    "active": true
  }
}

Gerenciar Categorias

Criar Categoria com Subcategoria

{
  "category": {
    "name": "Smartphones",
    "description": "Telefones celulares",
    "parent_id": 1,  // Subcategoria de Eletrônicos
    "active": true
  }
}

Gerenciar Pedidos

Status do Pedido

Atualizar Status

{
  "order": {
    "status": "shipped"
  }
}

Gerenciar Usuários

📊 Modelos de Dados

Diagrama ER

User

Product

Order

📋 Status Codes HTTP

⚠️ Tratamento de Erros

Todas as respostas de erro seguem um formato padronizado:

Erro de Validação (422)

{
  "errors": {
    "name": ["não pode ficar em branco"],
    "email": ["já está em uso", "não é válido"],
    "price": ["deve ser maior que 0"]
  }
}

Erro de Autenticação (401)

{
  "errors": ["Token de autenticação inválido ou expirado"]
}

Erro de Permissão (403)

{
  "errors": ["Acesso negado. Permissão de administrador necessária."]
}

Recurso Não Encontrado (404)

{
  "errors": ["Produto não encontrado"]
}