API Backend

Home	Escopo e Cronograma	Processo	Design/Mockups	Configuração	Arquitetura	Infra	Código	BD	Frontend	API Backend

Coopera RS - Documentação da API Backend

Visão Geral

Esta documentação descreve os principais endpoints da API do Coopera RS, uma plataforma voltada para o fortalecimento de pequenos empreendedores do Rio Grande do Sul.

O backend do projeto foi construído com Java + Spring Boot adotando arquitetura hexagonal, que visa a separação de responsabilidades entre domínio, aplicação e infraestrutura, permitindo maior manutenibilidade e testes mais eficazes.

Estrutura de Pastas

Observação: O diretório shared contém classes, funções e estruturas reutilizáveis que não pertencem a uma camada específica da arquitetura. Ele é utilizado para:

Exceções personalizadas compartilhadas (ex: UserNotFoundException)

Utilitários genéricos (ex: manipulação de datas, validações)

DTOs e Enums comuns a mais de uma camada

Mensagens padronizadas de erro/sucesso

Isso promove reuso, evita duplicação e mantém o domínio e a infraestrutura mais limpos.

O projeto segue a seguinte estrutura base:

├── application      # Casos de uso (serviços de aplicação)
├── domain           # Entidades de negócio, agregados, interfaces
├── infrastructure   # Implementações técnicas (controladores, repositórios, clientes HTTP)
├── config           # Arquivos de configuração (segurança, Swagger, JWT)
├── shared           # Utilitários e exceções comuns

Os endpoints são expostos por meio de controladores REST no módulo infrastructure, que dependem apenas das portas definidas no domain. O Swagger está configurado para facilitar a exploração da API.

Exemplos de Payloads JSON por Endpoint

Autenticação

`POST /api/auth/login`

{
  "email": "[email protected]",
  "password": "senha123"
}

`POST /api/auth/register`

{
  "name": "Nome do Cliente",
  "email": "[email protected]",
  "password": "senhaSegura123",
  "phone": "51999998888",
  "cep": "90000000",
  "address": "Rua Exemplo",
  "number": "123",
  "complement": "Apto 404"
}

`GET /api/auth/userAddress/{id}`

Retorna os dados de endereço de um usuário.

`POST /api/auth/linkPasswordChange`

{
  "email": "[email protected]"
}

Usuário vira Loja

`POST /api/store/create`

{
  "idUser": 123,
  "storeName": "Loja Teste",
  "cnpj": "12345678000199",
  "addressDTO": {
    "cep": "90000111",
    "street": "Rua Teste",
    "number": 100,
    "unit": "Loja 1"
  },
  "description": "Loja de exemplo",
  "profileImgUrl": "https://exemplo.com/perfil.jpg",
  "gallery": [
    "https://exemplo.com/foto1.jpg",
    "https://exemplo.com/foto2.jpg"
  ]
}

Lojas

`GET /api/stores`

Lista todas as lojas.

`GET /api/search/stores?q=termo`

Busca lojas por termo.

`GET /api/store/by-category/{categoryId}`

Lojas por categoria.

`GET /api/store/store_photos/{id}`

Galeria de fotos da loja.

`GET /api/store/get-address/{id}`

Endereço completo da loja.

`GET /api/store/{id}`

(Real) Retorna detalhes da loja por ID.

`PATCH /api/store/update-description`

(Real) Atualiza descrição de uma loja.

{
  "idStore": 123,
  "description": "Nova descrição da loja."
}

Produtos

`POST /api/product/create`

{
  "name": "Bolsa Artesanal",
  "description": "Feita à mão",
  "photo": "https://exemplo.com/bolsa.jpg",
  "category": "Acessórios",
  "characteristics": [
    { "name": "Cor", "options": ["Bege", "Marrom"] }
  ],
  "variations": [
    { "options": { "Cor": "Bege" }, "price": 79.9, "stock": 3 }
  ]
}

`GET /api/products`

Lista geral de produtos.

`GET /api/search/products?q=termo`

Busca por nome/descrição.

`GET /api/stores/{storeId}/products`

Produtos de uma loja.

Carrinho

`GET /api/cart`

Lista os itens do carrinho atual do usuário.

`POST /api/cart/add`

Adiciona um item:

{
  "productId": 88,
  "variation": { "Cor": "Bege" },
  "quantity": 2
}

`DELETE /api/cart/remove/{productId}`

Remove um item.

Patrocínios (SponsorService)

⚠️ Em desenvolvimento — Os endpoints abaixo fazem parte da infraestrutura do serviço SponsorService, mas ainda podem não estar acessíveis via Swagger.

`GET /api/sponsor/products`

Retorna lista de produtos patrocinados (em destaque na plataforma).

`GET /api/sponsor/stores`

Retorna lista de lojas patrocinadas.

`POST /api/sponsor/product`

Adiciona destaque a um produto.

{
  "productId": 123,
  "priority": 1
}

`POST /api/sponsor/store`

Adiciona destaque a uma loja.

{
  "storeId": 456,
  "priority": 2
}

Serviços Internos

EmailService: Envio de e-mails (cadastro, redefinição).
AddressService: Busca e atualização de endereços por CEP.
UserService: Atualização de perfil, status de verificação e ativação.
CategoryService: (em expansão) Criação e vinculação de categorias.
SponsorService: (planejado) Destaque de produtos/lojas.