Contas (Plano de Contas)

O endpoint de Contas é usado para gerenciar o plano de contas de uma organização. Ele permite criar, listar, atualizar e deletar contas contábeis.

Objeto Conta

Atributo	Tipo	Descrição
id	string	O ID único da conta (UUID).
name	string	O nome da conta (ex: "Caixa", "Receita de Vendas").
type	string	O tipo da conta (ex: Asset, Liability, Equity, Revenue, Expense).
code	string	O código contábil da conta (ex: "1.1.01.001").
parent_account_id	string	O ID da conta pai, para contas aninhadas. null para contas de nível superior.
organization_id	string	O ID da organização à qual a conta pertence.
accounting_period_id	string	O ID do período contábil ao qual a conta pertence.

---

Listar Contas

Retorna uma lista paginada de todas as contas para a organização e período contábil ativos.

GET/api/accounts

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

Resposta

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "Caixa",
      "type": "Asset",
      "code": "1.1.01.001",
      "parent_account_id": null
    }
  ],
  "count": 1
}

Códigos de Status HTTP

• 200 OK: Contas listadas com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao listar as contas.

---

Criar uma Conta

Cria uma nova conta contábil.

POST/api/accounts

Corpo da Requisição

{
  "name": "Banco Conta Movimento",
  "type": "Asset",
  "code": "1.1.01.002",
  "parent_account_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Resposta

Retorna o objeto da conta recém-criada.

Códigos de Status HTTP

• 201 Created: Conta criada com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: nome, tipo ou código ausente/inválido).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 409 Conflict: Uma conta com o mesmo código já existe.
• 500 Internal Server Error: Erro interno do servidor ao criar a conta.

---

Atualizar uma Conta

Atualiza os detalhes de uma conta existente.

PUT/api/accounts/{id}

Parâmetros de URL

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

Corpo da Requisição

{
  "name": "Banco Principal"
}

Resposta

Retorna o objeto da conta atualizada.

Códigos de Status HTTP

• 200 OK: Conta 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: Conta não encontrada.
• 409 Conflict: Uma conta com o mesmo código já existe (se o código for atualizado).
• 500 Internal Server Error: Erro interno do servidor ao atualizar a conta.

---

Deletar uma Conta

Exclui uma conta contábil.

DELETE/api/accounts/{id}

Parâmetros de URL

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

Resposta

204 No Content em caso de sucesso.

Códigos de Status HTTP

• 204 No Content: Conta deletada com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 403 Forbidden: A conta não pode ser deletada (ex: possui lançamentos associados ou subcontas).
• 404 Not Found: Conta não encontrada.
• 500 Internal Server Error: Erro interno do servidor ao deletar a conta.