> ## Documentation Index
> Fetch the complete documentation index at: https://docs.procfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Categorias

## **Introdução**

Na API do Procfy as categorias são representados por um objeto JSON com os seguintes atributos:

<Info>
  Atributos com o valor `null` serão retornados na resposta.
</Info>

| Atributo          | Tipo    | Descrição                        |
| :---------------- | :------ | :------------------------------- |
| id                | integer | Identificador único da categoria |
| name              | string  | Nome da categoria                |
| description       | text    | Descrição da categoria           |
| transaction\_type | string  | Tipo de transação da categoria   |

***

## **Rotas**

| Método | Endpoint               | Descrição                           |
| :----- | :--------------------- | :---------------------------------- |
| GET    | /api/v1/categories     | Visualizar várias categorias        |
| GET    | /api/v1/categories/:id | Visualizar uma categoria específica |
| POST   | /api/v1/categories     | Criar uma categoria                 |
| PUT    | /api/v1/categories/:id | Editar uma categoria                |
| DELETE | /api/v1/categories/:id | Excluir uma categoria               |

#### **Visualizar várias categorias**

O Procfy utiliza o padrão de paginação para retornar os resultados das requisições. Para mais informações sobre paginação, consulte a seção [**paginação**](/paginacao#introducao).

Para visualizar várias categorias, você deve fazer uma requisição para a API utilizando o método `GET` no endpoint correspondente ao objeto que deseja visualizar.

```text theme={null}
GET /api/v1/categories
```

#### **Parâmetros aceitos**

| Parâmetro | Tipo    | Descrição                      |
| :-------- | :------ | :----------------------------- |
| page      | integer | Número da página               |
| items     | integer | Quantidade de itens por página |

#### **Visualizar uma categoria específica**

Para visualizar uma categoria específica, você deve fazer uma requisição para a API utilizando o método `GET` no endpoint correspondente ao objeto que deseja visualizar.

```text theme={null}
GET /api/v1/categories/:id
```

#### **Criar uma categoria**

Para criar um objeto, você deve fazer uma requisição para a API utilizando o método `POST` no endpoint correspondente ao objeto que deseja criar.

```text theme={null}
POST /api/v1/categories
```

#### **Editar uma categoria**

Para editar um objeto, você deve fazer uma requisição para a API utilizando o método `PUT` no endpoint correspondente ao objeto que deseja editar.

```text theme={null}
PUT /api/v1/categories/:id
```

#### **Excluir uma categoria**

Para excluir um objeto, você deve fazer uma requisição para a API utilizando o método `DELETE` no endpoint correspondente ao objeto que deseja excluir.

```text theme={null}
DELETE /api/v1/categories/:id
```

***

## **Visualizando várias categorias**

A API utiliza o padrão de paginação para retornar os resultados das requisições. Para mais informações sobre paginação, consulte a seção [**paginação**](/paginacao#introducao).

> Exemplo de requisição para visualizar várias categorias

```text theme={null}
GET /api/v1/categories
```

> Exemplo de resposta para visualizar várias categorias

```json theme={null}
{
  "page": {
    "page": 1,
    "items": 50,
    "pages": 1,
    "last": 1,
    "next": null,
    "prev": null,
    "count": 1,
    "from": 1,
    "to": 1
  },
  "data": [
    {
      "id": 57,
      "name": "Nome de empresa",
      "description": "Descrição"
    }
  ]
}
```

***

## **Criando uma categoria**

Para criar um objeto, você deve fazer uma requisição para a API utilizando o método `POST` no endpoint correspondente ao objeto que deseja criar.

A API vai retornar o objeto criado, caso não ocorra nenhum erro.

O corpo da requisição deve conter um objeto com os atributos necessários para a criação do objeto.

Os atributos são:

| Atributo          | Tipo   | Obrigatório | Descrição                      |
| :---------------- | :----- | :---------- | :----------------------------- |
| name              | string | sim         | Nome da categoria              |
| description       | text   | não         | Descrição da categoria         |
| transaction\_type | string | sim         | Tipo de transação da categoria |

Veja a lista de atributos necessários para a criação do objeto na [tabela de atributos](/categorias#introdução).

> Exemplo de requisição para criar uma categoria

```text theme={null}
POST /api/v1/categories
```

> Exemplo de corpo da requisição para criar uma categoria

```json theme={null}
{
  "name": "Nome",
  "description": "Descrição",
  "transaction_type": "revenue"
}
```

> Exemplo de resposta para criar uma categoria

```json theme={null}
{
  "id": 57,
  "name": "Nome",
  "description": "Descrição",
  "transaction_type": "revenue"
}
```

***

## **Editando uma categoria**

Para editar um objeto, você deve fazer uma requisição para a API utilizando o método `PUT` no endpoint correspondente ao objeto que deseja editar.

A API vai retornar o objeto editado, caso não ocorra nenhum erro.

O corpo da requisição deve conter um objeto com os atributos necessários para a edição do objeto.

Veja a lista de atributos necessários para a edição do objeto na [tabela de atributos](/categorias#introdução).

> Exemplo de requisição para editar uma categoria

```text theme={null}
PUT /api/v1/categories/:id
```

> Exemplo de corpo da requisição para editar uma categoria

```json theme={null}
{
  "name": "Nome",
  "description": "Descrição alterada",
  "transaction_type": "revenue"
}
```

> Exemplo de resposta para editar uma categoria

```json theme={null}
{
  "id": 57,
  "name": "Nome",
  "description": "Descrição alterada",
  "transaction_type": "revenue"
}
```

***

## **Erros**

Erros que podem ocorrer durante a execução de uma categoria.

Os erros de validação retornam um objeto com a chave `error` e `description` com a mensagem de erro. A mensagem de erro pode variar de acordo com o erro ocorrido.

#### **Erros de validação**

Os erros de validação são retornados quando os atributos obrigatórios não são informados ou quando os atributos informados não estão de acordo com as regras de validação.

> Exemplo de resposta para erro de validação na criação ou edição de uma categoria (Objeto em branco)

```json theme={null}
{
  "error": "Registro inválido",
  "description": "A validação falhou: Nome não pode ficar em branco"
}
```

> Exemplo de resposta para erro de enum na criação ou edição de uma categoria (transaction\_type)

```json theme={null}
{
  "error": "Enum inválido",
  "description": "Tipo de transação inválido"
}
```