Transações - Manual do usuário

Introdução

Na API do Procfy as transações são representadas por um objeto JSON com os seguintes atributos:

Atributos com o valor null serão retornados na resposta.

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

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.

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.

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.

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.

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

Exemplo de requisição para visualizar várias transações

GET /api/v1/transactions

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

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

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.

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

POST /api/v1/transactions

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

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

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

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.

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

PUT /api/v1/transactions/:id

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

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

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

As frequências são utilizadas para transações recorrentes.

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)

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

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

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

{
  "error": "Enum inválido",
  "description": "Tipo de pagamento inválido"
}

​Introdução

​Rotas

​Visualizar várias transações

​Parâmetros aceitos

​Visualizando uma transação específica

​Criar uma transação

​Editar uma transação

​Excluir uma transação

​Visualizando várias transações

​Criando uma transação

​Editando uma transação

​Enums

​Transaction Type

​Payment Type

​Payment Method

​Frequencies

​Erros

​Erros de validação

​Erros de enum

Introdução

Rotas

Visualizar várias transações

Parâmetros aceitos

Visualizando uma transação específica

Criar uma transação

Editar uma transação

Excluir uma transação

Visualizando várias transações

Criando uma transação

Editando uma transação

Enums

Transaction Type

Payment Type

Payment Method

Frequencies

Erros

Erros de validação

Erros de enum