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 são o nome e o contato:
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",
"email": "contacto@inmobiliaria-modelo.test",
"phone1": "2234567890" }'
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 |
email | string | sim ⁽¹⁾ | O e-mail que recebe as consultas |
phone1 | string | sim ⁽¹⁾ | O telefone de contato |
phone2 | string | não | Um segundo telefone |
mobile | string | não | O celular (no MercadoLibre vai como segundo telefone) |
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 |
branches | array | não | Várias filiais, cada uma com seu branchRef — veja abaixo |
⁽¹⁾ email e phone1 valem no cliente ou na sua branch — não é preciso repeti-los. Se você
declarar apenas a filial, basta que estejam lá.
Os campos de texto aceitam até 256 caracteres.
Por que email e phone1 são obrigatórios aqui e não ao publicar. São o contato que sai
publicado em cada anúncio: sem eles, o portal não tem para onde enviar as consultas do cliente.
Isso é dito nesta chamada — a única em que você está olhando os dados do cliente — em vez de três
passos mais tarde, quando POST /publication já não
os encontra.
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.
A herança é campo por campo, não tudo ou nada: uma filial que declara apenas o seu nome mantém o telefone e o e-mail do cliente. Por isso declará-la não obriga você a repetir o resto.
| Campo | Tipo |
|---|---|
name phone1 phone2 mobile email address zipcode | string |
zone0 zone1 zone2 zone3 | number — os códigos de zona |
Várias filiais: branches
Se seu cliente tem mais de um escritório e você quer que cada imóvel seja publicado com os dados do
seu, declare-as em branches. Cada uma leva uma referência que você escolhe (branchRef), e é
com essa referência que o imóvel depois diz qual quer:
{
"name": "Inmobiliaria Lopez",
"email": "info@lopez.com",
"phone1": "3414445566",
"branches": [
{ "branchRef": "centro", "name": "Centro", "email": "centro@lopez.com", "phone1": "3414445566" },
{ "branchRef": "norte", "name": "Norte", "email": "norte@lopez.com", "phone1": "3415556677" }
]
}
E ao cadastrar o imóvel:
{ "canonical": { }, "portals": ["zonapropapi"], "branchRef": "norte" }
| Campo | Tipo | Obrigatório | O que é |
|---|---|---|---|
branchRef | string | sim | Sua referência para essa filial. Você a escolhe e ela nunca muda |
mapapropBranchId | number | não | O id da filial no Mapaprop, se seu cliente tem conta — veja abaixo |
Os demais campos são os mesmos de branch. Até 50 filiais por cliente.
A referência tem que ser única dentro do cliente: duas filiais com o mesmo branchRef são
rejeitadas, porque então o imóvel não poderia dizer qual quer.
branch e branches convivem. Se você já usava branch, não precisa mudar nada: continua
funcionando igual, e um imóvel que não envia branchRef publica com ela.
Se você declara branches e não declara branch, cada imóvel tem que enviar seu branchRef:
sem uma filial padrão não há como saber qual você quer, e não escolhemos por você.
Se seu cliente tem conta do Mapaprop (ou se é você)
O caminho mais simples: não declare nada. Se a filial já existe no Mapaprop, envie o branchId
dela como branchRef ao cadastrar o imóvel e pronto:
{ "canonical": { }, "branchRef": 777 }
Esse número é o que você vê na sua conta, e você o lê com
GET /branches. Não é preciso declará-lo na ficha nem dar a ele um
nome seu.
Dar a ela o SEU nome é opcional, e ajuda se seu código preferir falar de "centro" em vez de um
número:
{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }
Então as filiais dele já existem e ele as edita no Mapaprop. Nesse caso não repita os dados
aqui: declare apenas o vínculo entre sua referência e o id real dele, que você pode ler com
GET /branches:
{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }
Os dados de contato dessa filial saem do Mapaprop, não do que você declarar aqui. É o que evita que fiquem duas versões do mesmo telefone, com uma das duas desatualizada.
E se ainda não existem no Mapaprop, nós as criamos
Isto é para um cliente do Mapaprop automatizando a própria conta (o adicional Property API). Se
você declara uma filial com seus dados e sem mapapropBranchId, nós a criamos na sua conta e
devolvemos o id dela, já vinculado à sua referência:
{
"branches": {
"created": [ { "branchRef": "norte", "mapapropBranchId": 779 } ],
"failed": []
},
"customer": { "…" }
}
A partir daí essa filial é uma mais da sua conta: você a vê no Mapaprop, a edita onde quiser, e seus
imóveis a escolhem com branchRef: "norte".
| O que você declara | O que acontece |
|---|---|
branchRef + dados, sem mapapropBranchId | é criada na sua conta e devolvemos o id |
branchRef + mapapropBranchId | já existe: apenas o vínculo é guardado, nada é tocado |
branchRef sozinho, sem dados | nada é criado — seria uma filial vazia |
Se uma falha, as demais são criadas de todo modo. Cada filial é a sua própria operação:
failed diz quais não entraram e por quê — o limite de filiais do seu plano, uma zona que não
existe, um dado inválido. Você corrige essas e repete o PUT: as que já foram criadas não são
duplicadas.
Isto não se aplica se seus clientes não têm conta do Mapaprop. Ali as filiais deles vivem na ficha e não há nada a criar em outro lugar — que é o caso da maioria dos integradores.
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",
"email": "contacto@inmobiliaria-modelo.test",
"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, email ou phone1; 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 todos os métodos
GET·PUT·DELETE- Cadastro de imóveis — o passo seguinte