Conectar com um link
Alguns portais não entregam uma credencial da conta do seu cliente. A imobiliária precisa entrar no portal e autorizar ela mesma, e a autorização fica guardada do lado do portal.
Para esses casos você solicita um link de conexão, envia ao seu cliente, e ele conclui a etapa em uma página nossa. Quando termina, a conexão fica registrada e você pode publicar em nome dele.
| Método | Rota | Quem chama |
|---|---|---|
POST | /property-v1/connect-links | Você, com o seu token |
GET | /property-v1/connect-links/{token} | A página que o seu cliente vê |
POST | /property-v1/connect-links/{token}/confirm | A página que o seu cliente vê |
Os dois últimos são públicos: quem os usa é a página, não a sua aplicação. Estão documentados para que você entenda o fluxo, não para que você os chame.
Estes endpoints estão em desenvolvimento. Escreva para dev@mapaprop.com se a sua integração precisar deles.
Quando usar este caminho e quando não
| Portal | Como conectar |
|---|---|
Zonaprop (zonapropapi) | Aqui. Não emite credencial por conta |
| Argenprop, Cabaprop, MercadoLibre | Conexões com portais — você obtém o token e o armazena |
Hoje somente o Zonaprop usa este fluxo. Solicitar um link para outro portal devolve 400.
Antes de começar: declarar o seu cliente
O link é emitido para uma ficha de cliente já declarada. Se você não a criou, recebe 409.
Isso acontece porque o código com que o seu cliente se identifica perante o portal é atribuído por nós ao criar a ficha (MAPAPROP-PA-000123). O seu cliente não precisa ter nada prévio no portal além da conta dele.
Veja Clientes.
1. Solicitar o link
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
portal | string | sim | Hoje somente zonapropapi |
clientRef | string | sim* | O seu id de cliente. *Pode ser enviado pelo cabeçalho x-client-ref |
curl -X POST https://property-api.mapaprop.com/property-v1/connect-links \
-H "Authorization: Bearer <SEU_TOKEN>" \
-H "x-client-ref: cliente-42" \
-H "Content-Type: application/json" \
-d '{ "portal": "zonapropapi" }'
Resposta 201:
{
"token": "x-_qM7tYl3TnjxIyxTCmX2Y6dfuD1uiSYO8VX3M3jZE",
"portal": "zonapropapi",
"expiresAt": "2026-10-08T17:51:44.000Z",
"url": "https://www.mapaprop.com/property-api/connect/zonapropapi/x-_qM7tYl3Tnjx..."
}
Use a url exatamente como vem. Não a monte por conta própria: se mudarmos a página de lugar, os links que você já enviou deixariam de funcionar.
O link vale uma única vez e dura 7 dias. Quando o seu cliente conclui a conexão, o link fica consumido. Para reconectar — por exemplo, se ele se desconectou — solicite um novo.
Requer o escopo property-api-create.
2. Envie ao seu cliente
Por e-mail, pelo seu painel, como preferir. A página mostra a ele o nome da imobiliária para que confirme que está conectando a conta correta, e explica que vai entrar com as credenciais do portal — não com as do Mapaprop.
O que acontece ali: o seu cliente autoriza no portal, e a página pergunta ao portal se a autorização ficou registrada antes de dar a conexão como concluída. Não basta o portal dizer que sim na tela.
3. Saber que terminou
Nós não avisamos. Quando o seu cliente concluir a etapa, consulte o estado:
curl https://property-api.mapaprop.com/connections/zonapropapi \
-H "Authorization: Bearer <SEU_TOKEN>" \
-H "x-client-ref: cliente-42"
status: "active" significa conectado. Essa chamada não consome cota do portal: lê o nosso registro.
O botão da sua aplicação
Com isso você pode desenhar um único botão que sirva para conectar e para desconectar:
| Etapa | Chamada | Consome cota do portal? |
|---|---|---|
| Decidir qual botão mostrar | GET /connections/{portal} | não |
| Clique em Conectar | POST /property-v1/connect-links → abra a url | não |
| O seu cliente autoriza | — | sim, 1 |
| Clique em Desconectar | DELETE /connections/{portal} | sim, 1 |
status: "active" → mostre Desconectar. revoked ou 404 → mostre Conectar.
Olhe o status, não se a conexão existe. GET /connections devolve também as conexões revogadas: mantemos o registro para permitir a reconexão. Se o seu código fizer if (connections.length > 0), vai dar como conectado um cliente que se desconectou.
Solicite o link quando o seu cliente clicar no botão, não ao desenhá-lo. Se você o solicitar a cada carregamento de tela, gera links que ninguém usa.
No Zonaprop, além disso: cota mensal e limites.
Respostas de erro
| Código | Quando | O que fazer |
|---|---|---|
400 | O portal não aceita este fluxo | Hoje somente zonapropapi |
409 | Você não declarou a ficha do cliente | Crie-a com POST /property-v1/customers |
404 | O link não existe | Verifique se está completo |
410 | O link expirou (7 dias) | Solicite um novo |
409 not_authorized_yet | O seu cliente ainda não concluiu a autorização | Peça que ele termine a etapa no portal |
O que o seu cliente vê
A página é nossa, não leva a sua marca nem a do Mapaprop além de um rodapé, e não tem navegação: não o convida a sair para lugar nenhum. Mostra o nome da imobiliária, explica o que ele está autorizando, e abre a janela do portal.
Se terminar corretamente, avisa que ele pode fechar. Se o portal ainda não registrou a autorização, informa isso e permite tentar de novo.
Não pedimos as credenciais do portal em momento algum: ele as digita no site do próprio portal, na janela dele.