Documentação da Dindin API

Introdução à Dindin API

A Dindin API é um sistema de controle de gastos pessoais desenvolvido como resultado do Desafio do Módulo 3 do curso de Desenvolvimento de Software com foco em Backend da Cubos Academy. Seu principal objetivo é proporcionar uma oportunidade prática para que os estudantes possam aplicar as técnicas e conceitos aprendidos em sala de aula. Embora esta API possa parecer simples em sua funcionalidade, ela representa um modelo útil para estudantes que desejam aprofundar seus conhecimentos em desenvolvimento de software, especialmente no contexto de backend.

Aqui, você encontrará informações detalhadas sobre todos os endpoints disponíveis, permitindo que você compreenda e explore como esta API pode ser usada para criar aplicativos de controle financeiro pessoal. Neste guia, iremos abordar os recursos disponíveis e como utilizá-los para melhorar suas habilidades de desenvolvimento de software.

Desenvolvedores:
Mario Frederico Castilho (github)
Mario Silva (github)

Repositório do Projeto:
link

Cadastro de Usuário

Endpoint: POST - https://dindin-api.cyclic.cloud/usuario

Este endpoint é usado para cadastrar um novo usuário no sistema.

Requisição

            
{
    "nome": "João Silva",
    "email": "joao@example.com",
    "senha": "senha123"
}
            
        

Resposta

            
{
    "id": 1,
    "nome": "João Silva",
    "email": "joao@example.com"
}
            
        

Login do Usuário

Endpoint: POST - https://dindin-api.cyclic.cloud/login

Este endpoint permite que um usuário faça login no sistema.

Requisição

            
{
    "email": "joao@example.com",
    "senha": "senha123"
}
            
        

