CultivUA - API
1.0.1

Base URL
http://localhost:8000

API para gestão da aplicação web CultivUA. Desenvolvido por:

This is version 1.0.1 of this API documentation. Last update on Jan 2, 2025.

Blog posts

Obter todas as categorias de publicações do blog

GET /blog-posts/categories

Retorna uma lista de todas as categorias de publicações disponíveis.

Responses

  • 200

    Categorias de publicações retornadas com sucesso

  • 500

    Erro ao obter as categorias

GET /blog-posts/categories
curl \
 --request GET 'http://localhost:8000/blog-posts/categories'

Listar todos os posts

GET /blog-posts

Retorna uma lista com todos os posts do blog, incluindo informações sobre comentários, categoria e autor.

Responses

  • 200

    Lista de posts retornada com sucesso

  • 500

    Erro interno do servidor

GET /blog-posts
curl \
 --request GET 'http://localhost:8000/blog-posts'

Criar um novo post

POST /blog-posts

Cria um novo post no blog, incluindo título, conteúdo, categoria, imagem e status.

Responses

  • 201

    Post criado com sucesso

  • 400

    Dados inválidos ou incompletos

POST /blog-posts
curl \
 --request POST 'http://localhost:8000/blog-posts'

Exibir um post específico

GET /blog-posts/{id}

Retorna um post específico com seus comentários, categoria e autor, identificado pelo ID.

Path parameters

  • id integer Required

Responses

  • 200

    Post encontrado com sucesso

  • 404

    Post não encontrado

GET /blog-posts/{id}
curl \
 --request GET 'http://localhost:8000/blog-posts/{id}'

Atualizar um post existente

PUT /blog-posts/{id}

Atualiza as informações de um post existente no blog.

Path parameters

  • id integer Required

Responses

  • 200

    Post atualizado com sucesso

  • 400

    Dados inválidos

  • 404

    Post não encontrado

PUT /blog-posts/{id}
curl \
 --request PUT 'http://localhost:8000/blog-posts/{id}'

Remover um post

DELETE /blog-posts/{id}

Remove um post do blog, identificado pelo ID.

Path parameters

  • id integer Required

Responses

  • 200

    Post excluído com sucesso

  • 404

    Post não encontrado

DELETE /blog-posts/{id}
curl \
 --request DELETE 'http://localhost:8000/blog-posts/{id}'

Listar comentários de um post

GET /blog-posts/{postId}/comments

Retorna todos os comentários de um post específico.

Path parameters

  • postId integer Required

    ID do post

Responses

  • 200 application/json

    Comentários encontrados com sucesso.

    Hide response attributes Show response attributes object
    • comment_id integer
    • username string
    • profile_image string | null
    • comment_text string
    • commented_at string(date-time)
    • isVisible boolean
GET /blog-posts/{postId}/comments
curl \
 --request GET 'http://localhost:8000/blog-posts/{postId}/comments'
Response examples (200)
[
  {
    "comment_id": 42,
    "username": "string",
    "profile_image": "string",
    "comment_text": "string",
    "commented_at": "2025-05-04T09:42:00Z",
    "isVisible": true
  }
]

Criar um novo comentário

POST /blog-posts/add-comment

Permite a criação de um novo comentário.

application/json

Body Required

  • comment_text string

    Texto do comentário.

  • user_id integer

    ID do utilizador que fez o comentário.

  • post_id integer

    ID do post ao qual o comentário pertence.

Responses

  • 201 application/json

    Comentário criado com sucesso.

    Hide response attributes Show response attributes object
    • id integer
    • comment_text string
    • created_at string(date-time)
    • user object

      Additional properties are allowed.

      Hide user attributes Show user attributes object
      • username string
      • profile_image string | null
POST /blog-posts/add-comment
curl \
 --request POST 'http://localhost:8000/blog-posts/add-comment' \
 --header "Content-Type: application/json" \
 --data '{"comment_text":"string","user_id":42,"post_id":42}'
Request examples
{
  "comment_text": "string",
  "user_id": 42,
  "post_id": 42
}
Response examples (201)
{
  "id": 42,
  "comment_text": "string",
  "created_at": "2025-05-04T09:42:00Z",
  "user": {
    "username": "string",
    "profile_image": "string"
  }
}

