BETA

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

ChamadaO que trazCusto
GET .../usersTodos os usuários, com e-mail e papelnada
GET .../users?detail=trueO mesmo, e ainda nome e telefones1 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"
}
CampoO que é
emailO e-mail do usuário. É o que você envia em branch.agentEmail ao publicar
roleO papel normalizado: admin, superuser, assistant, agent. null se o portal usar um que ainda não conhecemos
portalRoleO mesmo papel exatamente como o portal o nomeia. É o que você vai ver no painel dele
firstName, lastName, phone, mobileSó 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
detailSe o detalhe pôde mesmo ser lido
portalCallsQuantas 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ódigoO que aconteceu
409 portal_not_connectedO cliente não tem uma conexão ativa com esse portal
501 portal_sin_padron_de_usuariosEsse 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_unreachableO portal não respondeu. Tente de novo

Hoje a lista está disponível no Zonaprop (zonapropapi).