> ## 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.

# Transações

## **Introdução**

Na API do Procfy as transações são representadas 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 transação                                  |
| name                        | string  | Descrição da transação                                            |
| description                 | text    | Observações da transação                                          |
| due\_date                   | date    | Data de vencimento da transação                                   |
| paid                        | boolean | Indica se a transação foi paga                                    |
| paid\_at                    | date    | Data de pagamento da transação                                    |
| competency\_date            | date    | Data de competência da transação                                  |
| document\_number            | string  | Número do documento da transação                                  |
| installment\_number         | integer | Número da parcela da transação                                    |
| installment\_total          | integer | Total de parcelas da transação                                    |
| amount\_cents               | integer | Valor da transação em centavos                                    |
| amount\_currency            | string  | Moeda da transação                                                |
| exchanged\_amount\_cents    | integer | Valor da transação em centavos convertido para a moeda da conta   |
| exchanged\_amount\_currency | string  | Moeda da transação convertida para a moeda da conta               |
| created\_at                 | string  | Data de criação da transação                                      |
| bank\_account               | object  | Objeto com os dados da conta bancária da transação                |
| transaction\_type           | string  | Tipo da transação                                                 |
| payment\_method             | string  | Método de pagamento da transação                                  |
| payment\_type               | string  | Tipo de pagamento da transação                                    |
| transfer\_to\_id            | integer | Identificador único da conta bancária de destino da transferência |

Alguns atributos quando não informados, são preenchidos automaticamente com valores padrão:

| Atributo          | Valor padrão        |
| :---------------- | :------------------ |
| paid              | false               |
| transaction\_type | revenue             |
| payment\_type     | on\_cash            |
| payment\_method   | no\_payment\_method |
| amount\_cents     | 0                   |
| amount\_currency  | BRL                 |

***

## **Rotas**

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

#### **Visualizar várias transações**

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 transações, 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/transactions
```

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

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

#### **Visualizando uma transação específica**

Para visualizar uma transação 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/transactions/:id
```

#### **Criar uma transação**

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/transactions
```

#### **Editar uma transação**

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/transactions/:id
```

