DEVELOPING

Os estados que viajam com a propriedade

Há duas coisas distintas que o objeto pode declarar, e vale a pena não confundi-las:

Eixo	O que diz	Campos
O estado da OPERAÇÃO	a operação fechou: foi reservada, vendida, alugada	`reserved` · `sold` · `rented`
O estado da PUBLICAÇÃO	o anúncio não aparece, mesmo que a operação siga aberta	`suspended`

Os dois viajam dentro do objeto e são aplicados quando você publica. Não há um método separado.

{ "code": "CMT-0014", "type": 1, "operation": 1, "sold": true }

O alcance desta página são esses dois eixos. Se no futuro aparecer um terceiro, ele vai ter a sua própria seção aqui — não se mistura com estes.

O estado da OPERAÇÃO

Campo	O que diz
`reserved`	A operação está reservada
`sold`	Fechou como venda
`rented`	Fechou como aluguel

🔴 Não dizem que a propriedade está ocupada: dizem que a operação fechou. É a distinção que governa as duas regras abaixo.

Regra 1 · Um ou nenhum, nunca dois

Uma propriedade tem UM estado ou nenhum — contando também suspended. Se você enviar dois ligados, o objeto é rejeitado no verificador e na criação, antes de publicar nada.

{ "field": "operationStatus",
  "rule": "exclusive",
  "value": ["reserved", "sold"],
  "detail": "una propiedad tiene UN estado o ninguno: vinieron 2 prendidos (reserved, sold). Dejá sólo el que corresponde y apagá el resto — si la propiedad se reservó y después se vendió, el estado es `sold` y `reserved` va en false." }

O caso mais frequente: foi reservada, depois vendida, e o sistema de origem deixou reserved ligado. O estado correto é sold, e reserved vai em false.

Regra 2 · O estado tem de ser COERENTE com a operação

Uma venda não pode fechar um anúncio de aluguel, nem o contrário. Se operation é um aluguel, sold é rejeitado; se é uma venda, rented é rejeitado.

{ "field": "operationStatus",
  "rule": "incoherent",
  "value": { "sold": true, "operation": 2 },
  "detail": "`sold` significa que la operación CERRÓ, y esta propiedad es de Alquiler: una venta no puede cerrar un aviso de Alquiler. `sold` cierra una venta o una permuta. Si lo que querés decir es otra cosa, revisá `operation`." }

`operation`	Fecha com
`1` Venda · `4` Permuta	`sold`
`2` Aluguel · `3` Aluguel Temporário	`rented`

reserved e suspended são compatíveis com qualquer operação: reservar e suspender valem para tudo.

E em 5 Traspasse, 6 Compartilhar e 7 Leilão não validamos nada: a família deles é ambígua e preferimos não rejeitá-lo por uma interpretação nossa.

Se você enviar dois estados ligados, recebe UM problema, não dois. Com dois ligados não há como saber qual deveria ser coerente, então dizemos a causa (exclusive) e não a consequência.

O estado da PUBLICAÇÃO

Campo	O que diz
`suspended`	O anúncio não aparece, mesmo que a operação siga aberta

É outro eixo: não diz nada da operação. Um anúncio suspenso pode voltar a aparecer sem que tenha acontecido nada com a venda ou o aluguel.

⚠️ Mas compartilha a regra 1: se você declarar suspended, não pode declarar também sold.

Quando são aplicados

Ao publicar, dentro do mesmo PUT …/publication/{portal}. Não há uma chamada extra para você fazer.

É uma chamada extra da cota do seu cliente, do nosso lado: escrever o estado é uma operação separada contra o portal. Uma propriedade sem estado declarado não a gasta.

E são aplicados depois de o anúncio existir: o estado é escrito sobre um anúncio publicado.

O que você recebe

{ "status": "published", "portal": "argenpropapi", "paId": "01M41AQ…",
  "operationStatus": {
    "field": "sold", "axis": "commercial",
    "applied": true, "portalState": "vendido", "reason": null } }

Campo	O que é
`field`	O estado que o seu objeto declarou
`axis`	`commercial` = o eixo da operação · `operational` = o da publicação
`applied`	Se o portal o aceitou
`portalState`	Como o portal o chama
`reason`	Por que não foi aplicado, se `applied` for `false`

O campo só aparece se o seu objeto declarou um estado. Caso contrário não vem — não vem como null.

applied: false NÃO significa que a publicação falhou. O anúncio foi publicado; o que não foi escrito é o estado, e reason diz por quê:

`reason`	O que aconteceu	O que fazer
`portal_sin_soporte`	esse portal não tem esse estado	nada: é assim, e a tabela está abaixo
um código do portal	o portal rejeitou a mudança	leia-o: é o mesmo tipo de código da publicação

🔴 Declarar um estado OCULTA o anúncio

No Argenprop, qualquer um dos quatro estados deixa o anúncio não visível no portal. Isso é correto —uma propriedade vendida não deveria aparecer como disponível— mas vale saber: você publica com sold: true, recebe 200, e o anúncio não aparece.

O que você declara	Como fica no portal	Aparece
nada	`VIGENTE`	sim
`reserved`	`RESERVADO`	não
`sold`	`VENDIDO`	não
`rented`	`ALQUILADO`	não
`suspended`	`SUSPENDIDO`	não

E o que importa para a sua integração: nós continuamos contando como publicado, os quatro.

"remoteStatus": "published",
"remote": { "estadoPortal": "VENDIDO", "visible": false }

O estado no portal diz isso com o nome do próprio portal, então você pode distinguir "foi vendida" de "caiu". Se o tratássemos como não publicado, cada nova tentativa sua tentaria republicar um anúncio que está perfeitamente bem.

Como voltar atrás

Nenhum estado é definitivo. Publique de novo com os quatro campos desligados e o anúncio volta a aparecer — inclusive a partir de sold ou rented.

{ "code": "CMT-0014", "type": 1, "operation": 1, "sold": false }

Não há um método separado para isso: é o mesmo PUT …/publication/{portal} que faz.

O que cada portal suporta

Portal	O estado da operação	O estado da publicação
Argenprop	✅	✅
Zonaprop	—	—
Cabaprop	—	—
MercadoLibre	—	—

Um portal que não suporta isso não é um erro. Você publica do mesmo jeito, o anúncio sai, e a resposta diz que o estado não viajou:

"operationStatus": { "field": "sold", "applied": false, "reason": "portal_sin_soporte" }

Assim você pode enviar o mesmo objeto aos quatro portais sem ramificar o seu código.

Hoje somente o Argenprop suporta o eixo da operação, e é o único dos quatro que o tem. Se você precisar disso em outro portal, escreva para dev@mapaprop.com: isso nos ajuda a priorizar.

Os empreendimentos não levam estado

Um empreendimento são muitos anúncios, portanto o estado não se aplica ali. Se uma unidade é vendida, o que se aplica é o estado dessa unidade.

Relacionado

Publicar em um portal — o PUT onde isso é aplicado
Consultar o estado no portal — o que o portal diz do anúncio
A chave publication — os dados por portal
Verificar antes — onde as duas regras são rejeitadas