BETA

Publicar um empreendimento

Um empreendimento é um edifício ou um bairro com unidades dentro. Se você já leu publicar um anúncio, o fluxo é o mesmo com uma diferença que muda toda a ordem.

As unidades são cadastradas ANTES do empreendimento que as agrupa. Não é uma recomendação de estilo: o empreendimento as referencia, então se elas ainda não existem, não há nada para referenciar. É o erro número um deste fluxo e não se corrige para a frente — é preciso voltar atrás.

O caminho

1 · cada unidade, separadamente       POST /properties             ← PRIMEIRO. São imóveis normais
2 · o empreendimento que as agrupa    POST /properties             ← referencia as do passo 1
3 · verificar                         POST /properties/verify      gratuito
4 · publicar                          PUT  …/publication/{portal}  ← e aqui muda conforme o portal
5 · estado e baixa                    igual a um anúncio

O passo 4 não é igual nos dois portais, e é a diferença que mais muda o seu código.

ZonapropArgenprop
As unidadesviajam dentro da publicação do empreendimentojá precisam estar publicadas: o empreendimento as agrupa
Quantas chamadas você fazumauma por unidade, e depois a do empreendimento

Na Argenprop cada unidade é um anúncio do portal por direito próprio, e o empreendimento as agrupa referenciando-as. Um empreendimento não pode agrupar uma unidade cujo anúncio ainda não existe.

1 · As unidades primeiro

Cada unidade é um imóvel normal: é cadastrada com o mesmo POST /properties que qualquer outro.

⚠️ Uma unidade não é um empreendimento. Tem o seu próprio tipo de imóvel —apartamento, casa, lote— e só herda o do empreendimento se você errar ao montá-la. Se acontecer, a tentativa de publicar marca isso unidade por unidade, nomeando o tipo que o portal não reconhece.

Guarde o código ou o identificador de cada uma: é com isso que o empreendimento vai referenciá-las.

Na Argenprop, além disso, cada unidade precisa ser publicada. Cadastrá-la aqui a cria do nosso lado; o empreendimento só pode agrupar unidades que já tenham o seu anúncio no portal. É o passo 4.

2 · O empreendimento

Outro POST /properties, com o objeto de empreendimento e a lista das unidades do passo 1.

Duas coisas que convém saber antes:

  • Uma unidade pertence a um só empreendimento. Se já faz parte de outro, dizemos isso nomeando qual — não a reatribuímos por conta própria.
  • Um empreendimento pode ser guardado sem unidades e recebê-las depois. O que não se pode é publicá-lo vazio.

Se você é cliente Mapaprop e gerou o seu token a partir do app, este mesmo passo faz algo a mais: o empreendimento entra sozinho na sua conta Mapaprop quando as fotos terminam de ser processadas, e as unidades ficam vinculadas a ele. Fica cadastrado, não publicado — publicá-lo continua sendo o passo 4.

O empreendimento não espera pelas unidades que ainda não chegaram. Vincula as que já estão lá e devolve as outras em units.pending, com o motivo de cada uma: isso é normal quando você cadastra as unidades e o empreendimento um logo depois do outro, porque cada unidade aguarda o carregamento das suas fotos. Para fechá-las, tente o cadastro novamente — são vinculadas apenas as que faltam.

O detalhe do bloco mapaprop está em Mapaprop.

3 · Verificar (gratuito, e aqui rende mais do que nunca)

O verificador revisa o empreendimento e cada unidade, e não custa nada. Na Zonaprop, onde publicar é uma única chamada, um problema numa única unidade pode travar tudo; na Argenprop não trava o empreendimento, mas deixa uma unidade de fora. Nos dois casos saber antes é gratuito e saber depois custa cota.

As unidades têm que existir ANTES de verificar. O verificador não inventa o que não está: se o empreendimento referencia uma unidade que você ainda não cadastrou, ele diz isso como not_found com o código que não encontrou — e daí conclui, com razão, que falta unidades ao empreendimento.

Então a ordem do passo 1 também vale para verificar, não só para publicar.

4 · Publicar

PUT …/publication/{portal} com o empreendimento. O que acontece com as unidades depende do portal, e é a única coisa deste fluxo que não é igual nos dois.

Na Zonaprop: uma chamada, o pai e as unidades

As unidades viajam dentro dele: você não as publica uma por uma.

