BETA

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

CampoTipoObrigatório?
namestringsimO nome do cliente, como aparece no anúncio
emailstringsim ⁽¹⁾O e-mail que recebe as consultas
phone1stringsim ⁽¹⁾O telefone de contato
phone2stringnãoUm segundo telefone
mobilestringnãoO celular (no MercadoLibre vai como segundo telefone)
addressstringnãoO endereço
zipcodestringnãoO CEP
countrynumbernãoO país do cliente
branchobjectnãoA filial — veja abaixo
branchesarraynãoVá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.

CampoTipo
name phone1 phone2 mobile email address zipcodestring
zone0 zone1 zone2 zone3number — 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" }
CampoTipoObrigatórioO que é
branchRefstringsimSua referência para essa filial. Você a escolhe e ela nunca muda
mapapropBranchIdnumbernãoO 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ê declaraO que acontece
branchRef + dados, sem mapapropBranchIdé criada na sua conta e devolvemos o id
branchRef + mapapropBranchIdjá existe: apenas o vínculo é guardado, nada é tocado
branchRef sozinho, sem dadosnada é 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ódigoO que aconteceuO que fazer
201A ficha foi criada—
200Já existia (created: false) ou foi reativada (revived: true)—
400Falta name, email ou phone1; country não é um inteiro positivo; branch não é um objeto; ou um texto passa de 256 caracteresO campo vem em field
400Falta o clientRefEnvie o header x-client-ref: sem ele não sabemos de qual cliente é a ficha, e não adivinhamos
401Token ausente ou inválido—
403O seu token não tem o scope property-api-createEscreva para nós para habilitá-lo

Relacionado