BETA

Conectar com a credencial que você já tem

Cada um dos seus clientes precisa ter conectada sua própria conta do portal. Este é o caminho para os portais em que você já tem a credencial: você fez o login com as credenciais que seu cliente lhe deu, ou completou o OAuth dele, e o que falta é salvá-la.

POST /connections

Esses endpoints estão em desenvolvimento. Escreva para nós em dev@mapaprop.com se sua integração precisar deles.

Antes de começar

O token da conta do portal é obtido por você. Esses endpoints não fazem o login contra o portal: eles salvam a credencial que seu cliente já autorizou você a usar. Cada portal tem seu próprio mecanismo de conexão.

Você precisa de um scope para cada portal. Os scopes são concedidos ao registrar sua aplicação; escreva para nós indicando com quais portais você vai trabalhar.

Valores de portal

PortalValorScope necessárioComo você obtém a credencial
ArgenpropArgenpropApiargenpropapi:connectlogin com as credenciais do seu cliente
CabapropCabapropApicabapropapi:connectOAuth do portal
MercadoLibreMercadolibreApimercadolibreapi:connectOAuth do portal

Não diferencia maiúsculas de minúsculas: ArgenpropApi, argenpropapi e ARGENPROPAPI são o mesmo portal e a mesma conexão. As respostas sempre retornam o valor em minúsculas (argenpropapi), então não se surpreenda se ele vier diferente de como você o enviou.

O sufixo Api importa: alguns portais também têm um feed XML, e esses endpoints são apenas para a integração via API.

O Zonaprop não se conecta por aqui. Esses endpoints salvam uma credencial que você já tem, e o Zonaprop não emite nenhuma: a imobiliária autoriza no portal e a autorização fica do lado deles.

Para conectar o Zonaprop, solicite um link e envie-o ao seu cliente: Conectar com um link. Se você tentar por aqui, vai receber 409.

Identificar seu cliente: clientRef

clientRef é o identificador que você escolhe para cada um dos seus clientes finais. É opaco para nós: pode ser seu id interno, um UUID ou o que você usar. Você o envia no header x-client-ref (ou na query, ou no body do POST).

Suas conexões vivem em um espaço próprio: nenhuma outra aplicação pode lê-las nem tocá-las, e você também não alcança as de outra. Isso é determinado pelo seu token, não pelo que você enviar no request.

Uma conta de portal = um dono

Uma mesma conta de portal não pode estar conectada por duas aplicações ao mesmo tempo. Se você tentar registrar uma conta que já está conectada por outra aplicação, recebe 409. Isso é o que permite direcionar sem ambiguidade as consultas que chegam do portal.

POST /connections

Registra a conexão. Se você chamá-lo novamente para o mesmo cliente e portal, ele atualiza a conexão existente (é a forma de rotacionar o token).

CampoTipoObrigatórioDescrição
portalstringsimVer Valores de portal
portalAccountIdstring ou númerosimId da conta no portal. Diferencia maiúsculas
accountTokenstringsimCredencial da conta. Máximo 4096 bytes
clientRefstringsim*Seu id de cliente. *Pode ser enviado pelo header
tokenExpiresAtnúmero ou nullnãoVencimento em epoch, se o portal informar
scopesGrantedarray de stringnãoPermissões que seu cliente lhe deu. Até 32
appMetaobjetonãoDados seus. Máximo 8192 bytes serializado
curl -X POST https://property-api.mapaprop.com/connections \
  -H "Authorization: Bearer <SEU_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "portal": "ArgenpropApi",
    "portalAccountId": "310578",
    "accountToken": "<credencial da conta>",
    "clientRef": "cliente-42"
  }'

Resposta 201:

{
  "connection": {
    "portal": "argenpropapi",
    "portalAccountId": "310578",
    "status": "active",
    "scopesGranted": [],
    "createdAt": "2026-09-04T13:40:00.000Z",
    "lastActivityAt": "2026-09-04T13:40:00.000Z",
    "tokenExpiresAt": null,
    "appMeta": {}
  }
}

O accountToken nunca volta a sair. Ele é salvo criptografado e nenhum endpoint o retorna, nem mesmo criptografado. Guarde-o você mesmo se precisar dele para outra coisa.

Depois de conectar

Para consultar o status ou desconectar, veja Consultar e desconectar — funciona igual para as contas conectadas por este caminho e para as conectadas com um link.

Erros

CódigoerrorO que aconteceu
400portal is required / portal must be a non-empty stringFalta o portal ou ele não é texto
400Invalid JSON bodyO corpo não é um JSON válido
400clientRef is required (header x-client-ref, query or body)Falta identificar o cliente
400(vários, com field)Um campo não cumpre o formato ou excede um máximo
401UnauthorizedFalta o token ou ele não é válido
403Missing required scope: argenpropapi:connectSua aplicação não tem o scope desse portal
404Connection not foundEsse cliente não tem conexão com esse portal
409portal account already connectedEssa conta de portal já está conectada por outra aplicação
503Connection storage is temporarily unavailable (encryption backend)Problema temporário nosso. Tente novamente

Um 403 informa exatamente qual scope está faltando, e esse texto inclui o portal exatamente como você o enviou. Se você vir Missing required scope: argenprop:connect em vez de argenpropapi:connect, o problema é o valor de portal, não suas permissões.