Skip to content

GitLab

API Backend · Changes

Page history
Update API Backend authored by Tomás Bringhenti Onofrio's avatar Tomás Bringhenti Onofrio
Show whitespace changes
Inline Side-by-side
API-Backend.md
View page @ 98744cdb
<table>
<tr>
<th> [Home](home) </th>
<th> [Escopo e Cronograma](escopo e cronograma) </th>
<th> [Processo](processo) </th>
<th> [Design/Mockups](design/mockups) </th>
<th> [Configuração](configuracao) </th>
<th> [Arquitetura](arquitetura) </th>
<th> [Infra](infraestrutura) </th>
<th> [Código](codigo) </th>
<th> [BD](banco de dados) </th>
<th> [Frontend](Frontend) </th>
<th> [API Backend](API-Backend) </th>
</tr>
</table>
| [Home](home) | [Escopo e Cronograma](escopo%20e%20cronograma) | [Processo](processo) | [Design/Mockups](design/mockups) | [Configuração](configuracao) | [Arquitetura](arquitetura) | [Infra](infraestrutura) | [Código](codigo) | [BD](banco%20de%20dados) | [Frontend](Frontend) | [API Backend](API-Backend) |
|--------------|-------------------------|----------------|------------------------|---------------------|--------------------|-------------------|--------------|------------------|----------------|------------------|
---
<div align="center">
<img src="uploads/df63c1ae8acde46d4d1f45f6ab1cd9a5/LogoCooperaRS.png" width="150">
</div>
---
# Exemplos de Payloads JSON para Endpoints da API
Esta seção fornece exemplos de estruturas JSON para as requisições (requests) e respostas (responses) dos principais endpoints da API do Coopera-RS, baseados nas interfaces TypeScript e mocks encontrados no frontend.
# Coopera RS - Documentação da API Backend
**Observação:** Os endpoints exatos (URLs e métodos HTTP) precisam ser confirmados com a documentação do backend (Swagger), mas os formatos de dados aqui apresentados servem como guia.
## Visão Geral
## Autenticação (`/api/auth`)
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.
### 1. Login de Usuário
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.
* **Endpoint (inferido):** `POST /api/auth/login`
* **Request Body:**
### Estrutura de Pastas
O projeto segue a seguinte estrutura base:
```json
{
"email": "[email protected]",
"password": "senha123"
}
```
├── 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)
```
* **Response Body (Sucesso - 200 OK):**
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.
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"id": 123,
"username": "Nome do Usuario",
"role": "CLIENT", // ou "STORE"
"emailVerified": true
}
```
---
## Sumário
### 2. Registro de Usuário (Cliente)
## Exemplos de Payloads JSON por Endpoint
* **Endpoint (inferido):** `POST /api/auth/register`
* **Observação:** Este endpoint registra um novo usuário sempre com a role **'CLIENT'**.
* **Request Body:**
### Autenticação
#### `POST /api/auth/login`
```json
{
"name": "Nome Completo do Cliente",
"email": "[email protected]",
"password": "senhaSegura123",
"phone": "51999998888",
"cep": "90000000",
"address": "Rua Exemplo", // Endereço residencial do cliente
"number": "123",
"complement": "Apto 404" // Opcional
"email": "[email protected]",
"password": "senha123"
}
```
* **Response Body (Sucesso - 201 Created):**
#### `POST /api/auth/register`
```json
{
"id": 123, // ID do novo usuário/cliente
"name": "Nome do Cliente",
"email": "[email protected]",
"name": "Nome Completo do Cliente",
"role": "CLIENT", // Sempre retorna CLIENT no registro inicial
"password": "senhaSegura123",
"phone": "51999998888",
"active": true, // ou false, exclusão logica
"verified": false, // ou true, dependendo da verificação de email
"cep": "90000000",
"address": "Rua Exemplo",
"number": "123",
......@@ -88,320 +60,81 @@ Esta seção fornece exemplos de estruturas JSON para as requisições (requests
}
```
### 3. Atualizar Cliente para Vendedor/Loja
* **Endpoint :** `POST /api/store/create` (requer autenticação como cliente)
* **Observação:** Este fluxo permite que um usuário 'CLIENT' existente se torne um 'STORE', adicionando informações da loja. O ID do usuário é mantido e compartilhado pela loja.
* **Request Body:**
#### `GET /api/auth/userAddress/{id}`
Retorna os dados de endereço de um usuário.
#### `POST /api/auth/linkPasswordChange`
```json
{
"idUser": 123, // ID do usuário que está criando a loja
"storeName": "Nome Fantasia da Loja",
"cnpj": "12345678000199",
"addressDTO": {
"cep": "90000111",
"street": "Nome da Rua",
"number": 100,
"unit": "Loja B"
},
"description": "Descrição detalhada da loja e seus produtos.",
"profileImgUrl": "https://exemplo.com/imagem_perfil.jpg",
"gallery": [
"https://exemplo.com/foto_galeria1.jpg",
"https://exemplo.com/foto_galeria2.jpg"
]
"email": "[email protected]"
}
```
* **Exemplo de Resposta (Sucesso - 200 OK):** (Retorna os dados da loja criada)
---
### Usuário vira Loja
#### `POST /api/store/create`
```json
{
"idStore": 123, //Mesmo id do user
"storeName": "Nome Fantasia da Loja",
"idUser": 123,
"storeName": "Loja Teste",
"cnpj": "12345678000199",
"address": {
"addressDTO": {
"cep": "90000111",
"street": "Nome da Rua",
"street": "Rua Teste",
"number": 100,
"unit": "Loja B"
// ... outros campos de endereço podem vir aqui
"unit": "Loja 1"
},
"description": "Descrição detalhada da loja e seus produtos.",
"profileImgUrl": "https://exemplo.com/imagem_perfil.jpg",
"description": "Loja de exemplo",
"profileImgUrl": "https://exemplo.com/perfil.jpg",
"gallery": [
"https://exemplo.com/foto_galeria1.jpg",
"https://exemplo.com/foto_galeria2.jpg"
]
// ID do usuário associado pode ou não ser retornado aqui
}
```
## Lojas (`/api/stores` - exemplos)
### 1. Listar Lojas
* **Endpoint (inferido):** `GET /api/stores` ou `GET /api/search/stores?q={termo}`
* **Response Body (Sucesso - 200 OK):** (Array de Lojas)
```json
[
{
"name": "Loja Tecidos Nossa Senhora",
"description": "Somos uma empresa tradicional e que ao longo de seus 60 anos consolidou sua posição no setor têxtil.",
"CEP": "90000000",
"address": "Av. Guaíba, 2658 - Porto Alegre/RS", // Verificar formato do endereço
"number": "2658",
"complement": "apt 4",
"rating": 8.4,
"photo": "https://picsum.photos/1000/1000",
},
{
"name": "Estilo & Cia",
"description": "Outra descrição...",
"CEP": "90000000",
"address": "Av. Guaíba, 2658 - Porto Alegre/RS", // Verificar formato do endereço
"number": "2658",
"complement": "apt 4",
"rating": 8.4,
"photo": "https://picsum.photos/1000/1000",
}
// ... mais lojas
]
```
### 2. Listar produtos de uma loja
* **Endpoint (inferido):** `GET /api/stores/{storeId}/products` ou similar
* **Response Body (Sucesso - 200 OK):**
```json
{
"name": "Camiseta Esportiva Dry Fit",
"description": "Camiseta leve e respirável, ideal para atividades físicas.",
"photo": "https://picsum.photos/id/1041/200/300",
"category": "Roupas",
"characteristics": [
{ "name": "Cor", "options": ["Azul", "Preto"] },
{ "name": "Tamanho", "options": ["P", "M", "G"] },
],
"variations": [
{ "options": { "Cor": "Azul", "Tamanho": "P" }, "price": 90.9, "stock": 10 },
{ "options": { "Cor": "Preto", "Tamanho": "M" }, "price": 80.9, "stock": 5 },
],
"views": 120,
"date": "2025-05-01",
},
{
"name": "Calça Jeans Slim Fit",
"description": "Calça jeans com corte ajustado e confortável.",
"photo": "https://picsum.photos/id/1042/200/300",
"category": "Roupas",
"characteristics": [
{ "name": "Cor", "options": ["Azul Claro", "Azul Escuro"] },
{ "name": "Tamanho", "options": ["38", "40", "42"] },
],
"variations": [
{ "options": { "Cor": "Azul Claro", "Tamanho": "38" }, "price": 89.9, "stock": 8 },
{ "options": { "Cor": "Azul Escuro", "Tamanho": "40" }, "price": 89.9, "stock": 12 },
],
"views": 200,
"date": "2025-04-28",
},
//... mais produtos
```
## Produtos (`/api/products` - exemplos)
### 1. Adicionar Produto
* **Endpoint (inferido):** ex: `POST /api/stores/{storeId}/products`)
* **Request Body:**
```json
{
"name": "Calça Jeans Slim Fit",
"description": "Calça jeans com corte ajustado e confortável.",
"photo": "URL_DA_IMAGEM_BASE64_OU_LINK", // Verificar como a imagem é enviada
"category": "Roupas",
"characteristics": [
{ "name": "Cor", "options": ["Azul Claro", "Azul Escuro"] },
{ "name": "Tamanho", "options": ["38", "40", "42"] }
],
"variations": [
{ "options": { "Cor": "Azul Claro", "Tamanho": "38" }, "price": 89.9, "stock": 8 },
{ "options": { "Cor": "Azul Escuro", "Tamanho": "40" }, "price": 89.9, "stock": 12 }
"https://exemplo.com/foto1.jpg",
"https://exemplo.com/foto2.jpg"
]
}
```
* **Response Body (Sucesso - 201 Created):** (Retorna o produto criado, talvez com ID)
```json
{
"id": "produto-12345", // ID gerado pelo backend
"name": "Calça Jeans Slim Fit",
"description": "Calça jeans com corte ajustado e confortável.",
"photo": "URL_DA_IMAGEM_ARMAZENADA",
"category": "Roupas",
"characteristics": [
{ "name": "Cor", "options": ["Azul Claro", "Azul Escuro"] },
{ "name": "Tamanho", "options": ["38", "40", "42"] }
],
"variations": [
{ "options": { "Cor": "Azul Claro", "Tamanho": "38" }, "price": 89.9, "stock": 8 },
{ "options": { "Cor": "Azul Escuro", "Tamanho": "40" }, "price": 89.9, "stock": 12 }
],
"views": 0,
"date": "2025-06-06" // Data de criação
}
```
### 2. Listar Produtos
* **Endpoint (inferido):** `GET /api/products` ou `GET /api/search/products?q={termo}`
* **Response Body (Sucesso - 200 OK):** (Array de Produtos)
```json
[
{
"name": "Camiseta Esportiva Dry Fit",
"description": "Camiseta leve e respirável, ideal para atividades físicas.",
"photo": "https://picsum.photos/id/1041/200/300",
"category": "Roupas",
"characteristics": [
{ "name": "Cor", "options": ["Azul", "Preto"] },
{ "name": "Tamanho", "options": ["P", "M", "G"] }
],
"variations": [
{ "options": { "Cor": "Azul", "Tamanho": "P" }, "price": 59.9, "stock": 10 },
{ "options": { "Cor": "Preto", "Tamanho": "M" }, "price": 59.9, "stock": 5 }
],
"views": 120,
"date": "2025-05-01"
},
// ... mais produtos
]
```
### 1. Obter Endereço do Usuário
* **Endpoint (real):** `GET /api/auth/userAddress/{id}`
* **Descrição:** Retorna os dados de endereço associados ao ID do usuário.
* **Exemplo de Resposta:**
```json
{
"cep": "90000000",
"street": "Rua das Palmeiras",
"number": 123,
"unit": "Apto 202",
"city": "Porto Alegre",
"state": "RS"
}
```
---
### 2. Gerar Link para Redefinição de Senha
* **Endpoint (real):** `POST /api/auth/linkPasswordChange`
* **Descrição:** Gera e envia um link por e-mail para redefinição de senha.
* **Request Body:**
```json
{
"email": "[email protected]"
}
```
---
### 3. Listar Lojas por Categoria
* **Endpoint (real):** `GET /api/store/by-category/{categoryId}`
* **Descrição:** Retorna lojas que pertencem à categoria informada.
* **Exemplo de Resposta:**
```json
[
{
"storeName": "Artesanato RS",
"category": "Artesanato",
"profileImgUrl": "https://exemplo.com/logo_loja.png",
"description": "Produtos feitos à mão com amor."
}
]
```
---
### Lojas
### 4. Retornar Galeria de Fotos da Loja
#### `GET /api/stores`
Lista todas as lojas.
* **Endpoint (real):** `GET /api/store/store_photos/{id}`
* **Descrição:** Retorna URLs das imagens da galeria vinculadas à loja.
* **Exemplo de Resposta:**
#### `GET /api/search/stores?q=termo`
Busca lojas por termo.
```json
[
"https://exemplo.com/foto1.jpg",
"https://exemplo.com/foto2.jpg",
"https://exemplo.com/foto3.jpg"
]
```
#### `GET /api/store/by-category/{categoryId}`
Lojas por categoria.
---
#### `GET /api/store/store_photos/{id}`
Galeria de fotos da loja.
### 5. Obter Endereço Completo de uma Loja
#### `GET /api/store/get-address/{id}`
Endereço completo da loja.
* **Endpoint (real):** `GET /api/store/get-address/{id}`
* **Descrição:** Retorna o endereço completo de uma loja pelo seu ID.
* **Exemplo de Resposta:**
#### `GET /api/store/{id}`
**(Real)** Retorna detalhes da loja por ID.
#### `PATCH /api/store/update-description`
**(Real)** Atualiza descrição de uma loja.
```json
{
"cep": "90400000",
"street": "Av. Independência",
"number": 456,
"unit": "Sala 10",
"city": "Porto Alegre",
"state": "RS"
"idStore": 123,
"description": "Nova descrição da loja."
}
```
---
### 6. Buscar Produtos ou Lojas por Termo
* **Endpoint (real):** `GET /api/search/products?q=termo`
* **Endpoint (real):** `GET /api/search/stores?q=termo`
* **Descrição:** Retorna lista de produtos ou lojas que contenham o termo informado.
* **Exemplo de Resposta (produtos):**
```json
[
{
"name": "Tênis de Corrida",
"description": "Tênis leve e confortável para treino",
"price": 199.9,
"photo": "https://exemplo.com/tenis.jpg"
}
]
```
---
### 7. Criar Produto (Loja Autenticada)
* **Endpoint (real):** `POST /api/product/create`
* **Descrição:** Cria um novo produto para a loja autenticada.
* **Request Body:**
### Produtos
#### `POST /api/product/create`
```json
{
"name": "Bolsa Artesanal",
"description": "Feita à mão com material sustentável",
"description": "Feita à mão",
"photo": "https://exemplo.com/bolsa.jpg",
"category": "Acessórios",
"characteristics": [
......@@ -413,64 +146,44 @@ Esta seção fornece exemplos de estruturas JSON para as requisições (requests
}
```
* **Exemplo de Resposta (201 Created):**
```json
{
"id": 88,
"name": "Bolsa Artesanal",
"category": "Acessórios",
"photo": "https://exemplo.com/bolsa.jpg",
"views": 0,
"date": "2025-06-19"
}
```
---
## Funcionalidades Internas (Serviços não expostos diretamente via API)
Embora alguns serviços ainda não possuam endpoints públicos mapeados, eles fazem parte da lógica do backend do Coopera RS e oferecem funcionalidades internas importantes:
### 1. EmailService
* Responsável pelo envio de e-mails de confirmação de cadastro, recuperação de senha e outras comunicações.
* Integração com serviços de e-mail configurados via `.env`.
* Pode utilizar templates personalizados para mensagens automáticas.
---
#### `GET /api/products`
Lista geral de produtos.
### 2. AddressService
#### `GET /api/search/products?q=termo`
Busca por nome/descrição.
* Gerencia dados de endereço vinculados a usuários e lojas.
* Realiza buscas e formatações de endereço.
* Suporta consultas por ID e vinculação via CEP.
#### `GET /api/stores/{storeId}/products`
Produtos de uma loja.
---
### 3. UserService
### Carrinho
* Gerencia dados de usuários, como ativação, desativação, verificação e atualização de perfil.
* Funciona como camada intermediária entre autenticação, loja e dados pessoais.
#### `GET /api/cart`
Lista os itens do carrinho atual do usuário.
---
### 4. CategoryService
#### `POST /api/cart/add`
Adiciona um item:
```json
{
"productId": 88,
"variation": { "Cor": "Bege" },
"quantity": 2
}
```
* Prevê suporte para criação, listagem e categorização de produtos e lojas.
* Embora o `CategoryController` ainda não tenha endpoints, esta camada de serviço já está preparada.
#### `DELETE /api/cart/remove/{productId}`
Remove um item.
---
### 5. SponsorService
* Prevê suporte para funcionalidades relacionadas a patrocínio ou destaque de lojas e produtos na plataforma.
* O controller correspondente está definido, porém ainda sem rotas mapeadas.
---
## Serviços Internos
Esses serviços fazem parte da estrutura modular do backend e poderão ser ativados e documentados com mais profundidade à medida que as features forem implementadas.
- **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.
---
*Estes são apenas exemplos baseados no código frontend. É crucial validar e complementar esta informação com a documentação oficial da API (Swagger) do backend.*