Clientes
Antes de cadastrar seu primeiro imóvel, você declara a ficha do cliente dono dele: o nome, o contato e a filial. Isso se faz uma vez por cliente e, a partir daí, todos os imóveis dele a herdam.
Dizemos cliente e não "imobiliária" de propósito: pode ser uma imobiliária, uma incorporadora, um
administrador de locações ou um particular. A API o chama de customer, e o id dele é o seu clientRef.
Os quatro métodos
| O que faz | ||
|---|---|---|
POST | Declara o cliente e devolve o customerId que atribuímos a ele | property-api-create |
GET | Devolve o que você declarou | property-api-read |
PUT | Muda os dados. Não muda o customerId | property-api-update |
DELETE | Dá baixa no cliente. Reversível | property-api-delete |
Os quatro vão para a mesma rota, /property-v1/customers, e o cliente sobre o qual você opera é
indicado pelo header x-client-ref — igual ao resto da API.
É destes dados que saem o nome, o telefone, o e-mail e o endereço publicados em cada anúncio.
Por que não vai em cada imóvel
Foi um integrador que pediu, e tinha razão: você tinha que repetir os mesmos dados do cliente em cada cadastro, e eram os mesmos para os 500 imóveis dela.
Declarando-os uma vez, os imóveis novos os herdam sozinhos e você não precisa enviá-los nunca mais.
customerId — nós o emitimos
O customerId (MAPAPROP-PA-000002) não é você que escolhe: nós o atribuímos ao criar a ficha, e é
o código com que esse cliente se identifica diante dos portais.
O customerId nunca muda. O PUT não o muda, e uma ficha com baixa e depois reativada volta com
o mesmo. Se mudasse, os anúncios que o seu cliente já tem publicados ficariam pendurados num código
que deixou de existir.
O seu clientRef é outra coisa: é o seu identificador, aquele que você usa para nos dizer de qual
cliente está falando. Nós não o interpretamos.
O ciclo de vida
POST → o cliente fica declarado, com o seu customerId
├── GET consultar
├── PUT mudar os dados (o id não é tocado)
└── DELETE dar baixa ─────┐
│
POST (de novo) ←───────────────────────┘ o reativa, com o MESMO customerId
Um POST repetido sobre um cliente que já existe não duplica nada nem emite outro id: devolve o que
está lá, com created: false.
O que acontece se você não a declarar
| Endpoint | Sem ficha |
|---|---|
POST /properties | 400 com rule: account_required |
POST /properties/verify | 200 — é um testador: simula os dados do cliente com um placeholder e o declara em customerSource: "placeholder" |
É por isso que você pode testar o seu objeto no primeiro dia, antes de declarar nada.
O que você pode fazer com a ficha declarada
A ficha não é só o contato que os imóveis herdam: é o cliente para quem depois você conecta portais e publica.
| Para | Vá para |
|---|---|
| Conectar a conta de Zonaprop dele | Conectar com um link |
| Conectar Argenprop, Cabaprop ou MercadoLibre | Conexões com portais |
| Ver a situação das conexões dele, ou desconectar | Conexões com portais |
| Entender a cota mensal da Zonaprop | Cota mensal e limites |
| Cadastrar os imóveis dele | Cadastro de imóveis |
O código que atribuímos aqui (MAPAPROP-PA-000123) é aquele com que o seu cliente se identifica
diante dos portais. É por isso que a ficha vem primeiro: sem ela não dá para emitir um link de conexão.
Ainda não há como listar os seus clientes pela API. Cada método opera sobre um clientRef por
vez, então o registro de quais clientes você declarou fica com você. Se precisar enumerá-los —
sobretudo para saber quais estão ativos e quais estão com baixa — escreva para dev@mapaprop.com e nós
priorizamos.