POST /properties
É o mesmo objeto e a mesma resposta que
POST /properties/verify, com duas diferenças: aqui o
imóvel fica salvo e devolvemos um identificador para operar com ele depois.
Se o verify diz que um portal pode publicar seu imóvel, o cadastro diz o mesmo. Não há surpresas entre os dois.
Não publica em nenhum portal. O cadastro salva o imóvel e prepara tudo; publicar é um passo à parte.
Para que serve
Para carregar o imóvel uma única vez e ficar com um identificador que você usa para consultá-lo, atualizar suas imagens ou excluí-lo.
Você envia as imagens como URLs e nós as baixamos: a partir do cadastro elas ficam nos nossos servidores.
Resource URL
POST https://property-api.mapaprop.com/property-v1/properties
Autenticação
Igual ao resto da API: Authorization: Bearer <seu token>.
curl -X POST https://property-api.mapaprop.com/property-v1/properties \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @propiedad.json
🔑 clientRef — de QUAL cliente é este imóvel
Viaja junto com o token, de qualquer uma destas três formas:
x-client-ref: cliente-42 ← header (recomendado)
?clientRef=cliente-42 ← query
{ "clientRef": "cliente-42", … } ← body
É o id do CLIENTE, não do imóvel. O mesmo clientRef para todos os imóveis desse seu
cliente.
É o que agrupa o inventário: GET /properties devolve os de um clientRef, e é o que separa um
cliente seu de outro. Se você enviar o id de cada imóvel, cada um fica no seu próprio grupo e a lista
devolve um só.
Você escolhe o valor e ele é opaco para nós: seu id interno, um UUID, o que usar — desde que
identifique o cliente. É o mesmo clientRef com que você registra
as conexões dela aos portais.
O corpo da requisição
O cliente se declara UMA vez, não em cada imóvel. Antes do seu primeiro cadastro, declare-a com
POST /property-v1/customers: devolve o customerId que a Mapaprop atribui a ela, e a partir daí
todos os seus imóveis herdam o nome, telefone, e-mail, endereço e filial. Sem ela o cadastro responde
400 com rule: account_required.
Mudar um dado depois é um PUT na mesma rota. ⚠️ Alcança os imóveis novos: os que você já cadastrou
conservam o contato com que foram criados, que é o registro de como foram publicados.
⚠️ Se você enviar customer dentro do objeto, ele é ignorado (como propertyId, customerId e
branchId).
Exatamente o mesmo que o verify: o objeto vai em canonical.
{
"canonical": { "…o objeto do imóvel…" },
"branchRef": "norte"
}
| Chave | Tipo | Obrigatório | O que é |
|---|---|---|---|
canonical | object | sim | O objeto do imóvel |
portals | array | não | Em quais portais verificá-lo |
options | object | não | Opções por portal |
branchRef | string | não | Com qual filial do cliente ele é publicado — veja abaixo |
branchRef — com qual filial ele é publicado
Se seu cliente tem várias filiais declaradas em
branches, branchRef diz com qual este imóvel sai: o
nome, o telefone e o email dela são o que o portal publica como contato do anúncio.
- Se você não enviar, sai com a filial padrão (
branch). - Se seu cliente declara
branchese não tembranch, é obrigatório: sem filial padrão não há como saber qual você quer, e não escolhemos por você. - Se você enviar uma referência que não existe, a resposta é
400e diz quais são as válidas. - Se a filial já existe no Mapaprop, envie o
branchIddela (um número) e não é preciso declará-la na ficha:"branchRef": 777.
A filial é congelada no imóvel ao cadastrá-lo. É o registro dos dados com que foi publicado, e
mudá-la depois é um 409: apague o imóvel e cadastre-o de novo. Mudar os dados da filial na
ficha, por outro lado, alcança os imóveis novos.
Os campos, suas regras e quais são obrigatórios estão em
O objeto JSON do imóvel. A configuração de publicação por
portal, em A chave publication.
Teste o objeto com /properties/verify antes de
cadastrar. Não cria nada e diz exatamente o que o cadastro vai dizer.
A resposta
201 Created. É a resposta do verify mais estas cinco chaves:
{
"paId": "01M3PTZ8YBMM5DSNW03WP8VD9E",
"saved": true,
"savedAt": "2026-09-29T15:01:46.059Z",
"status": "active",
"images": {
"status": "processing",
"total": 4,
"processed": 0,
"message": "Procesando 4 imágenes…"
},
"mapaprop": { "state": "pending" },
"object": { "…igual ao verify…" },
"portals": { "…igual ao verify…" },
"summary": { "…igual ao verify…" }
}
| Chave | O que é |
|---|---|
clientRef | De qual cliente é. O mesmo que você enviou no envelope — devolvemos para que possa cruzá-lo com a sua base sem lembrar com o que perguntou |
paId | O identificador do imóvel na nossa API. É a sua referência para tudo o que vier depois |
saved | Ficou salvo |
savedAt | Quando |
status | active, ou deleted se você o excluiu |
images | O estado das suas imagens — veja abaixo |
mapaprop | Só se você é cliente da Mapaprop: o estado do cadastro na sua conta — veja abaixo |
Os blocos object, portals e summary são os mesmos do verify e estão explicados
lá.
🔑 Guarde o paId
É o único identificador desse imóvel do nosso lado. Guarde-o no seu sistema junto ao id que você usa. Sem ele não há como consultá-lo, atualizar as imagens nem excluí-lo.
Você não o gera e não pode escolhê-lo. Se enviar o mesmo objeto de novo, é criado um imóvel novo
com outro paId: o cadastro não deduplica.
As imagens: o que acontece depois do 201
Ao responder, começamos a baixar suas imagens. É a única parte do cadastro que não é imediata.
201 → images.status: "processing" …baixando suas imagens…
images.status: "ready" pronto
o "partial" algumas não puderam ser baixadas
Enquanto estiverem em processing, o imóvel não pode ser modificado, excluído nem publicado.
Qualquer chamada devolve 409 informando quantas já foram.
O estado é consultado com GET /property-v1/properties/{paId}. Costuma
levar poucos segundos.
Espere 2-3 segundos entre consultas. Com volumes normais bastam 3 ou 4: medido, 40 imagens levaram 9 segundos. Consultar em um laço sem pausa não vai lhe dar a resposta mais rápido.
O que fazer com cada estado
images.status | O que significa | O que você faz |
|---|---|---|
processing | Estamos baixando | Espera e consulta de novo |
ready | Todas nos nossos servidores | Segue em frente |
partial | Algumas não puderam ser baixadas | Olha assets e tenta de novo |
Quando algo falha: assets
O GET traz uma entrada por imagem, com a URL que falhou e o motivo:
"assets": [
{ "n": 1, "slot": "image", "source": "https://tu-cdn.com/frente.jpg",
"url": "https://…/image-1.jpg", "ok": true },
{ "n": 2, "slot": "image", "source": "https://tu-cdn.com/living.jpg",
"error": "el host del origen no existe (DNS no resuelve) [ENOTFOUND]", "ok": false }
]
Os motivos mais comuns:
| Motivo | O que verificar |
|---|---|
el host del origen no existe (DNS no resuelve) | A URL está escrita errada, ou o domínio não existe mais |
el origen rechazó la conexión | Seu servidor não aceitou a conexão |
HTTP 403 | Seu CDN nos bloqueou, ou o arquivo não está lá — veja abaixo |
HTTP 404 | A imagem não está nessa URL |
el origen no respondió en 15s | Lenta demais |
el certificado del origen está vencido | Problema de HTTPS do seu lado |
Um HTTP 403 do seu próprio bucket S3 quase sempre significa que o arquivo NÃO ESTÁ LÁ. Se o
bucket não expõe a listagem — o normal — o S3 responde 403 em vez de 404 para não revelar quais
chaves existem. Então, antes de verificar permissões, confirme que a URL aponta para um arquivo que
continua lá.
Se der partial, o imóvel ficou salvo mesmo assim, com as imagens que conseguimos baixar. Você
corrige as URLs que falharam e tenta de novo; não precisa cadastrar outra vez.
O cadastro na sua conta Mapaprop
Se você é cliente da Mapaprop e gerou o seu token pelo app (Mapaprop > App e Token), esta mesma chamada faz algo a mais: a propriedade é cadastrada sozinha na sua conta, como se você a tivesse carregado pelo app. Não há nada a pedir.
Acontece quando termina a ingestão das imagens, não no 201: uma propriedade chega à sua conta
com as fotos já carregadas. Por isso o bloco mapaprop da resposta costuma dizer pending.
{ "mapaprop": { "state": "synced", "propertyId": 2619527, "branchId": 1, "message": "…" } }
state | o que aconteceu | o que fazer |
|---|---|---|
pending | ainda não rodou: a ingestão não terminou | esperar |
synced | a propriedade existe na sua conta, com o propertyId da Mapaprop | nada |
rejected | algo do objeto não pôde ser guardado. O bloco nomeia o campo | corrigir com o PUT e tentar de novo |
blocked | a conta não está em condições | escreva para nós |
exhausted | as tentativas automáticas se esgotaram | tentar de novo |
O estado é consultado no GET da propriedade, que traz o
mesmo bloco já resolvido.
Cadastrada não é publicada. synced significa que a propriedade existe na sua conta;
publicá-la é uma decisão sua, com
PUT …/publication/mapaprop.
Se o seu token não saiu de uma conta Mapaprop —o caso de um integrador que publica para clientes que não são clientes nossos— o bloco não viaja e não há cadastro: as suas propriedades vivem só no PropertyAPI. Tudo isso está explicado em Mapaprop.
Tentar as imagens de novo
POST https://property-api.mapaprop.com/property-v1/properties/{paId}/assets
Tenta de novo apenas as que faltam: as que já estão nos nossos servidores não são tocadas nem baixadas
novamente. Responde 202 com o estado novo.
Serve quando o GET devolveu partial e você já corrigiu o problema do seu lado.
Consultar e excluir
GET /properties— um imóvel pelo seupaId, ou a listaDELETE /properties/{paId}— excluir. Não dá baixa nos seus anúncios nos portais
Modificar
PUT /properties/{paId}— substituição total: você envia o objeto completo e devolvemos umdiffdo que mudou, com os campos esvaziados listados à parte
Erros
| Código | Quando |
|---|---|
400 canonical_missing | Falta canonical no corpo |
400 account_required | Falta customer no objeto |
400 invalid_body | O corpo não é um JSON válido |
400 body_missing | Você não enviou corpo |
401 | Token ausente, vencido ou inválido |
404 | Esse paId não existe |
409 | Você já tem um imóvel com esse code — veja abaixo |
409 | images_processing — o imóvel está processando suas imagens. Veja abaixo |
501 | PUT: ainda não disponível |
O 409 por code repetido
O code é único por conta. É o código com o qual você identifica o imóvel no seu sistema, então não
pode haver dois imóveis seus com o mesmo.
{
"error": "code_already_exists",
"detail": "Ya tenés una propiedad con el código \"CMT-0014\". …",
"code": "CMT-0014",
"paId": "01M41AQNXYG4W4SEEEEPHEDNX4"
}
Devolvemos o paId do que já existe, que é o que você precisa para agir:
- quer atualizá-lo? →
PUT /property-v1/properties/{paId}com essepaId - é outro imóvel? → envie outro
code
Duas coisas que vale saber:
- É por conta, não global. Outro integrador pode usar o mesmo código sem problema: é o código do seu sistema.
- O código de um imóvel que você excluiu pode ser reutilizado. Só contam os ativos.
Se você vinha repostando todo o seu inventário a cada vez, antes isso criava duplicados e agora
vai receber 409. É isso que diz quais imóveis você já tinha: com o paId da resposta, o repost
vira um PUT.
O 409 por imagens em processamento
{
"status": 409,
"error": "images_processing",
"detail": "La propiedad está procesando sus imágenes. Procesando 2 de 4 imágenes. No se puede modificar ni publicar hasta que terminen. El estado está en GET /property-v1/properties/{paId}."
}
Não é um erro da sua requisição: é que ainda não terminamos. Você consulta o GET de novo e tenta
quando estiver em ready ou partial.
Se um download travar, o bloqueio se libera sozinho depois de um tempo, e aí você pode tentar as imagens de novo ou excluir o imóvel.
Como usar
- Você monta o objeto — os campos
- Testa com
/properties/verifyaté não restar nenhumblocker POST /properties→ guarde opaId- Consulta o
GETatéimages.statusdeixar de serprocessing - Se ficou
partial, corrige as URLs e chama/assets