Consultar e desconectar
Estes endpoints são comuns às duas formas de conectar: tanto faz se a conta foi conectada com um link ou com a credencial.
| Método | Rota | O que faz |
|---|---|---|
GET | /connections | Lista as conexões de um cliente |
GET | /connections/{portal} | Devolve uma conexão |
DELETE | /connections/{portal} | Desvincula a conexão |
Olhe o status, não se a conexão existe. A lista devolve também as revogadas: mantemos o registro para permitir a reconexão. Se o seu código fizer if (connections.length > 0), vai dar como conectado um cliente que se desconectou.
status: "active" → conectado. "revoked" ou 404 → não.
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: cliente-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.
Não mexemos nos anúncios publicados no portal. Os anúncios são do seu cliente e continuam online exatamente como estavam. Desvincular corta o nosso acesso, nada mais. Se o seu cliente quiser tirar os anúncios do ar, precisa fazer isso no portal.
É idempotente: desvincular algo já desvinculado responde 200 do mesmo jeito.
{ "status": "revoked", "alreadyRevoked": false, "externalListingsUntouched": true }
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 ultrapassa um máximo |
401 | Unauthorized | Falta o token ou ele não é válido |
403 | Missing required scope: argenpropapi:connect | A 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 tal 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 as suas permissões.