Publicar e despublicar um empreendimento

Um empreendimento imobiliário é publicado pelo seu próprio recurso, não pelo recurso dos imóveis:

PUT    /property-v1/developments/{paId}/publication/{portal}
DELETE /property-v1/developments/{paId}/publication/{portal}

Mesmo scope que publicar um imóvel ({portal}:publish), mesmo paId — o do empreendimento.

Se você pedir um empreendimento em um portal que ainda não o suporta, respondemos 501 nomeando-o — não um erro genérico. Um portal pode estar disponível para anúncios avulsos e ainda não para empreendimentos.

Isto não muda como se cria um empreendimento: ele continua sendo cadastrado com POST /property-v1/properties e o seu grupo development dentro. O que tem recurso próprio é a publicação.

1. Uma chamada, o empreendimento inteiro

Quando você publica um empreendimento, as suas unidades vão na mesma chamada. Não é necessário publicá-las uma por uma, e é melhor não fazer isso: o portal recebe o anúncio pai com as suas unidades dentro.

curl -X PUT "https://property-api.mapaprop.com/property-v1/developments/01M3Z4MF6S817S9V8QADXFFXN3/publication/zonapropapi" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: $CLIENT_REF" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "DESARROLLOS_DESTACADO" }'

Por que isso importa: o portal tem um limite de chamadas

O Zonaprop permite 1.500 chamadas por mês e por imobiliária, e esse limite é compartilhado entre publicar, consultar status e buscar contatos. Para um empreendimento de 48 unidades a diferença é esta:

É por isso que o recurso existe: percorrer as unidades gasta o seu orçamento do mês em um único empreendimento.

2. O que respondemos: unidade por unidade

O portal nos responde com uma entrada por anúncio —o pai e cada unidade— e nós repassamos isso a você de forma resumida. É isto o que mais vale a pena olhar:

{
  "status": "published",
  "portal": "zonaprop",
  "development": {
    "total": 48,
    "published": 45,
    "withError": 3,
    "codesWithError": ["TORRE-4B", "TORRE-5A", "TORRE-PH"]
  },
  "quota": { "remaining": 1432, "limit": 1500 }
}

Uma publicação parcial não é reportada a você como sucesso. Se o portal aceita o pai e rejeita três unidades, withError é 3 e dizemos quais pelo código. Antes isso saía como publicado, e a única forma de descobrir era olhar o anúncio.

Os codesWithError são os seus códigos (o code que você enviou, ou o paId), não ids do portal.

Os anúncios que o portal aceita "com observações"

O portal pode aceitar uma unidade e ainda dizer algo — por exemplo que um dado veio vazio e ele colocou 0. Isso não é um erro: a unidade foi publicada. Repassamos a você de todo modo, porque geralmente é a pista de que falta um dado seu.

3. Com mais de 15 unidades, o portal processa em diferido

Se o empreendimento tem 16 unidades ou mais, o Zonaprop não o processa na hora: ele confirma o recebimento e continua trabalhando. Nesse caso respondemos:

{ "status": "received", "processing": "async" }

received não é published. Significa que o portal recebeu, não que já esteja no ar. Não guarde como publicado até confirmar.

4. Despublicar

curl -X DELETE "https://property-api.mapaprop.com/property-v1/developments/01M3Z4MF6S817S9V8QADXFFXN3/publication/zonapropapi" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: $CLIENT_REF"

Despublica o empreendimento e as suas unidades, em uma chamada. Igual a um imóvel:

• Não apaga nada: o empreendimento continua no seu inventário e você pode publicá-lo novamente.
• É idempotente: se já não estava publicado, respondemos 200 de todo modo. Você pode tentar de novo sem preocupação.
• E também dizemos quantos anúncios saíram do ar, com o mesmo bloco development — com uma diferença de nome, porque mede outra coisa:

{ "status": "unpublished",
  "development": { "total": 48, "unpublished": 48, "withError": 0, "codesWithError": [] } }

5. Se você usar o recurso errado, nós avisamos

Um empreendimento pelo recurso dos imóveis —ou um imóvel pelo recurso dos empreendimentos— é um 400, e a mensagem diz a URL exata:

{
  "error": "recurso_incorrecto",
  "detail": "Ese objeto es un DESARROLLO inmobiliario (tiene el grupo `development`). Usá `/property-v1/developments/{paId}/publication/{portal}`.",
  "expected": "developments",
  "received": "properties"
}

Não gastamos uma chamada do portal para dizer isso: a verificação acontece antes.

Por que existem os dois recursos: o portal também os tem separados, com formatos diferentes. Se enviássemos um empreendimento pelo caminho de um anúncio avulso, ele seria publicado sem as suas unidades.

6. Antes de publicar no Zonaprop

Um empreendimento também precisa saber se é horizontal ou vertical. Se os seus campos já dizem, nós deduzimos; se não, pedimos a você.

O objeto do empreendimento — está explicado na sua §4, com os dois casos.

7. Códigos de resposta

8. Relacionado

O objeto do empreendimento — como se declara e as regras das unidades

Verificar antes de cadastrar — testar sem publicar nada

developmentStats — os números calculados das suas unidades

Publicar um imóvel — o recurso dos anúncios avulsos