Conectar com um link
Em alguns portais você não consegue obter a credencial da conta do seu cliente por conta própria. É a imobiliária que tem de executar essa etapa, e você não deveria precisar lidar com as credenciais dela no portal.
Para esses casos você solicita um link de conexão, envia-o ao seu cliente, e ele completa a etapa em uma página nossa. Quando ele 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ê |
As duas últimas são públicas: são usadas pela página, não pela sua aplicação. Estão documentadas para que você entenda o fluxo, não para que você as 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. O seu cliente autoriza no portal |
Argenprop (argenpropapi) | Aqui. O seu cliente digita a credencial de integração na nossa página |
| Cabaprop, MercadoLibre | Conexões com portais — você obtém o token e o armazena |
Solicitar um link para um portal que não está nesta lista retorna 400.
Os dois modos, e o que muda para você
A resposta do link traz um campo connectMode que informa como aquele portal se conecta:
authorize | credentials | |
|---|---|---|
| Portal | Zonaprop | Argenprop |
| O que o seu cliente faz | autoriza em uma janela do portal | digita usuário e senha do portal na nossa página |
| Quem vê a credencial | ninguém: o portal a pede no próprio site | ele a digita na nossa página; você não a vê |
Para a sua integração nada muda: você solicita o link do mesmo jeito, envia-o do mesmo jeito e consulta o status do mesmo jeito. A página se adapta ao portal por conta própria. O campo está documentado porque serve para você saber o que o seu cliente vai ver.
Antes de começar: declarar o seu cliente
O link é emitido para um registro de cliente já declarado. Se você não o criou, recebe 409.
Isso acontece porque o link aponta para uma imobiliária, e a identidade dela vem do registro — nunca do que a sua aplicação enviar.
Como ela fica identificada junto ao portal depende do portal: na Zonaprop o código é atribuído por nós ao criar o registro (MAPAPROP-PA-000123), e o seu cliente não precisa ter nada prévio além da conta; na Argenprop o identificador é emitido pelo portal e nós o lemos ao conectar.
Veja Clientes.
1. Solicitar o link
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
portal | string | sim | zonapropapi ou argenpropapi |
clientRef | string | sim* | O id do seu cliente. *Pode ser enviado pelo header x-client-ref |
curl -X POST https://property-api.mapaprop.com/property-v1/connect-links \
-H "Authorization: Bearer <TU_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 ela vem. Não a monte você mesmo: 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 completa a conexão, o link fica consumido. Para reconectar — por exemplo, se ele se desconectou — solicite um novo.
Requer o scope property-api-create.
2. Envie-o 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 o que ele está por fazer.
Nos dois modos a conexão só é considerada concluída quando o portal confirma. No authorize perguntamos ao portal se a autorização ficou registrada; no credentials fazemos o login no portal e lemos o perfil da conta. Não basta a tela dizer que deu certo.
3. Saber que terminou
Nós não avisamos. Quando o seu cliente completa a etapa, consulte o status:
curl https://property-api.mapaprop.com/connections/zonapropapi \
-H "Authorization: Bearer <TU_TOKEN>" \
-H "x-client-ref: cliente-42"
status: "active" significa conectado. Essa chamada não consome cota do portal: ela lê o nosso próprio registro.
O botão da sua aplicação
Com isso você pode desenhar um único botão que sirva tanto para conectar quanto 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} | depende do portal (veja abaixo) |
status: "active" → mostre Desconectar. revoked ou 404 → mostre Conectar.
O que o desconectar faz, exatamente
Desconectar são duas coisas, e acontecem nesta ordem: primeiro o portal, depois nós.
- Encerramos a permissão do lado do portal. A resposta informa isso em
remoteUnlink:"ok"foi encerrada ·"pending"não conseguimos e vale a pena tentar de novo ·"skipped"esse portal não precisa dessa etapa. - Revogamos a conexão do nosso lado, e isso acontece sempre — mesmo que a etapa 1 tenha falhado. Um portal que não responde não pode deixar você preso a uma integração que pediu encerrar.
| Portal | Consome cota do seu cliente? |
|---|---|
| Zonaprop | sim, 1 — é uma rota por imobiliária |
| Argenprop | não — o limite dele é por integração, não por conta |
O que nunca faz, em nenhum caso: dar baixa nos anúncios. Os anúncios foram publicados pelo seu
cliente com a conta dele no portal e continuam publicados. A resposta diz isso explicitamente em
externalListingsUntouched: true. Se quiser dar baixa, despublique antes de desconectar.
Se você receber remoteUnlink: "pending", chame o DELETE novamente: é idempotente e tenta a
etapa do portal outra vez. Na Argenprop essa nova tentativa vai continuar devolvendo pending
— uma vez revogada a conexão já não temos a credencial para encerrar a sessão — então o que importa
é o resultado da primeira chamada.
Olhe o status, não se a conexão existe. GET /connections também retorna as conexões revogadas: mantemos o registro para permitir a reconexão. Se o seu código fizer if (connections.length > 0), vai considerar 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, vai gerar links que ninguém usa.
Na Zonaprop, além disso: cota mensal e limites.
Respostas de erro
| Código | Quando | O que fazer |
|---|---|---|
400 | O portal não admite este fluxo | Use zonapropapi ou argenpropapi |
409 | Você não declarou o registro do cliente | Crie-o 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 completou a autorização | Peça que ele finalize a etapa no portal |
409 portal_account_already_connected | Essa conta do portal já está conectada a outra integração | Ela precisa ser desconectada de onde está conectada hoje. Uma conta de portal tem um único dono |
Os demais são resolvidos pelo seu cliente na própria página e não chegam à sua aplicação.
O que o seu cliente vê
A página é nossa, não leva a sua marca nem a da Mapaprop além de um rodapé, e não tem navegação: não o convida a ir para nenhum outro lugar. Ela mostra o nome da imobiliária e explica o que ele está por fazer.
Se terminar corretamente, avisa que ele pode fechar. Se algo falhar, dizemos a ele com o motivo do próprio portal e deixamos que tente novamente.
Em nenhum caso a credencial do portal passa pela sua aplicação. Dependendo do portal:
- Na Zonaprop o seu cliente a digita no site do portal, na própria janela dele: nem nós a vemos.
- Na Argenprop ele a digita na nossa página, porque o portal não tem uma tela de autorização: conectar-se é fazer login. Nós a usamos uma única vez para que o portal nos autorize, armazenamos a permissão que ele devolve e não armazenamos a senha.
A Argenprop entrega credenciais de integração separadas daquelas que a imobiliária usa para entrar no site, no formato xxxx@api.com. Se o seu cliente conectar com as do site, a conexão fica registrada, mas as publicações falham por permissões. A página o avisa; se você vir esse relato, verifique com qual usuário ele conectou.
Esse e-mail traz também um número, que o Argenprop chama de IdAnunciante e também de IdVendedor: são o mesmo dado. A página o pede com os dois nomes, então o seu cliente vai reconhecê-lo.
O Argenprop pode dar baixa nos anúncios que o seu cliente tinha publicados por outro meio. Se ele vinha usando o painel do portal ou outro CRM, o portal retira esses anúncios quando a conta passa a ser gerida a partir de um sistema novo, para que não fiquem duplicados ao republicar. Quem faz isso é o Argenprop, não nós nem a sua integração.
Avise-o antes de conectar, e já conte com republicar a carteira dele a partir do seu sistema. Mais detalhe: Argenprop.