API v1 — visão geral

/v1 é a API oficial. Autenticação em Autenticação; formato de resposta e erros em Respostas e erros.

Módulos: Organizações, Usuários e Clientes. Referência com exemplos curl e TypeScript: api-v1/.

Integrando com uma LLM ou agente?

Leia o Guia para LLMs e agentes — página auto-contida com o contrato completo (entrada e saída de cada endpoint, tipos, cliente pronto, receitas e regras) para uma LLM integrar a v1 lendo um único documento.

Contexto de organização

• organizations recebe a organização explicitamente na URL ({id}).
• users e clients operam sobre a organização em contexto, resolvida assim:
  1. header X-Organization-Id (ou organization) com o uuid de uma organização à qual o usuário pertence; ou, na ausência dele,
  2. a organização mais recente do usuário.
  3. Se o usuário não pertencer a nenhuma organização, a resposta é 404.
• Sempre envie X-Organization-Id: <uuid> nas chamadas a users e clients. O uuid vem em GET /v1/auth/me ou na resposta de POST /v1/organizations.

---

Organizações

Recurso REST em /v1/organizations. Todas 🔒 (header Authorization: Bearer <token>).

GET /v1/organizations

Entrada: header Authorization. Saída: 200, chave organizations — array com as organizações do usuário.

POST /v1/organizations

Entrada (corpo JSON):

Campo	Tipo	Regras
name	string	obrigatório, máx. 255
email	string	opcional, e-mail, máx. 255
document	string	obrigatório, máx. 20, único (CPF ou CNPJ)

Saída: 201, chave organization, message: "Organização criada com sucesso." O usuário fica vinculado à organização; ela nasce com status = INACTIVE. 422 em validação.

GET /v1/organizations/{id}

Entrada: path id (numérico). O usuário precisa pertencer à organização. Saída: 200, chave organization. 404 se não existir ou não for do usuário.

PUT/PATCH /v1/organizations/{id}

Entrada (corpo JSON, todos opcionais — envie só o que muda):

Campo	Tipo	Regras
name	string	máx. 255
email	string|null	e-mail, máx. 255
document	string	máx. 20, único (o próprio registro é ignorado)
status	string	ACTIVE, INACTIVE, SUSPENDED, DISABLED, DISQUALIFIED, SOFT_DELETED ou DELETED

Saída: 200, chave organization, message: "Organização atualizada com sucesso."

DELETE /v1/organizations/{id}

Entrada: path id. Saída: 200, message: "Organização removida com sucesso."

---

Usuários

Recurso REST em /v1/users. Todas 🔒 + header X-Organization-Id.

GET /v1/users

Entrada: headers Authorization + X-Organization-Id. Saída: 200, chave users — usuários da organização em contexto.

POST /v1/users

Entrada (corpo JSON):

Campo	Tipo	Regras
name	string	obrigatório, máx. 255
email	string	obrigatório, e-mail, único, máx. 255
password	string	obrigatório, mín. 8 caracteres
password_confirmation	string	obrigatório, igual a password
phone	string|null	opcional, máx. 20

Saída: 201, chave user, message: "Usuário criado com sucesso." (vinculado à organização).

GET /v1/users/{id}

Entrada: path id (deve pertencer à organização em contexto). Saída: 200, chave user. 404 se não pertencer.

PUT/PATCH /v1/users/{id}

Entrada (corpo JSON, opcionais):

Campo	Tipo	Regras
name	string	máx. 255
email	string	e-mail, único (o próprio registro é ignorado)
phone	string|null	máx. 20
password	string	mín. 8 caracteres (envie password_confirmation junto)

Saída: 200, chave user, message: "Usuário atualizado com sucesso."

DELETE /v1/users/{id}

Entrada: path id. Saída: 200, message: "Usuário removido com sucesso."

---

Clientes

Recurso REST em /v1/clients. Todas 🔒 + header X-Organization-Id.

GET /v1/clients

Entrada: headers Authorization + X-Organization-Id. Saída: 200, chave clients — clientes da organização, do mais recente para o mais antigo.

POST /v1/clients

Entrada (corpo JSON):

Campo	Tipo	Regras
name	string	obrigatório, máx. 255
email	string|null	e-mail, máx. 255
phone	string|null	máx. 20
document	string|null	máx. 20, único por organização
type	string|null	individual ou company
gender	string|null	male ou female
birthdate	date|null	YYYY-MM-DD
metadata	object|null	livre

Saída: 201, chave client, message: "Cliente criado com sucesso." Nasce com status = ACTIVE. 422 com "Já existe um cliente com este documento nesta organização." em documento duplicado.

GET /v1/clients/{id}

Entrada: path id (da organização em contexto). Saída: 200, chave client. 404 se não pertencer.

PUT/PATCH /v1/clients/{id}

Entrada (corpo JSON, opcionais): mesmos campos de POST (name, email, phone, document, type, gender, birthdate, metadata). Saída: 200, chave client, message: "Cliente atualizado com sucesso."

DELETE /v1/clients/{id}

Entrada: path id. Saída: 200, message: "Cliente removido com sucesso."