#### **Excluir uma transação**

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/transactions/:id
```

***

## **Visualizando várias transações**

A API disponibiliza algumas opções de filtro para a listagem de transações. Os parâmetros aceitos são:

| Parâmetro          | Tipo    | Descrição                                         |
| :----------------- | :------ | :------------------------------------------------ |
| page               | integer | Número da página                                  |
| items              | integer | Quantidade de itens por página                    |
| start\_date        | date    | Data de início do período de busca das transações |
| end\_date          | date    | Data de fim do período de busca das transações    |
| bank\_account\_ids | array   | IDs das contas bancárias                          |
| category\_ids      | array   | IDs das categorias                                |
| contact\_ids       | array   | IDs dos contatos                                  |
| cost\_center\_ids  | array   | IDs dos centros de custo                          |

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 transações

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

> Exemplo de resposta para visualizar várias transações

```json theme={null}
{
  "page": {
    "page": 1,
    "items": 25,
    "pages": 2,
    "last": 2,
    "next": 2,
    "prev": null,
    "count": 50,
    "from": 1,
    "to": 25
  },
  "data": [
    {
      "id": 1,
      "name": "Pagamento de aluguel",
      "amount_cents": 100000,
      "amount_currency": "BRL",
      "transaction_type": "fixed_expense",
      "payment_method": "bank_slip",
      "payment_type": "on_cash",
      "due_date": "2019-01-01",
      "paid": true,
      "bank_account": {
        "id": 1,
        "name": "Conta Corrente",
        "default": true,
        "balance_cents": 0,
        "balance_currency": "BRL",
        "agency": null
      }
    },
    {
      "id": 2,
      "description": "Recebimento de aluguel",
      "amount_cents": 100000,
      "amount_currency": "BRL",
      "transaction_type": "revenue",
      "payment_method": "bank_slip",
      "payment_type": "on_cash",
      "due_date": "2019-01-01",
      "paid": true,
      "bank_account": {
        "id": 1,
        "name": "Conta Corrente",
        "default": true,
        "balance_cents": 0,
        "balance_currency": "BRL",
        "agency": null
      }
    }
  ]
}
```

***

## **Criando uma transação**

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.

<Info>
  No momento, a API suporta apenas a **visualização** de transações recorrentes e/ou parceladas, não sendo possível criá-las, editá-las ou excluí-las.
</Info>

Os atributos são:

| Atributo                    | Tipo    | Obrigatório | Descrição                                 |
| :-------------------------- | :------ | :---------- | :---------------------------------------- |
| name                        | string  | não         | Descrição da transação                    |
| bank\_account\_id           | integer | sim         | ID da conta bancária                      |
| due\_date                   | date    | sim         | Data de vencimento da transação           |
| paid                        | boolean | não         | Indica se a transação foi paga            |
| paid\_at                    | date    | não         | Data de pagamento da transação            |
| competency\_date            | date    | não         | Data de competência da transação          |
| document\_number            | string  | não         | Número do documento da transação          |
| installment\_number         | integer | não         | Número da parcela                         |
| installment\_total          | integer | não         | Total de parcelas                         |
| amount\_cents               | integer | sim         | Valor da transação em centavos            |
| amount\_currency            | string  | sim         | Moeda da transação                        |
| description                 | text    | não         | Observações da transação                  |
| exchanged\_amount\_cents    | integer | não         | Valor da transação convertido em centavos |
| exchanged\_amount\_currency | string  | não         | Moeda da transação convertida             |
| transaction\_type           | string  | sim         | Tipo da transação                         |
| payment\_method             | string  | sim         | Método de pagamento da transação          |
| payment\_type               | string  | sim         | Tipo de pagamento da transação            |

> Exemplo de requisição para criar uma transação

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

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

```json theme={null}
{
  "name": "Pagamento de aluguel",
  "amount_cents": 100000,
  "amount_currency": "BRL",
  "transaction_type": "fixed_expense",
  "payment_method": "bank_slip",
  "payment_type": "on_cash",
  "bank_account_id": 1,
  "due_date": "2019-01-01",
  "paid": true
}
```

> Exemplo de resposta para criar uma transação

```json theme={null}
{
  "id": 1,
  "name": "Pagamento de aluguel",
  "amount_cents": 100000,
  "amount_currency": "BRL",
  "transaction_type": "fixed_expense",
  "payment_method": "bank_slip",
  "payment_type": "on_cash",
  "due_date": "2019-01-01",
  "paid": true,
  "bank_account": {
    "id": 1,
    "name": "Conta Corrente",
    "default": true,
    "balance_cents": 0,
    "balance_currency": "BRL",
    "agency": null
  }
}
```

***

## **Editando uma transação**

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](/transacoes#introdução).

<Info>
  No momento, a API suporta apenas a **visualização** de transações recorrentes e/ou parceladas, não sendo possível criá-las, editá-las ou excluí-las.
</Info>

> Exemplo de requisição para editar uma transação

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

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

```json theme={null}
{
  "name": "Pagamento de aluguel",
  "amount_cents": 100000,
  "amount_currency": "BRL",
  "transaction_type": "fixed_expense",
  "payment_method": "bank_slip",
  "payment_type": "on_cash",
  "contact_id": 1,
  "category_id": 1,
  "bank_account_id": 1,
  "due_date": "2019-01-01",
  "paid": false
}
```

> Exemplo de resposta para editar uma transação

```json theme={null}
{
  "id": 1,
  "name": "Pagamento de aluguel",
  "amount_cents": 100000,
  "amount_currency": "BRL",
  "transaction_type": "fixed_expense",
  "payment_method": "bank_slip",
  "payment_type": "on_cash",
  "due_date": "2019-01-01",
  "paid": false,
  "bank_account": {
    "id": 1,
    "name": "Conta Corrente",
    "default": true,
    "balance_cents": 0,
    "balance_currency": "BRL",
    "agency": null
  }
}
```

***

## **Enums**

Os enums são utilizados para definir os valores permitidos para os atributos de um objeto. A sua utilização é importante para garantir a integridade dos dados.

#### **Transaction Type**

O atributo `transaction_type` é utilizado para definir o tipo da transação.

| Valor             | Descrição          |
| :---------------- | :----------------- |
| revenue           | Receita            |
| fixed\_expense    | Despesa Fixa       |
| variable\_expense | Despesa Variável   |
| payroll           | Folha de Pagamento |
| tax               | Imposto            |
| transfer          | Transferência      |

#### **Payment Type**

O atributo `payment_type` é utilizado para definir o tipo de pagamento.

| Valor       | Descrição  |
| :---------- | :--------- |
| on\_cash    | À Vista    |
| installment | Parcelado  |
| recurring   | Recorrente |

#### **Payment Method**

O atributo `payment_method` é utilizado para definir o método de pagamento.

| Valor               | Descrição              |
| :------------------ | :--------------------- |
| no\_payment\_method | Indefinido             |
| credit\_card        | Cartão de Crédito      |
| debit\_card         | Cartão de Débito       |
| bank\_slip          | Boleto Bancário        |
| check               | Cheque                 |
| cash                | Dinheiro               |
| pix                 | Pix                    |
| bank\_transfer      | Transferência Bancária |
| direct\_debit       | Débito Direto          |
| promissory          | Promissória            |

#### **Frequencies**

O atributo `frequency` é utilizado para definir a frequência de uma transação recorrente.

<Danger>
  As frequências são utilizadas para transações recorrentes.
</Danger>

| Valor      | Descrição  |
| :--------- | :--------- |
| daily      | Diário     |
| weekly     | Semanal    |
| biweekly   | Quinzenal  |
| monthly    | Mensal     |
| bimonthly  | Bimestral  |
| quarterly  | Trimestral |
| semiannual | Semestral  |
| annual     | Anual      |

***

## **Erros**

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

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 transação (Objeto em branco)

```json theme={null}
{
  "error": "Registro inválido",
  "description": "A validação falhou: Data não pode ficar em branco, Bank account não pode ficar em branco, Bank account é obrigatório(a)"
}
```

#### **Erros de enum**

Os erros de enum são retornados quando os atributos informados não estão de acordo com os valores permitidos.

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

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

> Exemplo de resposta para erro de enum na criação ou edição de uma transação (payment\_method)

```json theme={null}
{
  "error": "Enum inválido",
  "description": "Método de pagamento inválido"
}
```

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

```json theme={null}
{
  "error": "Enum inválido",
  "description": "Tipo de pagamento inválido"
}
```