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.
| Zonaprop | Argenprop | |
|---|---|---|
| As unidades | viajam dentro da publicação do empreendimento | já precisam estar publicadas: o empreendimento as agrupa |
| Quantas chamadas você faz | uma | uma 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 cota | uma chamada por unidade, mais a do empreendimento. Um empreendimento de 40 unidades custa 41 |
| A ordem | se 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 é seguro | agrupar 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 plano | os 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 é seguro | adotam-se só as que faltam. Nada é duplicado e o empreendimento não é recriado |
| Não é um erro | o que não cabeu volta identificado como não tentado, diferente de falhou |
| Quanto custa | cada volta são algumas chamadas da cota do seu cliente. Não repita em loop sem olhar: vá lendo quantas faltam |
| Quando terminou | quando 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.
| Unidades | Quanto levou para aceitar a escrita seguinte |
|---|---|
| 4 | ~1 minuto |
| 20 | mais de 8 minutos (e o anúncio principal se declarou pronto aos 3) |
| 29 | 8 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 unidades | não encontramos essas unidades, com o código que não existe |
| referencia uma unidade que já é de outro empreendimento | nomeamos o empreendimento que a tem |
| deixa as unidades herdarem o tipo do empreendimento | a 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
- Publicar um anúncio — o caso base
- O objeto do empreendimento · Verificar · A resposta
- Publicar um empreendimento — o endpoint e o contrato dele