API Reference

A API REST do LJ Velas & Aromas segue os princípios REST e usa JSON para todos os payloads.

👉 Abrir documentação interativa (Redoc)

---

Base URLs

Ambiente	URL
Produção	https://ljvelasearomas.com.br
Desenvolvimento local	http://localhost:3000

---

Autenticação

A API possui dois mecanismos de autenticação dependendo do grupo de endpoints:

Endpoints da loja (/api/*)

Rotas protegidas utilizam cookie de sessão JWT (token), definido automaticamente após uma chamada bem-sucedida a /api/auth/login ou /api/auth/register.

# O cookie é definido automaticamente pelo servidor.
# Basta enviar as requisições com credentials: "include" no fetch.

Endpoints de integração (/api/v1/*)

Requerem API Key com prefixo lvk_ enviada no header Authorization:

Authorization: Bearer lvk_suachaveaqui

As chaves são gerenciadas no painel administrativo e possuem escopos granulares:

Escopo	Descrição
products:read	Leitura de produtos
products:write	Atualização de produtos
stock:write	Atualização de estoque
orders:read	Leitura de pedidos
orders:write	Atualização de status e rastreio

---

Endpoints disponíveis

Auth

Método	Endpoint	Descrição	Auth
POST	/api/auth/login	Login com email e senha	—
POST	/api/auth/register	Registro de novo usuário	—
POST	/api/auth/logout	Encerrar sessão	—
GET	/api/auth/me	Dados do usuário autenticado	Cookie JWT
PUT	/api/auth/me	Atualizar perfil	Cookie JWT

Loja pública

Método	Endpoint	Descrição	Auth
GET	/api/products	Listar produtos ativos	—
GET	/api/products/{slug}	Detalhe de produto por slug	—
GET	/api/categories	Listar categorias ativas	—
GET	/api/shipping/calculate	Calcular frete por CEP	—
POST	/api/coupons/validate	Validar cupom de desconto	Cookie JWT
GET	/api/orders	Listar pedidos do usuário	Cookie JWT
POST	/api/orders	Criar pedido	Cookie JWT

API de integração (v1)

Método	Endpoint	Escopo necessário
GET	/api/v1/products	products:read
GET	/api/v1/products/{id}	products:read
PATCH	/api/v1/products/{id}	products:write
PATCH	/api/v1/products/{id}/stock	stock:write
GET	/api/v1/orders	orders:read
GET	/api/v1/orders/{id}	orders:read
PATCH	/api/v1/orders/{id}	orders:write

---

Códigos de resposta comuns

Código	Significado
200	Sucesso
201	Recurso criado
400	Dados inválidos (validação Zod)
401	Não autenticado (cookie ausente, API key inválida)
403	Conta suspensa ou escopo de API key insuficiente
404	Recurso não encontrado
409	Conflito (ex: email já cadastrado)
422	Erro semântico (ex: CEP inexistente, cupom esgotado)
429	Rate limit atingido
500	Erro interno do servidor

Todos os erros retornam o body:

{
  "error": "Mensagem descritiva do erro"
}

---

Rate limits

Endpoint	Limite
POST /api/auth/login	10 tentativas / 15 min por IP
POST /api/auth/register	5 tentativas / hora por IP
POST /api/coupons/validate	30 tentativas / min por IP

Quando o limite é atingido, a resposta inclui o header Retry-After (em segundos).

---

Para a documentação interativa completa com todos os schemas e exemplos, acesse API Reference → Redoc.