Conexões com portais

Se a sua aplicação publica imóveis em portais através da PropertyAPI, cada cliente seu precisa ter conectada a sua própria conta do portal. Estes endpoints administram essas conexões.

Antes de começar

O token da conta do portal é você quem obtém. Estes endpoints não fazem o login no portal: eles guardam a credencial que o seu cliente já autorizou você a usar. Cada portal tem o seu próprio mecanismo de conexão.

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

Valores de 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 devolvem o valor em minúsculas (argenpropapi), então não estranhe se ele aparecer diferente da forma como você o enviou.

No Zonaprop o sufixo Api importa: o portal também tem um feed XML, e estes endpoints são apenas para a integração por API.

Identificar o seu cliente: clientRef

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

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

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, recebe 409. É isso 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).

curl -X POST https://property-api.mapaprop.com/connections \
  -H "Authorization: Bearer <TU_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "portal": "ArgenpropApi",
    "portalAccountId": "310578",
    "accountToken": "<credencial de la cuenta>",
    "clientRef": "inmobiliaria-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,
    "providerMeta": {}
  }
}

GET /connections

Lista as conexões do cliente. Só devolve os portais para os quais você tem scope: se você trabalha com Argenprop e o seu cliente também tem uma conexão de outro portal, essa não aparece.

curl https://property-api.mapaprop.com/connections \
  -H "Authorization: Bearer <TU_TOKEN>" \
  -H "x-client-ref: inmobiliaria-42"

Resposta 200: { "connections": [ ... ] }, com os mesmos campos do POST.

GET /connections/{portal}

Devolve uma conexão. 404 se esse cliente não a tiver.

DELETE /connections/{portal}

Desvincula a conexão: apagamos a credencial guardada e a conta deixa de receber consultas do portal através de nós.

É idempotente: desvincular algo já desvinculado responde 200 do mesmo jeito.

{ "status": "revoked", "alreadyRevoked": false, "externalListingsUntouched": true }

Erros