Atualizar visibilidade de um comentário

PUT /blog-posts/comments/{commentId}

Atualiza a visibilidade de um comentário específico.

Path parameters

  • commentId integer Required

    ID do comentário a ser atualizado.

application/json

Body Required

  • isVisible boolean

    Definir visibilidade do comentário (verdadeiro ou falso).

Responses

  • 200 application/json

    Visibilidade do comentário atualizada com sucesso.

    Hide response attribute Show response attribute object
    • message string
PUT /blog-posts/comments/{commentId}
curl \
 --request PUT 'http://localhost:8000/blog-posts/comments/{commentId}' \
 --header "Content-Type: application/json" \
 --data '{"isVisible":true}'
Request examples
{
  "isVisible": true
}
Response examples (200)
{
  "message": "Visibilidade do comentário atualizada"
}

Deletar um comentário

DELETE /blog-posts/comments/{commentId}/delete

Deleta um comentário específico.

Path parameters

  • commentId integer Required

    ID do comentário a ser excluído.

Responses

  • 200 application/json

    Comentário excluído com sucesso.

    Hide response attribute Show response attribute object
    • message string
  • 404 application/json

    Comentário não encontrado.

    Hide response attribute Show response attribute object
    • error string
DELETE /blog-posts/comments/{commentId}/delete
curl \
 --request DELETE 'http://localhost:8000/blog-posts/comments/{commentId}/delete'
Response examples (200)
{
  "message": "Comentário excluído com sucesso"
}
Response examples (404)
{
  "error": "Comentário não encontrado"
}

Categories

Obter lista de categorias

GET /categories

Retorna todas as categorias no sistema com a contagem de produtos.

Responses

  • 200 application/json

    Lista de categorias retornada com sucesso

    Hide response attributes Show response attributes object
    • id integer
    • name string
    • mostrarLoja boolean
    • mostrarBlog boolean
    • number integer

      Número de produtos na categoria

GET /categories
curl \
 --request GET 'http://localhost:8000/categories'
Response examples (200)
[
  {
    "id": 42,
    "name": "string",
    "mostrarLoja": true,
    "mostrarBlog": true,
    "number": 42
  }
]

Adicionar nova categoria

POST /categories

Cria uma nova categoria no sistema.

application/json

Body Required

  • name string

Responses

  • 201 application/json

    Categoria criada com sucesso

    Hide response attributes Show response attributes object
    • message string
    • category object

      Additional properties are allowed.

      Hide category attributes Show category attributes object
      • id integer
      • name string
  • 409 application/json

    Conflito, a categoria já existe

    Hide response attributes Show response attributes object
    • message string
    • category object

      Additional properties are allowed.

      Hide category attributes Show category attributes object
      • id integer
      • name string
POST /categories
curl \
 --request POST 'http://localhost:8000/categories' \
 --header "Content-Type: application/json" \
 --data '{"name":"Vegetables"}'
Request examples
{
  "name": "Vegetables"
}
Response examples (201)
{
  "message": "string",
  "category": {
    "id": 42,
    "name": "string"
  }
}
Response examples (409)
{
  "message": "string",
  "category": {
    "id": 42,
    "name": "string"
  }
}

Obter detalhes de uma categoria

GET /categories/{id}

Retorna os detalhes de uma categoria específica.

Path parameters

  • id integer Required

    ID da categoria

Responses

  • 200 application/json

    Categoria encontrada

    Hide response attributes Show response attributes object
    • id integer
    • name string
    • mostrarLoja boolean
    • mostrarBlog boolean
  • 404 application/json

    Categoria não encontrada

    Hide response attribute Show response attribute object
    • error string
GET /categories/{id}
curl \
 --request GET 'http://localhost:8000/categories/{id}'
Response examples (200)
{
  "id": 42,
  "name": "string",
  "mostrarLoja": true,
  "mostrarBlog": true
}
Response examples (404)
{
  "error": "Categoria não encontrada"
}

Atualizar uma categoria

PUT /categories/{id}

Atualiza os detalhes de uma categoria existente.

Path parameters

  • id integer Required

    ID da categoria

application/json

Body Required

  • name string
  • mostrarLoja boolean
  • mostrarBlog boolean

