Os usuários do seu cliente no portal
GET /property-v1/customers/{portal}/users
Ao publicar um anúncio você pode escolher qual corretor fica como responsável, enviando o e-mail
dele em branch.agentEmail. Mas esse e-mail precisa ser
o de um usuário que exista na conta do portal — e é deste endpoint que você o obtém.
Se você enviar um e-mail que não é de nenhum usuário, o portal não devolve erro. Ele o
substitui pelo do administrador da conta e a publicação sai 200. Por isso convém ler a lista
antes, em vez de descobrir olhando o anúncio.
Dois níveis, e o que vem por padrão não custa nada
| Chamada | O que traz | Custo |
|---|---|---|
GET .../users | Todos os usuários, com e-mail e papel | nada |
GET .../users?detail=true | O mesmo, e ainda nome e telefones | 1 chamada da cota do seu cliente |
O nível básico não é uma versão reduzida do outro: traz mais gente. O detalhe existe apenas para os usuários com papel de corretor, então o administrador aparece somente no nível gratuito — e é justamente aquele que o portal usa quando não reconhece o e-mail que você enviou.
Como pedir
curl https://property-api.mapaprop.com/property-v1/customers/zonapropapi/users \
-H "Authorization: Bearer <SEU_TOKEN>" \
-H "x-client-ref: cliente-42"
Resposta 200:
{
"portal": "zonapropapi",
"portalAccountId": "11451",
"users": [
{ "email": "director@inmobiliaria.com", "role": "admin", "portalRole": "Administrador",
"firstName": null, "lastName": null, "phone": null, "mobile": null },
{ "email": "carina@inmobiliaria.com", "role": "agent", "portalRole": "Vendedor",
"firstName": null, "lastName": null, "phone": null, "mobile": null }
],
"detail": false,
"portalCalls": 0,
"readAt": "2026-11-16T21:40:12.004Z"
}
| Campo | O que é |
|---|---|
email | O e-mail do usuário. É o que você envia em branch.agentEmail ao publicar |
role | O papel normalizado: admin, superuser, assistant, agent. null se o portal usar um que ainda não conhecemos |
portalRole | O mesmo papel exatamente como o portal o nomeia. É o que você vai ver no painel dele |
firstName, lastName, phone, mobile | Só com detail=true. No nível gratuito são null porque não os lemos, não porque o usuário não os tenha |
detail | Se o detalhe pôde mesmo ser lido |
portalCalls | Quantas chamadas da cota do seu cliente esta consulta custou |
Com o detalhe
curl "https://property-api.mapaprop.com/property-v1/customers/zonapropapi/users?detail=true" \
-H "Authorization: Bearer <SEU_TOKEN>" \
-H "x-client-ref: cliente-42"
{
"users": [
{ "email": "carina@inmobiliaria.com", "role": "agent", "portalRole": "Vendedor",
"firstName": "Carina", "lastName": "Milesse", "phone": "3425050115", "mobile": null }
],
"detail": true,
"portalCalls": 1
}
Serve para montar o contato completo do anúncio: se você escolher um corretor, convém enviar também
o nome e o telefone dele em branch, porque o portal não os deduz do e-mail.
Se o detalhe não puder ser lido, a resposta não falha: devolve a lista do mesmo jeito, com
detail: false. Perder o dado extra é melhor do que perder a lista.
Os usuários são criados no portal, não aqui
Esta API não cria, não edita nem exclui usuários. O cadastro de um colaborador, as permissões dele e o número de WhatsApp são administrados no painel do portal, pelo próprio cliente.
Se o seu cliente adicionar um corretor no CRM dele mas não o cadastrar no portal, o e-mail dele não
vai funcionar como agentEmail: o portal não o reconhece e atribui o anúncio ao administrador.
Quando dá erro
| Código | O que aconteceu |
|---|---|
409 portal_not_connected | O cliente não tem uma conexão ativa com esse portal |
501 portal_sin_padron_de_usuarios | Esse portal não expõe uma lista de usuários. Não é erro seu — ainda não sabemos como perguntar a esse portal |
502 portal_unreachable | O portal não respondeu. Tente de novo |
Hoje a lista está disponível no Zonaprop (zonapropapi).