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
| Portal | Valor | Scope necessário | Como você obtém a credencial |
|---|---|---|---|
| Argenprop | ArgenpropApi | argenpropapi:connect | login com as credenciais do seu cliente |
| Cabaprop | CabapropApi | cabapropapi:connect | OAuth do portal |
| MercadoLibre | MercadolibreApi | mercadolibreapi:connect | OAuth 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).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
portal | string | sim | Ver Valores de portal |
portalAccountId | string ou número | sim | Id da conta no portal. Diferencia maiúsculas |
accountToken | string | sim | Credencial da conta. Máximo 4096 bytes |
clientRef | string | sim* | Seu id de cliente. *Pode ser enviado pelo header |
tokenExpiresAt | número ou null | não | Vencimento em epoch, se o portal informar |
scopesGranted | array de string | não | Permissões que seu cliente lhe deu. Até 32 |
appMeta | objeto | não | Dados 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ódigo | error | O que aconteceu |
|---|---|---|
400 | portal is required / portal must be a non-empty string | Falta o portal ou ele não é texto |
400 | Invalid JSON body | O corpo não é um JSON válido |
400 | clientRef 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 |
401 | Unauthorized | Falta o token ou ele não é válido |
403 | Missing required scope: argenpropapi:connect | Sua aplicação não tem o scope desse portal |
404 | Connection not found | Esse cliente não tem conexão com esse portal |
409 | portal account already connected | Essa conta de portal já está conectada por outra aplicação |
503 | Connection 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.