Lançamentos Contábeis

Este endpoint gerencia os cabeçalhos dos lançamentos contábeis (partidas dobradas). Cada lançamento de diário é um registro que contém uma data, uma descrição e está associado a múltiplas linhas de lançamento (débitos e créditos), que devem ser criadas usando o endpoint de Linhas de Lançamento.

Objeto Lançamento Contábil

Atributo	Tipo	Descrição
id	string	O ID único do lançamento (UUID).
entry_date	string	A data do lançamento no formato YYYY-MM-DD.
description	string	Uma descrição para o lançamento (ex: "Venda de mercadorias").
organization_id	string	O ID da organização à qual o lançamento pertence.
accounting_period_id	string	O ID do período contábil ao qual o lançamento pertence.
status	string	O status atual do lançamento (draft, posted, reviewed).
reference	string	A referência única do lançamento (gerada automaticamente ou definida).
created_by_user_id	string	O ID do usuário que criou o lançamento.
created_by_username	string	O nome de usuário de quem criou o lançamento.
created_by_email	string	O e-mail de quem criou o lançamento.
updated_at	string	Timestamp da última atualização do lançamento.

---

Listar Lançamentos

Retorna uma lista paginada de todos os lançamentos contábeis para a organização e período contábil ativos.

GET/api/journal-entries

Parâmetros de Query

Parâmetro	Tipo	Descrição
page	integer	Opcional. O número da página a ser retornada (padrão: 1).
limit	integer	Opcional. O número máximo de itens por página (padrão: 10).
status	string	Opcional. Filtra lançamentos por status (draft, posted, reviewed).
startDate	string	Opcional. Data de início para filtrar lançamentos (YYYY-MM-DD).
endDate	string	Opcional. Data de fim para filtrar lançamentos (YYYY-MM-DD).
creatorId	string	Opcional. Filtra lançamentos pelo ID do criador.
hasProductMovement	boolean	Opcional. Filtra lançamentos com movimentação de produto.
hasCalculatedTaxes	boolean	Opcional. Filtra lançamentos com impostos calculados.
accountId	string	Opcional. Filtra lançamentos que afetam uma conta específica.

Resposta

{
  "data": [
    {
      "id": "f1g2h3i4-j5k6-7890-1234-567890abcdef",
      "entry_date": "2025-07-24",
      "description": "Pagamento de salários",
      "status": "posted",
      "reference": "SAL001",
      "created_by_username": "João Silva",
      "updated_at": "2025-07-24T10:30:00Z"
    }
  ],
  "count": 1
}

Códigos de Status HTTP

• 200 OK: Lançamentos listados com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao listar os lançamentos.

---

Criar um Lançamento

Cria o cabeçalho de um novo lançamento contábil. As linhas de débito e crédito devem ser adicionadas separadamente.

POST/api/journal-entries

Corpo da Requisição

{
  "entry_date": "2025-07-25",
  "description": "Compra de matéria-prima",
  "status": "draft",
  "reference_prefix": "COMP" // Opcional, para geração automática de referência
}

Resposta

Retorna o objeto do lançamento recém-criado.

Códigos de Status HTTP

• 201 Created: Lançamento criado com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: entry_date ou description ausente/inválido).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao criar o lançamento.

---

Atualizar um Lançamento

Atualiza a data, a descrição ou o status de um lançamento existente.

PUT/api/journal-entries/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID do lançamento a ser atualizado.

Corpo da Requisição

{
  "description": "Compra de matéria-prima a prazo",
  "status": "posted"
}

Resposta

Retorna o objeto do lançamento atualizado.

Códigos de Status HTTP

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

---

Deletar um Lançamento

Exclui um lançamento contábil e todas as suas linhas de lançamento associadas.

DELETE/api/journal-entries/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID do lançamento a ser deletado.

Resposta

204 No Content em caso de sucesso.

Códigos de Status HTTP

• 204 No Content: Lançamento deletado com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 403 Forbidden: O lançamento não pode ser deletado (ex: status posted ou reviewed).
• 404 Not Found: Lançamento não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao deletar o lançamento.