BETA

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étodoRotaQuem chama
POST/property-v1/connect-linksVocê, com o seu token
GET/property-v1/connect-links/{token}A página que o seu cliente vê
POST/property-v1/connect-links/{token}/confirmA 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

PortalComo 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, MercadoLibreConexõ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:

authorizecredentials
PortalZonapropArgenprop
O que o seu cliente fazautoriza em uma janela do portaldigita usuário e senha do portal na nossa página
Quem vê a credencialninguém: o portal a pede no próprio siteele 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.

CampoTipoObrigatórioDescrição
portalstringsimzonapropapi ou argenpropapi
clientRefstringsim*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:

EtapaChamadaConsome cota do portal?
Decidir qual botão mostrarGET /connections/{portal}não
Clique em ConectarPOST /property-v1/connect-links → abra a urlnão
O seu cliente autoriza—sim, 1
Clique em DesconectarDELETE /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.

  1. 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.
  2. 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.
PortalConsome cota do seu cliente?
Zonapropsim, 1 — é uma rota por imobiliária
Argenpropnã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ódigoQuandoO que fazer
400O portal não admite este fluxoUse zonapropapi ou argenpropapi
409Você não declarou o registro do clienteCrie-o com POST /property-v1/customers
404O link não existeVerifique se está completo
410O link expirou (7 dias)Solicite um novo
409 not_authorized_yetO seu cliente ainda não completou a autorizaçãoPeça que ele finalize a etapa no portal
409 portal_account_already_connectedEssa conta do portal já está conectada a outra integraçãoEla 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.