Contas a Pagar e a Receber

Este endpoint gerencia as transações financeiras de contas a pagar e a receber, que não se originam diretamente de uma nota fiscal de compra ou venda (ex: salários, aluguel, etc.).

Objeto Transação Financeira

Atributo	Tipo	Descrição
id	string	O ID único da transação (UUID).
description	string	A descrição da transação (ex: "Aluguel do escritório").
amount	number	O valor da transação.
due_date	string	A data de vencimento no formato YYYY-MM-DD.
is_paid	boolean	Para contas a pagar, indica se a conta foi paga.
paid_date	string	A data em que a conta foi paga. null se não foi paga.
is_received	boolean	Para contas a receber, indica se o valor foi recebido.
received_date	string	A data em que o valor foi recebido. null se não foi recebido.
organization_id	string	O ID da organização à qual a transação pertence.
accounting_period_id	string	O ID do período contábil ao qual a transação pertence.

---

Listar Transações

Retorna uma lista de contas a pagar ou a receber.

GET/api/financial-transactions

Parâmetros de Query

Parâmetro	Tipo	Descrição
type	string	Obrigatório. O tipo de transação a ser listada. Valores possíveis: payable (a pagar), receivable (a receber).
is_paid	boolean	Opcional. Filtra transações pagas/recebidas (true) ou não pagas/recebidas (false).
startDate	string	Opcional. Data de início para filtrar transações (YYYY-MM-DD).
endDate	string	Opcional. Data de fim para filtrar transações (YYYY-MM-DD).

Resposta

Retorna um array de objetos de Transação Financeira.

Códigos de Status HTTP

• 200 OK: Transações listadas com sucesso.
• 400 Bad Request: Parâmetro type ausente ou inválido.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao listar as transações.

---

Criar uma Transação

Cria uma nova conta a pagar ou a receber.

POST/api/financial-transactions

Parâmetros de Query

Parâmetro	Tipo	Descrição
type	string	Obrigatório. O tipo de transação a ser criada. Valores possíveis: payable, receivable.

Corpo da Requisição

{
  "description": "Pagamento de fornecedor de serviço",
  "amount": 500.00,
  "due_date": "2025-08-15"
}

Resposta

Retorna o objeto da transação recém-criada.

Códigos de Status HTTP

• 201 Created: Transação criada com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: description, amount ou due_date ausente/inválido).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao criar a transação.

---

Atualizar uma Transação

Atualiza os detalhes de uma transação existente.

PUT/api/financial-transactions/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID da transação a ser atualizada.

Corpo da Requisição

{
  "is_paid": true,
  "paid_date": "2025-08-10"
}

Resposta

Retorna o objeto da transação atualizada.

Códigos de Status HTTP

• 200 OK: Transação atualizada com sucesso.
• 400 Bad Request: Dados da requisição inválidos.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 404 Not Found: Transação não encontrada.
• 500 Internal Server Error: Erro interno do servidor ao atualizar a transação.

---

Deletar uma Transação

Exclui uma transação financeira.

DELETE/api/financial-transactions/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID da transação a ser deletada.

Resposta

204 No Content em caso de sucesso.

Códigos de Status HTTP

• 204 No Content: Transação deletada com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 404 Not Found: Transação não encontrada.
• 500 Internal Server Error: Erro interno do servidor ao deletar a transação.