Declarar um cliente
POST /property-v1/customers
É o primeiro passo de tudo: sem ficha não dá para cadastrar um imóvel, nem pedir um link de conexão, nem publicar.
O clientRef diz de qual cliente é a ficha, igual ao resto da API: vai no header x-client-ref
(recomendado), na query ou no body.
O mínimo que funciona é o nome:
curl -X POST https://property-api.mapaprop.com/property-v1/customers \
-H "Authorization: Bearer $TOKEN" \
-H "x-client-ref: cliente-42" \
-H "Content-Type: application/json" \
-d '{ "name": "Inmobiliaria Modelo" }'
E a ficha completa, com tudo o que é publicado no anúncio:
{
"name": "Inmobiliaria Modelo",
"phone1": "2234567890",
"mobile": "2235550000",
"email": "contacto@inmobiliaria-modelo.test",
"address": "Av. Colón 1234",
"country": 1,
"branch": {
"email": "centro@inmobiliaria-modelo.test",
"phone1": "2234567891",
"name": "Sucursal Centro",
"address": "San Martín 2500"
}
}
Resposta 201:
{
"created": true,
"customer": {
"customerId": "MAPAPROP-PA-000002",
"clientRef": "cliente-42",
"createdAt": "2026-10-01T02:54:30.980Z",
"updatedAt": "2026-10-01T02:54:30.980Z",
"name": "Inmobiliaria Modelo",
"phone1": "2234567890",
"mobile": "2235550000",
"email": "contacto@inmobiliaria-modelo.test",
"address": "Av. Colón 1234",
"country": 1,
"branch": {
"name": "Sucursal Centro",
"phone1": "2234567891",
"email": "centro@inmobiliaria-modelo.test",
"address": "San Martín 2500"
}
}
}
Os campos
| Campo | Tipo | Obrigatório? | |
|---|---|---|---|
name | string | sim | O nome do cliente, como aparece no anúncio |
phone1 | string | não | O telefone de contato |
phone2 | string | não | Um segundo telefone |
mobile | string | não | O celular (no MercadoLibre vai como segundo telefone) |
email | string | não | O e-mail que recebe as consultas |
address | string | não | O endereço |
zipcode | string | não | O CEP |
country | number | não | O país do cliente |
branch | object | não | A filial — veja abaixo |
name é o único obrigatório: sem nome, o anúncio não tem de quem é. Os campos de texto aceitam até 256
caracteres.
Os nomes das chaves são os mesmos que o objeto do imóvel usa, então o bloco que você já montava serve do mesmo jeito. O que mudou é para onde você o envia: aqui uma vez, em vez de em cada cadastro.
A filial é opcional
Se você não enviar branch, a filial herda os dados do cliente. Não é uma comodidade nossa: é o que
a Mapaprop faz quando uma conta é criada, e é a razão de 96 de cada 100 imobiliárias terem uma só
filial com os mesmos dados.
| Campo | Tipo |
|---|---|
name phone1 phone2 mobile email address zipcode | string |
zone0 zone1 zone2 zone3 | number — os códigos de zona |
Repetir o POST é seguro
Um POST sobre um cliente que já existe não emite outro id nem sobrescreve os dados: devolve a
ficha que está lá com created: false e status 200. Isso torna segura uma nova tentativa por
timeout.
Para mudar os dados existe o PUT, que nunca toca no id.
E reativa um cliente com baixa
Se o cliente estava com baixa, o mesmo POST o reativa.
Resposta 200 com revived: true:
{
"created": false,
"revived": true,
"customer": {
"customerId": "MAPAPROP-PA-000002",
"clientRef": "cliente-42",
"name": "Inmobiliaria Modelo",
"phone1": "2234567890",
"revivedAt": "2026-10-02T11:05:41.882Z"
}
}
Volta com o mesmo customerId, então os anúncios publicados dele continuam sendo dele. Os dados que
você enviar nesse POST são os que ficam.
Códigos de resposta
| Código | O que aconteceu | O que fazer |
|---|---|---|
201 | A ficha foi criada | — |
200 | Já existia (created: false) ou foi reativada (revived: true) | — |
400 | Falta name, country não é um inteiro positivo, branch não é um objeto, ou um texto passa de 256 caracteres | O campo vem em field |
400 | Falta o clientRef | Envie o header x-client-ref: sem ele não sabemos de qual cliente é a ficha, e não adivinhamos |
401 | Token ausente ou inválido | — |
403 | O seu token não tem o scope property-api-create | Escreva para nós para habilitá-lo |
Relacionado
- Clientes — o que é a ficha e os quatro métodos
GET·PUT·DELETE- Cadastro de imóveis — o passo seguinte