Como funcionam os Tokens de API

Os Tokens de API permitem que sistemas externos se autentiquem e se comuniquem com o sistema da imobiliária. Eles funcionam como uma credencial de acesso para integrações desenvolvidas sob medida, permitindo consultar ou enviar informações conforme as permissões definidas.

Cada token pode possuir um perfil específico, que determina exatamente quais recursos o sistema externo poderá acessar.

Navegação no Módulo

Rotina: Configurações > Integrações > Tokens de API

Nesta tela é possível criar, visualizar e remover os tokens utilizados pelas integrações externas.

Entender a listagem de tokens

Cada token cadastrado aparece na listagem com suas principais informações.

Campo / Informação	Descrição
Código	Identificador interno do token.
Descrição	Nome utilizado para identificar para qual integração ou parceiro o token foi criado.
Grupo	Perfil de acesso vinculado ao token, responsável por definir suas permissões.
Expiração	Data até a qual o token poderá ser utilizado.
Token	Código utilizado para autenticação da integração. Fica oculto até utilizar a opção Mostrar Token .
Criação	Data em que o token foi gerado.
Documentação	Abre a documentação técnica da API com os recursos disponíveis para integração.

Criar um token

Clique em Cadastrar para gerar uma nova credencial.

Campo	Descrição
Descrição	Nome utilizado para identificar o token. Campo obrigatório. Recomenda-se utilizar o nome da ferramenta ou parceiro que receberá o acesso.
Perfil da API	Define quais informações e funcionalidades poderão ser acessadas utilizando aquele token. Campo obrigatório.

Depois de preencher os campos, grave as informações para gerar o token.

O Perfil da API define as permissões do token. Sempre que possível, utilize um perfil com somente os acessos necessários para aquela integração, evitando liberar recursos que o sistema externo não precisa utilizar.

Entender o Perfil da API

O Perfil da API funciona de forma semelhante às permissões de um usuário do sistema.

É por meio dele que se define quais recursos poderão ser consultados ou alterados pela integração.

Configuração	Funcionamento
Perfil mais restrito	A integração possui acesso somente aos recursos necessários para executar sua função.
Perfil mais amplo	A integração pode acessar uma quantidade maior de informações e funcionalidades.

Por segurança, é recomendado criar perfis específicos para cada tipo de integração.

Visualizar e entregar o token

Por padrão, o código do token permanece oculto na listagem.

Utilize Mostrar Token para visualizar a credencial e encaminhá-la ao responsável pela integração.

Opção	Descrição
Mostrar Token	Exibe o código utilizado pelo sistema externo para autenticar as requisições à API.

O token deve ser tratado como uma senha. Evite compartilhá-lo em grupos, documentos públicos ou locais sem controle de acesso. Sempre que possível, utilize um token diferente para cada parceiro ou integração.

Utilizar um token por integração

Mesmo que tecnicamente um único token possa ser utilizado em mais de uma integração, é recomendado manter credenciais separadas.

Por exemplo:

Token	Utilização
Integração Parceiro A	Utilizado somente pelo sistema do Parceiro A.
Aplicativo interno	Utilizado pelo aplicativo desenvolvido pela própria imobiliária.
Integração Parceiro B	Utilizado exclusivamente pelo Parceiro B.

Dessa forma, se uma integração precisar ser desativada, basta remover o token correspondente sem afetar as demais.

Remover um token

Para encerrar o acesso de uma integração, selecione o token na listagem e clique em Remover.

A partir da remoção, a credencial deixa de permitir novas comunicações com a API.

Esse procedimento pode ser utilizado quando:

uma integração não será mais utilizada;
o acesso de um parceiro precisa ser encerrado;
houver suspeita de exposição da credencial;
for necessário substituir um token existente.

Consultar a documentação da API

O botão Documentação permite acessar a referência técnica da API.

Nela, os responsáveis pelo desenvolvimento da integração podem consultar os recursos disponíveis e entender como realizar as requisições utilizando o token criado.

Opção	Descrição
Documentação	Abre a referência técnica da API com os recursos disponibilizados para integrações externas.

Perguntas frequentes

➜ Para que serve um Token de API? Ele permite que um sistema externo se identifique e seja autorizado a consultar ou enviar informações por meio da API.

➜ Preciso criar um token para todas as integrações do sistema? Não. As integrações prontas normalmente possuem seus próprios mecanismos de autenticação. Os Tokens de API são utilizados principalmente em integrações personalizadas.

➜ Posso utilizar o mesmo token em vários sistemas? É possível, mas não é recomendado. Criar um token para cada integração facilita o controle e permite revogar um acesso sem afetar os demais.

➜ Como limito o que uma integração pode acessar? Por meio do Perfil da API selecionado durante o cadastro do token.

➜ O token possui data de validade? Sim. A data de expiração pode ser consultada diretamente na listagem.

➜ O que acontece quando o token expira? A credencial deixa de funcionar e a integração precisa utilizar um novo token válido.

➜ Perdi o token. Consigo visualizá-lo novamente? Sim. Utilize a opção Mostrar Token disponível na listagem.

➜ O que faço se suspeitar que o token foi exposto? Remova a credencial existente e gere um novo token para a integração.

➜ Onde encontro as informações técnicas para desenvolver uma integração? Utilize o botão Documentação na tela de Tokens de API para acessar a referência técnica dos recursos disponíveis.