Clientes — /v1/clients

Assim como users/, 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/clients	Lista os clientes da organização em contexto
POST	/v1/clients	Cria um cliente na organização em contexto
GET	/v1/clients/{id}	Detalha um cliente (precisa estar na organização em contexto)
PUT/PATCH	/v1/clients/{id}	Atualiza um cliente
DELETE	/v1/clients/{id}	Remove um cliente

Em todas as rotas com {id}, se o cliente não pertencer à organização em contexto, a API retorna 404, mesmo que o cliente exista em outra organização.

TypeScript

type OrgClient = {
    id: number;
    code: string;
    name: string;
    email: string | null;
    phone: string | null;
    document: string | null;
    type: "individual" | "company" | null;
    gender: "male" | "female" | null;
    birthdate: string | null;
    metadata: Record<string, unknown> | null;
    status: string;
    organization_id: number;
    created_at: string;
    updated_at: string;
    deleted_at: string | null;
};

---

GET /v1/clients

Sem parâmetros. Retorna todos os clientes (não removidos) da organização em contexto, ordenados do mais recente para o mais antigo.

Resposta 200 (chave: clients)

{
    "code": 200,
    "success": true,
    "clients": [
        {
            "id": 10,
            "code": "a1b2c3...",
            "name": "Maria da Silva",
            "email": "maria@example.com",
            "phone": "11999999999",
            "document": "12345678900",
            "type": "individual",
            "gender": "female",
            "birthdate": "1990-01-01",
            "metadata": null,
            "status": "2",
            "organization_id": 1,
            "account_id": -1,
            "created_by": 3,
            "created_at": "...",
            "updated_at": "...",
            "deleted_at": null
        }
    ]
}

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

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

---

POST /v1/clients

Cria o cliente já associado à organização em contexto. status inicia como ACTIVE.

Body

Campo	Tipo	Obrigatório	Regras
name	string	sim	máx. 255
email	string	não	e-mail válido, máx. 255
phone	string	não	máx. 20
document	string	não	máx. 20, único por organização (o mesmo documento pode se repetir entre organizações diferentes)
type	string	não	individual ou company
gender	string	não	male ou female
birthdate	string	não	data válida (YYYY-MM-DD)
metadata	array	não	objeto livre

Resposta 201 (chave: client) — mesmo shape de um item da listagem acima. Erro 422 se document já existir na mesma organização. Erro 404 se o usuário autenticado não pertencer a nenhuma organização.

type StoreClientBody = Partial<
    Pick<
        OrgClient,
        | "email"
        | "phone"
        | "document"
        | "type"
        | "gender"
        | "birthdate"
        | "metadata"
    >
> & { name: string };

await apiFetch<ApiSuccess<OrgClient, "client">>("POST", "/clients", {
    token,
    organizationUuid,
    body,
});

curl -X POST https://api.fastgivr.com.br/v1/clients \
  -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG_UUID" -H "Content-Type: application/json" \
  -d '{"name":"Maria da Silva","document":"12345678900","email":"maria@example.com"}'

---

GET /v1/clients/{id}

Resposta 200 (chave: client) — mesmo shape de um item da listagem. Erro 404 se o cliente não existir ou não pertencer à organização em contexto.

await apiFetch<ApiSuccess<OrgClient, "client">>("GET", `/clients/${id}`, {
    token,
    organizationUuid,
});

---

PUT/PATCH /v1/clients/{id}

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

Body: mesmos campos de POST, todos opcionais.

Resposta 200 (chave: client). Erro 404 se não pertencer à organização em contexto. Erro 422 em validação (ex.: document duplicado na mesma organização).

type UpdateClientBody = Partial<StoreClientBody>;

await apiFetch<ApiSuccess<OrgClient, "client">>("PUT", `/clients/${id}`, {
    token,
    organizationUuid,
    body,
});

---

DELETE /v1/clients/{id}

Marca status como DELETED e remove o cliente das listagens.

Resposta 200: só message. Erro 404 se não pertencer à organização em contexto.

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