A cotaé uma chamada, não uma por unidade. Um empreendimento de 40 unidades custa o mesmo que um de 2

Um empreendimento grande na Zonaprop continua sendo uma chamada

Nada do que vem abaixo se aplica a ele: as unidades viajam dentro, então o tamanho não muda o número de chamadas.

Na Argenprop: cada unidade primeiro, o empreendimento depois

Cada unidade é um anúncio do portal por direito próprio, então você a publica como publicaria qualquer anúncio —o mesmo PUT …/publication/argenpropapi sobre o imóvel— e só então publica o empreendimento, que as agrupa.

para cada unidade   PUT /properties/{paId}/publication/argenpropapi
e no final          PUT /developments/{paId}/publication/argenpropapi
A cotauma chamada por unidade, mais a do empreendimento. Um empreendimento de 40 unidades custa 41
A ordemse você publicar o empreendimento antes, as unidades que ainda não têm anúncio voltam como falha, nomeando qual — o empreendimento fica publicado
Repetir é seguroagrupar uma unidade que já está agrupada não a duplica nem custa a mais

Por que não as publicamos por dentro. Avaliamos e não cabe: publicar 30 anúncios dentro de uma única chamada sua demora mais do que uma requisição pode durar, e o modo de falha seria o pior —algumas publicadas, outras não, e você sem saber o que ficou feito—. Fazendo uma por uma, cada unidade tem o seu próprio orçamento de tempo e o fluxo escala sem teto.

E nos dois, o plano

O planoos empreendimentos consomem um plano próprio, diferente do de um anúncio solto. Qual é e quantos o seu cliente tem você vê com a consulta de planos

Dependendo de quantas unidades tiver, o portal pode responder de duas formas: confirmando cada anúncio, ou confirmando só o empreendimento e processando as unidades depois. O que devolvemos está explicado em a resposta do empreendimento; o modo não é você quem escolhe.

Como sei que publicou tudo o que enviei?

Não conte na mão. Há dois momentos para saber, e o primeiro é o que vale a pena usar:

Antes de publicar, o verificador já lista o que vamos enviar diferente de como você declarou e o que não vamos enviar, com o motivo de cada coisa. É de graça, e é o momento útil: você corrige o objeto e verifica de novo sem gastar cota.

Depois de publicar, a resposta traz o que o portal aceitou e mantém essa mesma lista. Se uma unidade não viajou, ali está dito qual e por quê.

Um total que não coincide com o que você enviou não é, por si só, um erro. Pode ser uma unidade que decidimos não publicar — a seção a seguir — ou o modo em que o portal processa depois e ainda não terminou. Leia o motivo antes de tentar de novo: tentar de novo custa cota e quase nunca é a resposta.

🔴 Na Argenprop, um empreendimento grande se publica REPETINDO

Adotar as unidades uma a uma não cabe sempre numa só chamada —uma chamada tem um tempo máximo— então o publish de um empreendimento grande é naturalmente iterativo:

você publica o empreendimento  →  adota as que cabem, e diz quantas ficaram
    você repete                 →  retoma de onde parou
        você repete             →  …
            até não ficar nenhuma
Repetir é seguroadotam-se só as que faltam. Nada é duplicado e o empreendimento não é recriado
Não é um erroo que não cabeu volta identificado como não tentado, diferente de falhou
Quanto custacada volta são algumas chamadas da cota do seu cliente. Não repita em loop sem olhar: vá lendo quantas faltam
Quando terminouquando não ficam unidades sem adotar

Quantas voltas: depende de quão rápido o portal está respondendo naquele dia, e varia bastante. Um empreendimento de poucas unidades costuma fechar numa; um de 50 pode precisar da ordem de 15 a 20.

Se você está carregando um empreendimento grande pela primeira vez, deixe o loop rodando com uma pausa entre voltas e olhe o número de unidades que faltam: é o único indicador que você precisa.

⚠️ Isto é só da carga inicial. Depois, mudar o preço de uma unidade ou adicionar uma só é uma chamada: comparamos com o que o portal já tem e tocamos apenas a diferença.

Uma unidade vendida: marque, não retire

O empreendimento é o inventário completo, não a oferta do momento. Se você vendeu 3 de 100 unidades, as 100 continuam fazendo parte do empreendimento: você marca essas 3 como vendidas e pronto. Não as retire do objeto.

