Organizações

O endpoint de Organizações é central para o Finvy, pois gerencia os espaços de trabalho onde todos os dados contábeis residem. Um usuário pode ser proprietário de várias organizações ou membro de organizações compartilhadas por outros.

Objeto Organização

Atributo	Tipo	Descrição
id	string	O ID único da organização (UUID).
name	string	O nome da organização (ex: "Minha Empresa LTDA").
cnpj	string	Opcional. O CNPJ da organização.
razao_social	string	Opcional. A razão social da organização.
uf	string	Opcional. A unidade federativa (estado) da organização.
municipio	string	Opcional. O município da organização.
is_personal	boolean	true se for a organização pessoal padrão do usuário. false caso contrário.
is_shared	boolean	true se a organização foi compartilhada com o usuário atual por outro.
shared_from_user_name	string	O nome do usuário que compartilhou a organização. null se não for compartilhada.

---

Listar Organizações Acessíveis

Retorna uma lista de todas as organizações que o usuário atual pode acessar, incluindo as próprias e as compartilhadas.

GET/api/organizations

Resposta

Retorna um array de objetos de Organização.

Códigos de Status HTTP

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

---

Criar uma Organização

Cria uma nova organização e automaticamente atribui o usuário atual como owner (proprietário). Um período contábil padrão também é criado para a nova organização.

POST/api/organizations

Corpo da Requisição

{
  "name": "Nova Consultoria XYZ",
  "cnpj": "12.345.678/0001-99"
}

Resposta

Retorna um objeto contendo a organização e o período contábil criados.

Códigos de Status HTTP

• 201 Created: Organização criada com sucesso.
• 400 Bad Request: Dados da requisição inválidos (ex: nome ausente).
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 500 Internal Server Error: Erro interno do servidor ao criar a organização.

---

Atualizar uma Organização

Atualiza os detalhes de uma organização. Apenas usuários com papel de owner ou admin podem realizar esta ação.

PUT/api/organizations/{id}

Parâmetros de URL

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

Corpo da Requisição

{
  "name": "Consultoria XYZ (Atualizado)",
  "uf": "SP"
}

Resposta

Retorna o objeto da organização atualizada.

Códigos de Status HTTP

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

---

Deletar uma Organização

Exclui permanentemente uma organização e todos os seus dados associados (períodos contábeis, lançamentos, contas, etc.). Esta ação não pode ser desfeita.

• Apenas usuários com papel de owner ou admin podem deletar uma organização.
• Não é possível deletar uma organização pessoal (is_personal: true).

DELETE/api/organizations/{id}

Parâmetros de URL

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

Resposta

204 No Content em caso de sucesso.

Códigos de Status HTTP

• 204 No Content: Organização deletada com sucesso.
• 401 Unauthorized: Autenticação necessária ou credenciais inválidas.
• 403 Forbidden: Usuário não tem permissão para deletar a organização ou tenta deletar uma organização pessoal.
• 404 Not Found: Organização não encontrada.
• 500 Internal Server Error: Erro interno do servidor ao deletar a organização.