Verificar e cadastrar um empreendimento

Não há endpoints novos. Um empreendimento é verificado com POST /property-v1/properties/verify e cadastrado com POST /property-v1/properties, igual a um imóvel. O que muda é o que validamos e o que devolvemos.

POST /property-v1/properties/verify     ← teste sem salvar nada
POST /property-v1/properties            ← o cadastro
PUT  /property-v1/properties/{paId}     ← editar (e carregar ou alterar as unidades)

1. Comece pelo verify. Sempre.

O verify não cria nada, não publica nada e não gasta cota de nenhum portal. Você envia o objeto e ele devolve exatamente o que aconteceria: quais dados chegaram corretamente, o que falta para cada portal, em que zona publicaríamos e como ficaria o anúncio.

Com um empreendimento isso vale mais do que com um imóvel avulso, porque há mais coisas que podem não fechar: as unidades precisam existir e estar livres, e o tipo de empreendimento é deduzido a partir dos campos que você envia.

curl -X POST https://property-api.mapaprop.com/property-v1/properties/verify \
  -H "Authorization: Bearer {seu-token}" \
  -H "x-client-ref: {seu-cliente}" \
  -H "Content-Type: application/json" \
  -d '{ "canonical": { … seu empreendimento … } }'

O verify mostra a mesma coisa que o POST enviaria. Não é uma versão reduzida nem uma aproximação: é o mesmo motor, com a escrita desligada.

2. A ordem que funciona

1. As unidades primeiro. POST /properties de cada uma, e guarde o paId.
2. O empreendimento depois, com os códigos das suas unidades em development.units.

Se você fizer ao contrário, as unidades ainda não existem e nós as reportamos como not_found — o empreendimento é salvo mesmo assim, mas não poderá ser publicado até que a lista resolva.

Você também pode fazer em duas etapas

Um empreendimento pode ser cadastrado sem unidades e recebê-las depois com PUT. Esse é o fluxo normal quando o projeto vai à venda antes de o mix de unidades estar fechado.

⚠️ O PUT substitui a lista inteira, não acrescenta: se o empreendimento tem 10 unidades e o PUT envia 3, ele fica com 3. Envie sempre a lista completa.

E isso convive com o limite de 100 da tabela abaixo, porque o que se conta são as unidades que entram e saem, não as que o empreendimento já tem. O detalhe, com exemplos, está em o limite: 100 unidades que MUDAM.

3. O que validamos a mais

Além de tudo o que já validamos em um imóvel, um empreendimento acrescenta:

O tipo. O grupo development exige type: 23. Com outro tipo devolvemos um erro de contrato em vez de escolher por conta própria: adivinhar qual dos dois você quis dizer é como uma base de dados fica suja.

Os seis campos do grupo, que são obrigatórios: totalBuildingArea, totalLandArea, totalGarages, minAmbiences, minRooms, minBathrooms. Se faltar um, nós o nomeamos pelo seu caminho no seu JSON (development.minRooms), não pelo nosso nome interno.

As unidades, uma a uma: que existam, que estejam ativas, que sejam do seu mesmo cliente, que não estejam já em outro empreendimento e que não formem um ciclo. As sete regras estão em o objeto do empreendimento.

O tipo de empreendimento. Se você declarar campos dos dois (casas e andares de prédio) devolvemos o conflito nomeando os campos de cada lado. Não escolhemos por você.

4. Um objeto com problemas é salvo mesmo assim

Isso surpreende, então vale dizer com clareza: se uma unidade não resolve, o POST devolve 201 e o empreendimento fica salvo, com os problemas listados.

Não é falta de rigor: o objeto é seu. Salvá-lo permite corrigir a unidade e tentar de novo sem reenviar tudo, e os problemas são o diagnóstico de por que ainda não é possível publicar — não uma recusa.

O que é bloqueante é publicar: um empreendimento não é publicado com unidades faltando.

As duas exceções, que são erro

5. O que devolvemos

A resposta tem a mesma forma que a de um imóvel, mais um bloco developmentStats com os números calculados das suas unidades: quantas existem, quantas estão disponíveis, a faixa de preços por moeda e a distribuição por tipologia.

Isso está em developmentStats, e é a parte que mais vale a pena ler: são dados que você não precisa calcular.

6. E depois

developmentStats — os números calculados, campo a campo

O objeto JSON do empreendimento — os campos e as regras das unidades

Publicar em um portal — com o objeto já verificado