Responses

  • 200 application/json

    Categoria atualizada com sucesso

    Hide response attribute Show response attribute object
    • message string
  • 404

    Categoria não encontrada

PUT /categories/{id}
curl \
 --request PUT 'http://localhost:8000/categories/{id}' \
 --header "Content-Type: application/json" \
 --data '{"name":"string","mostrarLoja":true,"mostrarBlog":true}'
Request examples
{
  "name": "string",
  "mostrarLoja": true,
  "mostrarBlog": true
}
Response examples (200)
{
  "message": "Categoria atualizada com sucesso!"
}

Excluir uma categoria

DELETE /categories/{id}

Deleta uma categoria do sistema.

Path parameters

  • id integer Required

    ID da categoria

Responses

  • 200 application/json

    Categoria excluída com sucesso

    Hide response attribute Show response attribute object
    • message string
  • 404 application/json

    Categoria não encontrada

    Hide response attribute Show response attribute object
    • message string
DELETE /categories/{id}
curl \
 --request DELETE 'http://localhost:8000/categories/{id}'
Response examples (200)
{
  "message": "Categoria deletada com sucesso!"
}
Response examples (404)
{
  "message": "Categoria não encontrada!"
}

Obter estatísticas do dashboard

GET /categories/dashboard/stats

Retorna as estatísticas gerais do sistema.

Responses

  • 200 application/json

    Estatísticas do dashboard retornadas com sucesso

    Hide response attributes Show response attributes object
    • totalUsers integer
    • totalProductsSold integer
    • totalSales number(float)
    • totalActiveGardens integer
    • totalProducts integer
    • totalQuestionsAnswered integer
GET /categories/dashboard/stats
curl \
 --request GET 'http://localhost:8000/categories/dashboard/stats'
Response examples (200)
{
  "totalUsers": 42,
  "totalProductsSold": 42,
  "totalSales": 42.0,
  "totalActiveGardens": 42,
  "totalProducts": 42,
  "totalQuestionsAnswered": 42
}

Obter produtos vendidos por categoria

GET /categories/products/sold

Retorna a quantidade de produtos vendidos por categoria.

Responses

  • 200 application/json

    Produtos vendidos por categoria retornados com sucesso

    Hide response attributes Show response attributes object
    • category string
    • total_sold integer
GET /categories/products/sold
curl \
 --request GET 'http://localhost:8000/categories/products/sold'
Response examples (200)
[
  {
    "category": "string",
    "total_sold": 42
  }
]

Create checkout session

Cria uma sessão de checkout no Stripe

POST /create-checkout-session

Gera uma sessão de checkout para múltiplos produtos e calcula os impostos com base no país do cliente.

application/json

Body Required

  • amount number(float) Required

    Valor total da compra (incluindo impostos).

  • cartItems array[object] Required

    Lista de itens no carrinho.

    Hide cartItems attributes Show cartItems attributes object
    • name string Required

      Nome do produto.

    • price number(float) Required

      Preço unitário do produto.

    • quantity integer Required

      Quantidade do produto.

  • customerCountry string Required

    Código do país do cliente (ISO 3166-1 alfa-2).

Responses

  • 200 application/json

    Sessão de checkout criada com sucesso

    Hide response attribute Show response attribute object
    • id string

      ID da sessão de checkout criada.

  • 500 application/json

    Erro ao criar a sessão de checkout

    Hide response attribute Show response attribute object
    • error string

      Mensagem de erro detalhada.

POST /create-checkout-session
curl \
 --request POST 'http://localhost:8000/create-checkout-session' \
 --header "Content-Type: application/json" \
 --data '{"amount":120,"cartItems":[{"name":"Produto Exemplo","price":10,"quantity":2}],"customerCountry":"PT"}'
Request examples
{
  "amount": 120,
  "cartItems": [
    {
      "name": "Produto Exemplo",
      "price": 10,
      "quantity": 2
    }
  ],
  "customerCountry": "PT"
}
Response examples (200)
{
  "id": "cs_test_a1b2c3d4e5f6g7h8"
}
Response examples (500)
{
  "error": "Invalid amount."
}

Create order

Cria um novo pedido

POST /create-order

Cria um pedido com os itens do carrinho, o valor total e a quantidade total.

application/json