Por que importa: o tamanho do empreendimento é um dado do edifício, e os números que calculamos — quantas restam, quanto foi comercializado — só fazem sentido se estiverem todas. Um empreendimento que passou de 100 para 97 unidades perdeu a informação de que vendeu 3.

E depois cada portal decide o que faz com elas. Não é igual em todos: há portais que não têm como mostrar uma unidade indisponível, então a mostrariam como se estivesse à venda. Nesses, não a enviamos — e dizemos na resposta, qual e por quê. O total do empreendimento continua sendo o real.

Se a unidade já estava publicada, marcá-la não dá baixa. Deixar de enviá-la mantém o anúncio fora das próximas atualizações, mas o anúncio que já está no ar continua no ar: dê baixa na publicação dele como em qualquer anúncio. São duas coisas diferentes e vale fazer as duas.

5 · Estado, atualizar e baixa

Igual a um anúncio: publicar de novo atualiza, a baixa é idempotente, e o estado se lê gratuitamente do nosso lado ou pagando uma chamada ao portal.

Existe uma janela entre publicar e poder publicar de novo, e aqui é a mais longa do fluxo. Com muitas unidades o portal não termina na hora: confirma o recebimento e continua trabalhando. Enquanto isso, não aceita uma segunda escrita do mesmo empreendimento — então uma atualização enviada em seguida é rejeitada.

Não é uma falha e você não perdeu o empreendimento: o primeiro segue seu curso. Respondemos como algo temporário, com quantos segundos convém esperar.

⚠️ A decisão de desenho que isso pede de você: se o seu fluxo publica e corrige na mesma rajada, você tem dois caminhos e os dois são válidos — esperar e tentar de novo, ou perguntar ao portal se ele já terminou antes de reescrever. Tratar como um erro definitivo é o único que dá errado. O contrato da resposta do publish está em publicar; o da consulta, em a consulta de estado.

Perguntar gasta uma chamada da cota do seu cliente; esperar é grátis.

Com muitas unidades, perguntar não te serve para isso.

Quando o empreendimento é grande o portal o processa de forma assíncrona, e termina com o anúncio principal muito antes de terminar com o lote. Então se você perguntar, ele vai dizer que aquele anúncio está pronto enquanto as unidades seguem na fila — e a próxima escrita continua sendo rejeitada.

UnidadesQuanto levou para aceitar a escrita seguinte
4~1 minuto
20mais de 8 minutos (e o anúncio principal se declarou pronto aos 3)
298 a 10 minutos

⇒ Em um empreendimento grande, espere e tente de novo. O número que devolvemos na resposta já leva em conta o tamanho: para um lote sugerimos dez minutos, e para um anúncio avulso ou um empreendimento pequeno, um.

Continua sendo uma sugestão nossa, não um dado do portal: não existe um campo que diga o momento exato — o portal não o envia. Se ao vencer voltar a mesma recusa, não está quebrado: é que ainda está processando, e tentar de novo é seguro.

A janela também afeta a BAIXA, e aí surpreende mais. Se você dá baixa enquanto o portal está processando, a baixa responde normalmente e o empreendimento pode voltar a ficar online quando o portal termina o trabalho que tinha pendente. Não é que a baixa falhou: a publicação anterior ainda estava em curso e se completou depois. O mesmo em dar baixa.

⚠️ O empreendimento e as unidades dele têm estados separados. Consulte o do empreendimento pelo empreendimento: perguntar por uma unidade como se fosse um anúncio solto não vai dizer o que você procura.

Os três erros de ordem, e como aparecem

Se você…Dizemos assim
manda o empreendimento antes das unidadesnão encontramos essas unidades, com o código que não existe
referencia uma unidade que já é de outro empreendimentonomeamos o empreendimento que a tem
deixa as unidades herdarem o tipo do empreendimentoa tentativa marca cada unidade com o tipo que o portal não aceita

Os três aparecem antes de chegar ao portal se você verificou. Se não verificou, aparecem depois de gastar a chamada.

Que portais suportam isso

Publicar empreendimentos não está disponível em todos os portais, e naqueles em que está, o seu cliente precisa ter contratado o produto correspondente — que é diferente do de anúncios soltos. A tabela está em Publicação; se o portal não suportar, a tentativa diz isso sem gastar cota.

Relacionado