BETA

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.

CampoO que é
addedURLs que não estavam antes: são as que baixamos
removedURLs que já não estão no objeto
unchangedAs que continuam. Não são baixadas de novo
reorderedAs 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 objetoO que acontece
não vemas 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 objetoO que acontece
não vemas 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ódigoQuando
400 canonical_missingFalta canonical no corpo
401Token ausente, vencido ou inválido
403 missing_scopeFalta o escopo property-api-update
404Esse paId não existe, ou está excluído
409Outro imóvel seu já usa esse code — o código é único por conta. Devolvemos o paId do que o tem
409images_processing — o imóvel está processando suas imagens
409registration_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