Usuários — /v1/users

Diferente de organizations/, estas rotas não recebem o id da organização na URL: elas sempre operam sobre a organização em contexto do usuário autenticado. Leia ../README.md antes de integrar — resumindo: envie o header X-Organization-Id: <uuid> para escolher a organização; se omitido, a API usa a organização de maior id à qual o usuário pertence.

Todas as rotas exigem 🔒 Authorization: Bearer <token>.

Método	Rota	Descrição
GET	/v1/users	Lista os usuários da organização em contexto
POST	/v1/users	Cria um usuário e o associa à organização em contexto
GET	/v1/users/{id}	Detalha um usuário (precisa estar na organização em contexto)
PUT/PATCH	/v1/users/{id}	Atualiza um usuário
DELETE	/v1/users/{id}	Remove o usuário da organização e o soft-deleta

Em todas as rotas com {id}, se o usuário alvo não pertencer à organização em contexto, a API retorna 404 ("Usuário não encontrado nesta organização."), mesmo que o usuário exista em outra organização.

TypeScript

type OrgUser = {
    id: number;
    name: string;
    email: string;
    phone: string | null;
    email_verified_at: string | null;
};

---

GET /v1/users

Resposta 200 (chave: users)

{
    "code": 200,
    "success": true,
    "users": [
        {
            "id": 2,
            "name": "...",
            "email": "...",
            "phone": "...",
            "email_verified_at": null
        }
    ]
}

await apiFetch<ApiSuccess<OrgUser[], "users">>("GET", "/users", {
    token,
    organizationUuid,
});

curl https://api.fastgivr.com.br/v1/users -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG_UUID"

---

POST /v1/users

Cria um novo usuário e já o associa à organização em contexto — equivalente a "convidar/adicionar membro".

Body

Campo	Tipo	Obrigatório	Regras
name	string	sim	máx. 255
email	string	sim	e-mail válido, único em users
password	string	sim	mín. 8, confirmed
password_confirmation	string	sim	igual a password
phone	string	não	máx. 20

Resposta 201 (chave: user). Erro 422 se email já existir. Erro 404 se o usuário autenticado não pertencer a nenhuma organização (não há organização em contexto para associar o novo usuário).

type StoreUserBody = {
    name: string;
    email: string;
    password: string;
    password_confirmation: string;
    phone?: string;
};

await apiFetch<ApiSuccess<OrgUser, "user">>("POST", "/users", {
    token,
    organizationUuid,
    body,
});

curl -X POST https://api.fastgivr.com.br/v1/users \
  -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG_UUID" -H "Content-Type: application/json" \
  -d '{"name":"Bruno","email":"bruno@example.com","password":"segredo123","password_confirmation":"segredo123"}'

---

GET /v1/users/{id}

Resposta 200 (chave: user). Erro 404 se o usuário não existir ou não pertencer à organização em contexto.

await apiFetch<ApiSuccess<OrgUser, "user">>("GET", `/users/${id}`, {
    token,
    organizationUuid,
});

---

PUT/PATCH /v1/users/{id}

Todos os campos são opcionais (envie só o que quer alterar). Omitir password mantém a senha atual.

Body

Campo	Tipo	Regras
name	string	máx. 255
email	string	e-mail válido, único em users (ignorando o próprio registro)
phone	string	máx. 20
password	string	mín. 8, confirmed (se enviado, precisa vir com password_confirmation)

Resposta 200 (chave: user).

type UpdateUserBody = Partial<{
    name: string;
    email: string;
    phone: string;
    password: string;
    password_confirmation: string;
}>;

await apiFetch<ApiSuccess<OrgUser, "user">>("PUT", `/users/${id}`, {
    token,
    organizationUuid,
    body,
});

---

DELETE /v1/users/{id}

Remove a associação do usuário com a organização em contexto e remove o usuário — ele deixa de existir para o sistema, não apenas de pertencer à organização.

Resposta 200: só message.

await apiFetch("DELETE", `/users/${id}`, { token, organizationUuid });