Organizações — /v1/organizations

(um usuário pode pertencer a várias organizações).

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

Método	Rota	Descrição
GET	/v1/organizations	Lista as organizações do usuário autenticado
POST	/v1/organizations	Cria uma organização
GET	/v1/organizations/{id}	Detalha uma organização
PUT/PATCH	/v1/organizations/{id}	Atualiza uma organização
DELETE	/v1/organizations/{id}	Remove uma organização

{id} é o id numérico da organização (não o uuid). Em todas as rotas com {id}, a API verifica que o usuário autenticado pertence àquela organização — caso contrário, retorna 404 ("Organização não encontrada."), mesmo que a organização exista para outro usuário.

TypeScript

type Organization = {
    id: number;
    uuid: string;
    name: string;
    email: string | null;
    document: string;
    status:
        | "ACTIVE"
        | "INACTIVE"
        | "SUSPENDED"
        | "DISABLED"
        | "DISQUALIFIED"
        | "SOFT_DELETED"
        | "DELETED";
    created_by: number;
    updated_by: number | null;
    created_at: string;
    updated_at: string;
    deleted_at: string | null;
};

---

GET /v1/organizations

Sem parâmetros. Retorna todas as organizações às quais o usuário pertence.

Resposta 200 (chave: organizations)

{
    "code": 200,
    "success": true,
    "organizations": [
        {
            "id": 1,
            "uuid": "b3f2...-...",
            "name": "Acme Ltda",
            "email": "contato@acme.com",
            "document": "12345678000199",
            "status": "ACTIVE",
            "created_by": 1,
            "updated_by": null,
            "created_at": "...",
            "updated_at": "...",
            "deleted_at": null
        }
    ]
}

await apiFetch<ApiSuccess<Organization[], "organizations">>(
    "GET",
    "/organizations",
    { token },
);

curl https://api.fastgivr.com.br/v1/organizations -H "Authorization: Bearer $TOKEN"

---

POST /v1/organizations

Cria a organização e associa o usuário autenticado a ela. Não há mais restrição de "uma organização por usuário" — o usuário pode criar/pertencer a quantas organizações quiser.

Body

Campo	Tipo	Obrigatório	Regras
name	string	sim	máx. 255
email	string	não	e-mail válido, máx. 255
document	string	sim	máx. 20, único

uuid é gerado automaticamente. status inicia como INACTIVE.

Resposta 201 (chave: organization) — mesmo shape de um item da listagem acima. Erro 422 se document já existir.

type StoreOrganizationBody = { name: string; email?: string; document: string };

await apiFetch<ApiSuccess<Organization, "organization">>(
    "POST",
    "/organizations",
    { token, body },
);

curl -X POST https://api.fastgivr.com.br/v1/organizations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Acme Ltda","document":"12345678000199"}'

---

GET /v1/organizations/{id}

Resposta 200 (chave: organization) — mesmo shape de um item da listagem. Erro 404 se a organização não existir ou não pertencer ao usuário.

await apiFetch<ApiSuccess<Organization, "organization">>(
    "GET",
    `/organizations/${id}`,
    { token },
);

---

PUT/PATCH /v1/organizations/{id}

Todos os campos são opcionais (envie só o que quer alterar).

Body

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

updated_by é preenchido automaticamente com o id do usuário autenticado.

Resposta 200 (chave: organization). Erro 404 se não pertencer ao usuário. Erro 422 em validação (ex.: status inválido, document duplicado).

type UpdateOrganizationBody = Partial<{
    name: string;
    email: string;
    document: string;
    status: Organization["status"];
}>;

await apiFetch<ApiSuccess<Organization, "organization">>(
    "PUT",
    `/organizations/${id}`,
    { token, body },
);

---

DELETE /v1/organizations/{id}

Remoção lógica: a organização deixa de aparecer nas listagens.

Resposta 200: só message. Erro 404 se não pertencer ao usuário.

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