PUT /properties/{paId}
É SUBSTITUIÇÃO TOTAL: você envia o objeto completo, igual ao cadastro. O que não enviar fica esvaziado.
Por isso a resposta traz um diff, e os campos que foram esvaziados vão à parte em cleared.
Resource URL
PUT https://property-api.mapaprop.com/property-v1/properties/{paId}
Autenticação
Authorization: Bearer <seu token>. Requer o escopo property-api-update.
curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @propiedad.json
O corpo
O mesmo objeto do cadastro, completo, em canonical:
{
"canonical": { "…o objeto do imóvel, inteiro…" }
}
Os campos estão em O objeto JSON do imóvel.
Não é um PATCH. Enviar {"canonical": {"price": 230000}} não altera só o preço: apaga todo o
resto. Para alterar um campo, pegue o objeto que o GET
devolve, altere esse campo e envie o objeto inteiro.
A resposta
A resposta traz o clientRef, o mesmo que você enviou no envelope. Nós o devolvemos nos seis
caminhos (verify, cadastro, consulta, listagem, edição e exclusão) para que você possa cruzá-lo com a sua
base sem ter que lembrar com qual clientRef perguntou.
200 OK. É a resposta do cadastro — object,
portals, summary — mais o comprovante e o diff:
{
"paId": "01M3PTZ8YBMM5DSNW03WP8VD9E",
"updated": true,
"updatedAt": "2026-09-29T23:41:02.118Z",
"status": "active",
"diff": {
"property": {
"price": { "from": 245000, "to": 230000 },
"description": { "from": "Departamento de 2 ambientes en el corazón…(1240 ch)", "to": "…(1310 ch)" },
"toilettes": { "from": 2, "to": null }
},
"assets": { "added": 2, "removed": 1, "unchanged": 7, "reordered": false },
"cleared": ["toilettes"],
"changed": 6
},
"images": { "status": "processing", "total": 9, "processed": 7 }
}
diff.property — quais campos mudaram
Um por campo, com o valor anterior e o novo. O texto longo é resumido com o seu tamanho real
(…(1240 ch)) para a resposta continuar legível.
images e blueprint não aparecem aqui: têm o seu próprio bloco.
🔑 diff.cleared — o que foi esvaziado
A lista de campos que tinham valor e agora não têm. É a consequência da substituição total, colocada à parte para se ver de imediato.
Se cleared trouxer algo que você não queria esvaziar, envie o PUT de novo com esse campo incluído.
Nada foi publicado ainda.
diff.assets — as fotos
"assets": { "added": 2, "removed": 1, "unchanged": 7, "reordered": false }
São comparadas por URL, não por posição. Reordenar suas fotos sem alterá-las dá unchanged e
reordered: true — não conta como fotos novas.
| Campo | O que é |
|---|---|
added | URLs que não estavam antes: são as que baixamos |
removed | URLs que já não estão no objeto |
unchanged | As que continuam. Não são baixadas de novo |
reordered | As mesmas fotos em outra ordem. Importa: a primeira é a principal |
As imagens novas passam pelo mesmo ciclo
Se o PUT trouxer URLs novas, images.status volta a processing e o imóvel fica bloqueado enquanto as
baixamos — igual ao cadastro. As que já estavam hospedadas não são baixadas de novo.
O que o PUT muda na sua conta Mapaprop
Se o imóvel já estiver cadastrado na sua conta Mapaprop, o PUT propaga a alteração para lá: o
título, a descrição, os metros, o preço e seu histórico, os preços alternativos, os vídeos, a planta
e as fotos. É uma única chamada: não há endpoints separados para o preço ou para as fotos.
O seu objeto é a realidade completa do imóvel. O que você envia substitui o que está na conta —
inclusive se alguém editou à mão pelo Mapaprop. Se corrigiram o preço no aplicativo web e depois
você envia um PUT, fica o preço do seu objeto.
O mesmo vale para o estado comercial: se o seu objeto diz que o imóvel não está vendido, ele fica não vendido, mesmo que na conta constasse como vendido. O seu sistema é a fonte.
Duas coisas que o PUT não altera:
- A publicação. Se o imóvel estava publicado, continua publicado; se não estava, continua sem publicar. Publicar é uma ação separada.
- O que nós resolvemos: a zona e as URLs das fotos que já hospedamos.
Quanto tempo leva para aparecer na sua conta
O PUT responde assim que o imóvel é salvo; a alteração viaja para a conta Mapaprop depois.
Medido em produção: cerca de 8 segundos para uma alteração que não traz fotos novas.
Se o PUT traz fotos novas, primeiro nós as baixamos — images.status diz como está indo — e a
alteração chega à conta quando esse processamento termina.
Esses segundos são uma referência, não uma garantia: dependem de quantas fotos você envia. O
sinal que manda é o GET, não um relógio — se o bloco
mapaprop traz update com status: "pending", a alteração ainda está a caminho; se traz
status: "failed", não chegou e diz por quê.
Os empreendimentos: as unidades também são substituídas
Se o objeto for um empreendimento, a lista development.units manda como todo o resto:
units no seu objeto | O que acontece |
|---|---|
| não vem | as unidades vinculadas ficam como estão |
[] (lista vazia) | todas são desvinculadas |
[A, B] | ficam vinculadas exatamente essas duas |
Desvincular uma unidade não a apaga: continua sendo um imóvel seu, só deixa de pertencer ao empreendimento.
As fotos: ausente não é o mesmo que vazio
images no seu objeto | O que acontece |
|---|---|
| não vem | as fotos ficam como estão |
[] (lista vazia) | todas são apagadas |
[a, b] | ficam exatamente essas duas, nessa ordem |
As fotos novas são baixadas antes de chegar à conta, então a alteração aparece quando esse processamento termina. As que já estavam hospedadas não são baixadas de novo.
Você acabou de cadastrar o imóvel: espere o cadastro
Um PUT disparado nos segundos seguintes ao POST se cruza com o cadastro, que ainda está gravando
os preços e as fotos na conta. Nesse caso devolvemos 409 registration_in_progress com
retryAfterSeconds: tente o PUT novamente depois desses segundos.
{
"error": "registration_in_progress",
"detail": "La propiedad se está dando de alta en Mapaprop en este momento…",
"retryAfterSeconds": 8
}
Para evitar a nova tentativa, espere que o GET devolva o
bloco mapaprop com state: "synced" e accessories antes de enviar o PUT.
Erros
| Código | Quando |
|---|---|
400 canonical_missing | Falta canonical no corpo |
401 | Token ausente, vencido ou inválido |
403 missing_scope | Falta o escopo property-api-update |
404 | Esse paId não existe, ou está excluído |
409 | Outro imóvel seu já usa esse code — o código é único por conta. Devolvemos o paId do que o tem |
409 | images_processing — o imóvel está processando suas imagens |
409 | registration_in_progress — o cadastro no Mapaprop ainda está gravando. Tente novamente depois dos retryAfterSeconds |
Um PUT sobre um imóvel excluído devolve 404: não o traz de volta. Para tê-lo novamente,
cadastre-o outra vez — você vai receber um paId novo.
O que o PUT ainda NÃO faz
Não republica nos portais. Salva o imóvel e diz o que mudou, mas um anúncio já publicado em um portal não é atualizado sozinho. Isso chega com a etapa de publicação.
Relacionados
- POST /properties — o cadastro
- GET /properties — de onde você tira o objeto para modificar
- DELETE /properties/{paId} — excluir