Body Required

  • user_id integer Required

    ID do utilizador que está fazendo o pedido.

  • cartItems array[object] Required

    Lista de itens no carrinho.

    Hide cartItems attributes Show cartItems attributes object
    • id integer Required

      ID do produto no estoque.

    • quantity integer Required

      Quantidade do produto.

  • totalAmount number(float) Required

    Valor total do pedido (incluindo todos os itens).

  • totalQuantity integer Required

    Quantidade total de itens no pedido.

Responses

  • 201 application/json

    Pedido criado com sucesso

    Hide response attributes Show response attributes object
    • message string

      Mensagem de sucesso.

    • order_id integer

      ID do pedido criado.

  • 400 application/json

    Dados inválidos fornecidos

    Hide response attribute Show response attribute object
    • message string

      Mensagem de erro detalhada.

POST /create-order
curl \
 --request POST 'http://localhost:8000/create-order' \
 --header "Content-Type: application/json" \
 --data '{"user_id":1,"cartItems":[{"id":101,"quantity":2}],"totalAmount":50.75,"totalQuantity":3}'
Request examples
{
  "user_id": 1,
  "cartItems": [
    {
      "id": 101,
      "quantity": 2
    }
  ],
  "totalAmount": 50.75,
  "totalQuantity": 3
}
Response examples (201)
{
  "message": "Order created successfully!",
  "order_id": 123
}
Response examples (400)
{
  "message": "The given data was invalid."
}

Dashboard stats

Obter estatísticas do dashboard

GET /dashboard-stats

Retorna informações sobre o número de utilizadors, vendas totais, produtos vendidos, entre outros.

Responses

  • 200 application/json

    Estatísticas do dashboard retornadas com sucesso

    Hide response attributes Show response attributes object
    • totalUsers integer
    • totalProductsSold integer
    • totalSales number(float)
    • totalActiveGardens integer
    • totalProducts integer
    • totalQuestionsAnswered integer
GET /dashboard-stats
curl \
 --request GET 'http://localhost:8000/dashboard-stats'
Response examples (200)
{
  "totalUsers": 42,
  "totalProductsSold": 42,
  "totalSales": 42.0,
  "totalActiveGardens": 42,
  "totalProducts": 42,
  "totalQuestionsAnswered": 42
}

Dashboardplants

Obtém todas as plantas do dashboard

GET /dashboardplants

Retorna todas as plantas associadas ao painel do utilizador.

Responses

  • 200 application/json

    Plantas do dashboard retornadas com sucesso.

    Hide response attributes Show response attributes object
    • id integer
    • name string
  • 500 application/json

    Erro ao obter plantas do dashboard.

    Hide response attribute Show response attribute object
    • error string
GET /dashboardplants
curl \
 --request GET 'http://localhost:8000/dashboardplants'
Response examples (200)
[
  {
    "id": 42,
    "name": "string"
  }
]
Response examples (500)
{
  "error": "Erro ao obter plantas do dashboard"
}

Delete ticket

Excluir ticket de suporte

DELETE /deleteTicket/{id}

Remove um ticket de suporte do sistema.

Path parameters

  • id integer Required

    ID do ticket a ser excluído

Responses

  • 200 application/json

    Ticket excluído com sucesso

    Hide response attribute Show response attribute object
    • message string
  • 404 application/json

    Ticket não encontrado

    Hide response attribute Show response attribute object
    • message string
DELETE /deleteTicket/{id}
curl \
 --request DELETE 'http://localhost:8000/deleteTicket/{id}'
Response examples (200)
{
  "message": "string"
}
Response examples (404)
{
  "message": "string"
}

Getproduct up

Obtém um produto específico com suas informações

GET /getproductUp/{id}

Retorna os detalhes completos de um produto com base no ID fornecido.

Path parameters

  • id integer Required

    ID do produto a ser recuperado.

Responses

  • 200 application/json

    Produto encontrado

    Hide response attributes Show response attributes object
    • id integer
    • name string
    • price number(float)
    • stock integer
    • threshold integer
    • category object

      Additional properties are allowed.

      Hide category attribute Show category attribute object
      • name string
    • scientific_name string
    • description string
    • size string
    • image string
    • isKit boolean
GET /getproductUp/{id}
curl \
 --request GET 'http://localhost:8000/getproductUp/{id}'
