Períodos Contábeis

Este endpoint gerencia os períodos contábeis (exercícios fiscais) dentro de uma organização. Cada período tem uma data de início e fim, e todos os lançamentos contábeis estão vinculados a um período específico.

Objeto Período Contábil

Atributo	Tipo	Descrição
id	string	O ID único do período contábil (UUID).
name	string	O nome do período (ex: "Exercício 2025").
start_date	string	A data de início do período no formato YYYY-MM-DD.
end_date	string	A data de fim do período no formato YYYY-MM-DD.
organization_id	string	O ID da organização à qual o período pertence.
regime	string	O regime tributário associado a este período (simples_nacional, lucro_presumido, lucro_real).
costing_method	string	O método de custeio padrão para este período (weighted_average, fifo, lifo).

---

Listar Períodos Contábeis

Retorna uma lista de todos os períodos contábeis para a organização ativa do usuário.

GET/api/accounting-periods

Resposta

Retorna um array de objetos de Período Contábil, ordenados pela data de início (mais recentes primeiro).

Códigos de Status HTTP

• 200 OK: Períodos contábeis listados com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao listar os períodos contábeis.

---

Criar um Período Contábil

Cria um novo período contábil para a organização ativa. A API valida para garantir que não haja sobreposição de datas com períodos existentes.

POST/api/accounting-periods

Corpo da Requisição

{
  "name": "Exercício 2026",
  "start_date": "2026-01-01",
  "end_date": "2026-12-31",
  "regime": "lucro_presumido",
  "costing_method": "weighted_average"
}

Resposta

Retorna um objeto contendo o período contábil e o registro de histórico do regime tributário criados.

Códigos de Status HTTP

• 201 Created: Período contábil criado com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: datas sobrepostas, nome ou regime ausente/inválido).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao criar o período contábil.

---

Atualizar um Período Contábil

Atualiza os detalhes de um período contábil existente.

PUT/api/accounting-periods/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID do período a ser atualizado.

Corpo da Requisição

{
  "name": "Exercício Fiscal 2026",
  "costing_method": "fifo"
}

Resposta

Retorna o objeto do período contábil atualizado.

Códigos de Status HTTP

• 200 OK: Período contábil atualizado com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: datas sobrepostas).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 404 Not Found: Período contábil não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao atualizar o período contábil.

---

Deletar um Período Contábil

Exclui um período contábil. Esta ação também removerá o registro de regime tributário associado.

DELETE/api/accounting-periods/{id}

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	string	O ID do período a ser deletado.

Resposta

204 No Content em caso de sucesso.

Códigos de Status HTTP

• 204 No Content: Período contábil deletado com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 403 Forbidden: O período não pode ser deletado (ex: possui lançamentos associados).
• 404 Not Found: Período contábil não encontrado.
• 500 Internal Server Error: Erro interno do servidor ao deletar o período contábil.