Resposta

            
{
    "usuario": {
        "id": 3,
        "nome": "João Silva",
        "email": "joao@example.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MywiaWF0IjoxNjk0NTQyNzEyLCJleHAiOjE2OTQ2MjkxMTJ9.oOyebU8i04jtI1lm1HPOw6z1unqUe4keogH9pyo3JJQ"
}
            
        

Detalhar Perfil do Usuário Logado

Endpoint: GET - https://dindin-api.cyclic.cloud/usuario

Retorna os dados do perfil do usuário logado.

Requisição:

Método: GET

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Resposta:

Sucesso (HTTP Status 200 / 201 / 204):

json
{
    "id": 1,
    "nome": "José",
    "email": "jose@email.com"
}
        

Falha na Validação (HTTP Status 400 / 401 / 403 / 404):

json
{
    "mensagem": "Para acessar este recurso, um token de autenticação válido deve ser enviado."
}
        

Editar Perfil do Usuário Logado

Endpoint: PUT - https://dindin-api.cyclic.cloud/usuario

Permite que o usuário logado atualize seu próprio perfil.

Requisição:

Método: PUT

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Corpo da Requisição (JSON):

json
{
    "nome": "José de Abreu",
    "email": "jose_abreu@email.com",
    "senha": "j4321"
}
        

Resposta:

Sucesso (HTTP Status 200 / 201 / 204):

json
// Sem conteúdo no corpo (body) da resposta
        

Falha na Validação (HTTP Status 400 / 401 / 403 / 404):

json
{
    "mensagem": "O e-mail informado já está sendo utilizado por outro usuário."
}
        

Listar Categorias

Endpoint: GET - https://dindin-api.cyclic.cloud/categoria

Essa rota permite ao usuário logado listar todas as categorias cadastradas.

Requisição:

Método: GET

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Parâmetros de rota: Nenhum

Parâmetros de consulta: Nenhum

Corpo da requisição: Nenhum

Resposta:

Em caso de sucesso (HTTP Status 200 / 201 / 204), o corpo da resposta conterá um array de objetos representando as categorias cadastradas.

Exemplo de requisição:

json
            Endpoint: GET https://dindin-api.cyclic.cloud/categoria
        

Exemplo de resposta de sucesso:

json
HTTP Status 200 / 201 / 204
[
    {
        "id": 1,
        "descricao": "Roupas"
    },
    {
        "id": 2,
        "descricao": "Mercado"
    }
]
        

Em caso de falha (HTTP Status 400 / 401 / 403 / 404), o corpo da resposta conterá uma mensagem de erro apropriada.

Filtrar Transações por Categoria

Na funcionalidade de listagem de transações do usuário logado (GET /transacao), agora é possível filtrar as transações com base nas categorias informadas.

Requisição:

Método: GET

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Parâmetros de rota: Nenhum

Parâmetros de consulta:

filtro (array de strings, opcional): Um array contendo a descrição de uma ou mais categorias pelas quais as transações devem ser filtradas.

Exemplo de requisição:

json
GET https://dindin-api.cyclic.cloud/transacao?filtro[]=roupas&filtro[]=salarios
        

Resposta:

Em caso de sucesso (HTTP Status 200 / 201 / 204), o corpo da resposta conterá um array de objetos representando as transações que atendem aos critérios de filtro.

Exemplo de resposta de sucesso:

json
HTTP Status 200 / 201 / 204
[
    {
        "id": 1,
        "tipo": "saida",
        "descricao": "Sapato amarelo",
        "valor": 15800,
        "data": "2022-03-23T15:35:00.000Z",
        "usuario_id": 5,
        "categoria_id": 4,
        "categoria_nome": "Roupas"
    },
    {
        "id": 3,
        "tipo": "entrada",
        "descricao": "Salário",
        "valor": 300000,
        "data": "2022-03-24T15:30:00.000Z",
        "usuario_id": 5,
        "categoria_id": 6,
        "categoria_nome": "Salários"
    }
]
        

Em caso de falha, o corpo da resposta conterá a seguinte mensagem: "Categoria não encontrada".

Listar Transações do Usuário Logado

Endpoint: GET - https://dindin-api.cyclic.cloud/transacao

Lista todas as transações associadas ao usuário logado.

Requisição:

Método: GET

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Resposta:

Sucesso (HTTP Status 200 / 201 / 204):

json
[
    {
        "id": 1,
        "tipo": "saida",
        "descricao": "Sapato amarelo",
        "valor": 15800,
        "data": "2022-03-23T15:35:00.000Z",
        "usuario_id": 5,
        "categoria_id": 4,
        "categoria_nome": "Roupas"
    },
    {
        "id": 3,
        "tipo": "entrada",
        "descricao": "Salário",
        "valor": 350000,
        "data": "2022-03-01T08:15:00.000Z",
        "usuario_id": 5,
        "categoria_id": 1,
        "categoria_nome": "Salário"
    }
]
        

Falha na Validação (HTTP Status 400 / 401 / 403 / 404):

json
{
    "mensagem": "Para acessar este recurso, um token de autenticação válido deve ser enviado."
}
        

Registrar Nova Transação

Endpoint: POST - https://dindin-api.cyclic.cloud/transacao

Permite que o usuário logado registre uma nova transação.

Requisição:

Método: POST

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Corpo da Requisição (JSON):

json
{
    "tipo": "saida",
    "descricao": "Compras no mercado",
    "valor": 25000,
    "data": "2022-03-10",
    "categoria_id": 2
}
        

Resposta:

Sucesso (HTTP Status 200 / 201 / 204):

json
{
    "id": 4,
    "tipo": "saida",
    "descricao": "Compras no mercado",
    "valor": 25000,
    "data": "2022-03-10T00:00:00.000Z",
    "usuario_id": 5,
    "categoria_id": 2,
    "categoria_nome": "Mercado"
}
        

Falha na Validação (HTTP Status 400 / 401 / 403 / 404):

json
{
    "mensagem": "Erro de validação: O campo 'data' é obrigatório."
}
        

Detalhar uma Transação do Usuário Logado

Endpoint: GET https://dindin-api.cyclic.cloud/transacao/:id

Essa rota permite ao usuário logado obter detalhes de uma transação específica associada a eles.

Requisição:

Método: GET

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Parâmetros de rota:

id (integer): O ID da transação que se deseja detalhar.

Corpo da requisição: Nenhum

Resposta:

Em caso de sucesso (HTTP Status 200 / 201 / 204), o corpo da resposta conterá um objeto representando os detalhes da transação.

Exemplo de requisição:

json
            Endpoint: GET https://dindin-api.cyclic.cloud/transacao/2
        

Exemplo de resposta de sucesso:

json
HTTP Status 200 / 201 / 204
{
    "id": 2,
    "tipo": "saida",
    "descricao": "Compra de roupas",
    "valor": 100.0,
    "data": "2023-09-10",
    "categoria_id": 1,
    "categoria_nome": "Vestuário"
}
        

Cadastrar Transação para o Usuário Logado

Endpoint: POST https://dindin-api.cyclic.cloud/transacao

Essa rota permite ao usuário logado cadastrar uma nova transação associada a eles.

Requisição:

Método: POST

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Parâmetros de rota: Nenhum

Parâmetros de consulta: Nenhum

Corpo da requisição:

json
{
    "tipo": "entrada",
    "descricao": "Salário",
    "valor": 3000.0,
    "data": "2023-09-15",
    "categoria_id": 2
}
        

Resposta:

Em caso de sucesso (HTTP Status 200 / 201 / 204), o corpo da resposta conterá um objeto representando os detalhes da transação recém-cadastrada, incluindo o seu ID.

Exemplo de requisição:

json
            Endpoint: POST https://dindin-api.cyclic.cloud/transacao
{
    "tipo": "entrada",
    "descricao": "Salário",
    "valor": 3000.0,
    "data": "2023-09-15",
    "categoria_id": 2
}
        

Exemplo de resposta de sucesso:

json
HTTP Status 200 / 201 / 204
{
    "id": 5,
    "tipo": "entrada",
    "descricao": "Salário",
    "valor": 3000.0,
    "data": "2023-09-15",
    "categoria_id": 2,
    "categoria_nome": "Salários"
}
        

Atualizar Transação do Usuário Logado

Endpoint: PUT - https://dindin-api.cyclic.cloud/transacao/:id

Essa rota permite ao usuário logado atualizar uma transação existente associada a eles.

Requisição:

Método: PUT

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Parâmetros de rota:

id (integer): O ID da transação que se deseja atualizar.

Corpo da requisição:

json
{
    "tipo": "saida",
    "descricao": "Compra de eletrônicos",
    "valor": 500.0,
    "data": "2023-09-20",
    "categoria_id": 3
}
        

Resposta:

Em caso de sucesso (HTTP Status 200 / 201 / 204), o corpo da resposta conterá um objeto representando os detalhes da transação atualizada.

Exemplo de requisição:

json
            Endpoint: PUT https://dindin-api.cyclic.cloud/transacao/5
{
    "tipo": "saida",
    "descricao": "Compra de eletrônicos",
    "valor": 500.0,
    "data": "2023-09-20",
    "categoria_id": 3
}
        

Exemplo de resposta de sucesso:

json
HTTP Status 200 / 201 / 204
{
    "id": 5,
    "tipo": "saida",
    "descricao": "Compra de eletrônicos",
    "valor": 500.0,
    "data": "2023-09-20",
    "categoria_id": 3,
    "categoria_nome": "Eletrônicos"
}
        

Excluir Transação do Usuário Logado

Endpoint: DELETE - https://dindin-api.cyclic.cloud/transacao/:id

Essa rota permite ao usuário logado excluir uma transação existente associada a eles.

Requisição:

Método: DELETE

Atenção: É obrigatório o envio do token de autenticação via header (Bearer Token) da requisição

Parâmetros de rota:

id (integer): O ID da transação que se deseja excluir.

Corpo da requisição: Nenhum

Resposta:

Em caso de sucesso (HTTP Status 200 / 201 / 204), o corpo da resposta será vazio.

Exemplo de requisição:

json
            Endpoint: DELETE https://dindin-api.cyclic.cloud/transacao/5
        

Exemplo de resposta de sucesso:

json
HTTP Status 200 / 201 / 204
{}