Response examples (200)
{
  "id": 42,
  "name": "string",
  "price": 42.0,
  "stock": 42,
  "threshold": 42,
  "category": {
    "name": "string"
  },
  "scientific_name": "string",
  "description": "string",
  "size": "string",
  "image": "string",
  "isKit": true
}

Identify plant

Identificar planta com base na imagem

POST /identify-plant

Recebe uma imagem e retorna informações sobre a planta identificada.

multipart/form-data

Body Required

  • images array[string(binary)]

    Arquivos de imagem para identificar a planta.

  • latitude number(float)

    Latitude para geolocalização (opcional).

  • longitude number(float)

    Longitude para geolocalização (opcional).

Responses

  • 200 application/json

    Identificação bem-sucedida da planta

    Hide response attributes Show response attributes object
    • plant_id_response object

      Resposta da API Plant.id

      Additional properties are allowed.

    • perenual_response object

      Resposta da API Perenual

      Additional properties are allowed.

  • 400 application/json

    Erro na solicitação (imagem muito grande ou dados inválidos)

    Hide response attributes Show response attributes object
    • error string
    • details string
  • 404 application/json

    Planta não encontrada ou dados incompletos

    Hide response attributes Show response attributes object
    • error string
    • response object

      Additional properties are allowed.

  • 500 application/json

    Erro no servidor

    Hide response attributes Show response attributes object
    • error string
    • details string
POST /identify-plant
curl \
 --request POST 'http://localhost:8000/identify-plant' \
 --header "Content-Type: multipart/form-data" \
 --form "images[]=@file" \
 --form "latitude=42.0" \
 --form "longitude=42.0"
Response examples (200)
{
  "plant_id_response": {},
  "perenual_response": {}
}
Response examples (400)
{
  "error": "string",
  "details": "string"
}
Response examples (404)
{
  "error": "string",
  "response": {}
}
Response examples (500)
{
  "error": "string",
  "details": "string"
}

Kit

Obter detalhes do kit

GET /kit/details/{kitId}

Retorna os detalhes de um kit, incluindo a localização e as plantas associadas.

Path parameters

  • kitId integer Required

    ID do kit cujos detalhes serão obtidos.

Responses

  • 200 application/json

    Detalhes do kit encontrados com sucesso.

    Hide response attributes Show response attributes object
    • nome string

      Nome do kit.

    • localizacao string

      Nome da localização associada ao kit.

    • plants array[object]
      Hide plants attributes Show plants attributes object
      • name string

        Nome da planta.

      • species string

        Espécie da planta.

      • description string

        Descrição da planta.

      • ideal_temperature string

        Temperatura ideal para a planta.

      • ideal_humidity string

        Umidade ideal para a planta.

      • harvest_season string

        Estação de colheita da planta.

      • sunlight string

        Necessidade de luz solar da planta.

      • watering_frequency string

        Frequência de rega necessária para a planta.

  • 404 application/json

    Kit não encontrado.

    Hide response attribute Show response attribute object
    • message string
GET /kit/details/{kitId}
curl \
 --request GET 'http://localhost:8000/kit/details/{kitId}'
Response examples (200)
{
  "nome": "string",
  "localizacao": "string",
  "plants": [
    {
      "name": "string",
      "species": "string",
      "description": "string",
      "ideal_temperature": "string",
      "ideal_humidity": "string",
      "harvest_season": "string",
      "sunlight": "string",
      "watering_frequency": "string"
    }
  ]
}
Response examples (404)
{
  "message": "Kit não encontrado"
}

Obter dados de temperatura do kit

GET /kit/temperature-data

Retorna os dados de temperatura média mensal e as temperaturas ideais das plantas associadas ao kit.

Responses

  • 200 application/json

    Dados de temperatura do kit com sucesso.

    Hide response attributes Show response attributes object
    • averageMonthlyTemperatures object

      Temperatura média mensal calculada a partir das leituras de temperatura.

      Hide averageMonthlyTemperatures attribute Show averageMonthlyTemperatures attribute object
      • * number Additional properties

        Temperatura média do mês.

    • idealTemperatures array[string]

      Temperatura ideal da planta.

    • months array[string]

      Meses do ano com dados de temperatura.

  • 404 application/json

    Kit não encontrado ou sem leituras de temperatura.

    Hide response attribute Show response attribute object
    • message string
