Pular para o conteúdo

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.


GET /api/v1/crm/customers

Parâmetros de Query:

ParâmetroTipoDescrição
querystringNome, e-mail, telefone ou código (CLI-000001)
pagenumberNúmero da página (default: 1)
pageSizenumberItens por página (default: 25, max: 100)
statusstringactive, won ou lost
dealTypestringsale ou rental
citystringCidade
statestringUF, duas letras
rolestringPapel já visto (ex.: buyer, seller)

Exemplo:

Janela do terminal
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",
"primaryEmail": "[email protected]",
"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
}
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).

POST /api/v1/crm/customers

Exige 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.

Janela do terminal
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.

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.

CampoTipoDescrição
expectedRevisionnumberrevision lido no GET. Opcional.
displayNamestringNome
primaryEmailstringE-mail
primaryPhonestringTelefone, de preferência com DDI (+55…)
cpfCnpjstringCPF ou CNPJ
professionstringProfissão
birthDatestringData AAAA-MM-DD
genderstringGênero
maritalStatusstringEstado civil
incomeRangeenumlow, medium, high, premium
citystringCidade
statestringUF
neighborhoodstringBairro
postalCodestringCEP
Janela do terminal
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.


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.