BETA

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…" }
}

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…"
  },

  "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

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.

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 seu paId, ou a lista
DELETE /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 um diff do que mudou, com os campos esvaziados listados à parte

Erros

Código	Quando
`400`	Falta `canonical` no corpo, falta `customer` no objeto, ou o corpo não é um JSON válido
`401`	Token ausente, vencido ou inválido
`404`	Esse `paId` não existe
`409`	O imóvel está processando suas imagens — veja abaixo
`501`	`PUT`: ainda não disponível

O `409`

{
  "status": 409,
  "error": "La propiedad está procesando sus imágenes",
  "detail": "Procesando 2 de 4 imágenes. No se puede modificar ni publicar hasta que terminen."
}

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/verify até não restar nenhum blocker
POST /properties → guarde o paId
Consulta o GET até images.status deixar de ser processing
Se ficou partial, corrige as URLs e chama /assets