GET /kit/temperature-data
curl \
 --request GET 'http://localhost:8000/kit/temperature-data'
Response examples (200)
{
  "averageMonthlyTemperatures": {
    "additionalProperty1": 42.0,
    "additionalProperty2": 42.0
  },
  "idealTemperatures": [
    "string"
  ],
  "months": [
    "string"
  ]
}
Response examples (404)
{
  "message": "Kit não encontrado ou sem leituras de temperatura"
}

Kit readings

Obtém as leituras associadas a um kit

GET /kit-readings/{kitId}

Retorna as leituras de um kit específico pelo seu ID.

Path parameters

  • kitId integer Required

    ID do kit.

Responses

  • 200 application/json

    Leituras obtidas com sucesso.

    Hide response attributes Show response attributes object
    • id integer

      ID da leitura.

    • kits_id integer

      ID do kit associado.

    • value string

      Valor da leitura.

    • created_at string(date-time)

      Data e hora em que a leitura foi registrada.

  • 404 application/json

    Kit não encontrado.

    Hide response attribute Show response attribute object
    • error string
  • 500 application/json

    Erro interno ao Procurarr as leituras.

    Hide response attribute Show response attribute object
    • error string
GET /kit-readings/{kitId}
curl \
 --request GET 'http://localhost:8000/kit-readings/{kitId}'
Response examples (200)
[
  {
    "id": 42,
    "kits_id": 42,
    "value": "string",
    "created_at": "2025-05-04T09:42:00Z"
  }
]
Response examples (404)
{
  "error": "Kit não encontrado para o ID fornecido."
}
Response examples (500)
{
  "error": "Erro ao Procurarr as leituras: [detalhes do erro]"
}

Location

Obtém a localização associada a uma planta

GET /location/{user_plant_id}

Retorna a localização de uma planta específica.

Path parameters

  • user_plant_id integer Required

    ID da planta do utilizador.

Responses

  • 200 application/json

    Localização da planta obtida com sucesso.

    Hide response attribute Show response attribute object
    • location object

      Additional properties are allowed.

      Hide location attributes Show location attributes object
      • id integer
      • name string
      • description string
  • 404 application/json

    Planta não encontrada ou localização não encontrada.

    Hide response attribute Show response attribute object
    • error string
GET /location/{user_plant_id}
curl \
 --request GET 'http://localhost:8000/location/{user_plant_id}'
Response examples (200)
{
  "location": {
    "id": 42,
    "name": "string",
    "description": "string"
  }
}
Response examples (404)
{
  "error": "Associação de planta não encontrada"
}

Locations

Cria uma nova localização

POST /locations

Cria uma nova localização no sistema.

application/json

Body Required

  • name string Required

    Nome da nova localização.

Responses

  • 201 application/json

    Localização criada com sucesso

    Hide response attributes Show response attributes object
    • id integer

      ID da nova localização criada.

    • name string

      Nome da nova localização criada.

  • 400 application/json

    Dados inválidos fornecidos

    Hide response attribute Show response attribute object
    • message string

      Mensagem de erro.

POST /locations
curl \
 --request POST 'http://localhost:8000/locations' \
 --header "Content-Type: application/json" \
 --data '{"name":"Varanda"}'
Request examples
{
  "name": "Varanda"
}
Response examples (201)
{
  "id": 2,
  "name": "Sala"
}
Response examples (400)
{
  "message": "The given data was invalid."
}

Retorna informações sobre uma localização

GET /locations/{id}

Obtém os detalhes de uma localização com base no ID fornecido.

Path parameters

  • id integer Required

    ID da localização.

Responses

  • 200 application/json

    Localização encontrada com sucesso

    Hide response attributes Show response attributes object
    • id integer

      ID da localização.

    • name string

      Nome da localização.

  • 404 application/json

    Localização não encontrada

    Hide response attribute Show response attribute object
    • error string

      Mensagem de erro.

GET /locations/{id}
curl \
 --request GET 'http://localhost:8000/locations/{id}'
Response examples (200)
{
  "id": 1,
  "name": "Varanda"
}
Response examples (404)
{
  "error": "Location not found"
}