This is an old version of this page. You can view the most recent version or browse the history.

API Backend

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

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.

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.

Autenticação (`/api/auth`)

1. Login de Usuário

Endpoint (inferido): POST /api/auth/login
Request Body:

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

Response Body (Sucesso - 200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id": 123,
  "username": "Nome do Usuario",
  "role": "CLIENT", // ou "STORE"
  "emailVerified": true
}

2. Registro de Usuário (Cliente)

Endpoint (inferido): POST /api/auth/register
Observação: Este endpoint registra um novo usuário sempre com a role 'CLIENT'.
Request Body:

{
  "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
}

Response Body (Sucesso - 201 Created):

{
  "id": 123, // ID do novo usuário/cliente
  "email": "[email protected]",
  "name": "Nome Completo do Cliente",
  "role": "CLIENT", // Sempre retorna CLIENT no registro inicial
  "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",
  "complement": "Apto 404"
}

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:

{
  "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"
  ]
}

Exemplo de Resposta (Sucesso - 200 OK): (Retorna os dados da loja criada)

{
  "idStore": 123, //Mesmo id do user
  "storeName": "Nome Fantasia da Loja",
  "cnpj": "12345678000199",
  "address": {
    "cep": "90000111",
    "street": "Nome da Rua",
    "number": 100,
    "unit": "Loja B"
    // ... outros campos de endereço podem vir aqui
  },
  "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"
  ]
  // 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)

[
  {
    "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):

  {
    "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:

{
  "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 }
  ]
}

Response Body (Sucesso - 201 Created): (Retorna o produto criado, talvez com ID)

{
  "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)

[
  {
    "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:

{
  "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:

{
  "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:

[
  {
    "storeName": "Artesanato RS",
    "category": "Artesanato",
    "profileImgUrl": "https://exemplo.com/logo_loja.png",
    "description": "Produtos feitos à mão com amor."
  }
]

4. Retornar Galeria de Fotos da Loja

Endpoint (real): GET /api/store/store_photos/{id}
Descrição: Retorna URLs das imagens da galeria vinculadas à loja.
Exemplo de Resposta:

[
  "https://exemplo.com/foto1.jpg",
  "https://exemplo.com/foto2.jpg",
  "https://exemplo.com/foto3.jpg"
]

5. Obter Endereço Completo de uma 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:

{
  "cep": "90400000",
  "street": "Av. Independência",
  "number": 456,
  "unit": "Sala 10",
  "city": "Porto Alegre",
  "state": "RS"
}

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):

[
  {
    "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:

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

Exemplo de Resposta (201 Created):

{
  "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.

2. AddressService

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.

3. UserService

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.

4. CategoryService

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.

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.

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.

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.