Clientes
Esta seção documenta o cadastro da pessoa no CRM. Um cliente é a pessoa (comprador, vendedor, inquilino, proprietário). O array contacts de uma negociação só diz qual papel essa pessoa tem naquela negociação.
Para corrigir nome, e-mail ou telefone, use os endpoints abaixo. Não reescreva contacts em PATCH /api/v1/crm/deals/{id}: outro telefone pode apontar para outra pessoa ou criar um cadastro novo.
A chave de API respeita as mesmas permissões de Clientes da interface. Quem só vê os próprios clientes na lista também só os vê aqui. Cliente fora do alcance responde 404. Para o PATCH, ver o cliente não basta: quem só o acompanha como Observador recebe 403.
Não há DELETE nesta API. Apagar um cliente é operação de governança (LGPD), feita na interface.
📊 Endpoints
Seção intitulada “📊 Endpoints”Listar Clientes
Seção intitulada “Listar Clientes”GET /api/v1/crm/customersParâmetros de Query:
| Parâmetro | Tipo | Descrição |
|---|---|---|
query | string | Nome, e-mail, telefone ou código (CLI-000001) |
page | number | Número da página (default: 1) |
pageSize | number | Itens por página (default: 25, max: 100) |
status | string | active, won ou lost |
dealType | string | sale ou rental |
city | string | Cidade |
state | string | UF, duas letras |
role | string | Papel já visto (ex.: buyer, seller) |
Exemplo:
curl -X GET "https://app.garagem.ai/api/v1/crm/customers?query=maria&pageSize=20" \ -H "Authorization: Bearer sua_api_key"Resposta:
{ "items": [ { "id": "uuid-do-cliente", "customerCode": "CLI-000001", "displayName": "Maria Souza", "primaryPhone": "+5511999990000", "status": "active", "isDemandSide": true, "isSupplySide": false, "city": "São Paulo", "state": "SP", "assignedToId": "uuid-do-corretor", "dealCount": 2, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-16T12:00:00.000Z" } ], "total": 150, "page": 1, "pageSize": 20}Buscar Cliente por ID
Seção intitulada “Buscar Cliente por ID”GET /api/v1/crm/customers/{id}dealIds traz no máximo 50 negociações, as mais recentes. dealCount é o total.
Guarde revision. No PATCH, envie esse número em expectedRevision para não gravar em cima de uma alteração mais nova (409 se o cadastro mudou).
Criar Cliente
Seção intitulada “Criar Cliente”POST /api/v1/crm/customersExige displayName e pelo menos um de email ou phone, mais idempotencyKey (8 a 128 caracteres). Reenviar a mesma chave não cria outro cliente.
Se o e-mail ou o telefone já pertence a um cliente, a resposta reutiliza esse cadastro (status: "reused"). Contato bloqueado volta status: "blocked" e não cria linha nova.
curl -X POST https://app.garagem.ai/api/v1/crm/customers \ -H "Authorization: Bearer sua_api_key" \ -H "Content-Type: application/json" \ -d '{ "idempotencyKey": "form-site-2024-01-15-maria", "displayName": "Maria Souza", "email": "[email protected]", "phone": "+5511999990000", "side": "demand", "city": "São Paulo", "state": "SP" }'side é demand (compra/aluguel) ou supply (venda/locação). O servidor não grava a chave de idempotência no cliente.
Atualizar Cliente
Seção intitulada “Atualizar Cliente”PATCH /api/v1/crm/customers/{id}Envie só os campos que mudam. Pelo menos um campo de perfil é obrigatório. null limpa o campo. Nome, e-mail e telefone passam a valer nas negociações que leem esse cliente.
| Campo | Tipo | Descrição |
|---|---|---|
expectedRevision | number | revision lido no GET. Opcional. |
displayName | string | Nome |
primaryEmail | string | |
primaryPhone | string | Telefone, de preferência com DDI (+55…) |
cpfCnpj | string | CPF ou CNPJ |
profession | string | Profissão |
birthDate | string | Data AAAA-MM-DD |
gender | string | Gênero |
maritalStatus | string | Estado civil |
incomeRange | enum | low, medium, high, premium |
city | string | Cidade |
state | string | UF |
neighborhood | string | Bairro |
postalCode | string | CEP |
curl -X PATCH https://app.garagem.ai/api/v1/crm/customers/uuid-do-cliente \ -H "Authorization: Bearer sua_api_key" \ -H "Content-Type: application/json" \ -d '{ "expectedRevision": 3, "displayName": "Maria Souza", "primaryPhone": "+5511988887777" }'A resposta é o mesmo objeto de GET /api/v1/crm/customers/{id}, já com a revision nova.
Não dá para apagar o último e-mail e o último telefone ao mesmo tempo: o cliente precisa continuar com uma identidade.
📋 O que este recurso não faz
Seção intitulada “📋 O que este recurso não faz”Não cria negociação nem define o papel (buyer, seller, …). Isso continua em Negociações, no array contacts.
Não lista conversas de WhatsApp. Um resultado da busca da interface pode incluir um chat; esta API só devolve clientes.
Campos customizados do cliente não entram neste contrato.