Além de gerenciar os usuários dos aplicativos Omie pela interface, você também pode realizar essa gestão de forma mais prática, via API.
Através das nossas APIs, você poderá realizar diversas ações relacionadas à gestão de usuários, como inclusão, atualização, exclusão e consulta de dados.
Neste artigo, temos os seguintes tópicos:
Introdução: Consumo das APIs para Gestão de Usuários
Para realizar a gestão de usuários, é necessário obter o Token de Usuário. Este Token contém informações específicas do usuário e é utilizado para obter acesso aos aplicativos. Através dele, você realizará todas as consultas e processos via API.
Para isso obter o Token, siga os passos abaixo:
Token de Usuário
Para garantir a segurança dos dados, recomendamos que este Token seja mantido em um cofre de senhas, com extrema confidencialidade, uma vez que ele concede acesso a todos os aplicativos aos quais o usuário está vinculado.
Para adquiri-lo, é necessário realizar o login no Omie, então, acesse a seguinte URL:
💡 Informações Importantes
O consumo destas APIs é baseado em Tokens JWT (JSON Web Tokens).
Através do URL, você obterá o Token de Usuário.
Após obter o Token, você pode Listar os Aplicativos para obter o App Hash.
Trabalhando com o Token do Usuário
1. Testando o Token
A forma mais simples para testar um Token e confirmar a sua validade, é consumir o endpoint que vai retornar os dados do usuário atual.
Abaixo, demonstramos um exemplo do endpoint:
curl --request GET \
--header 'Authorization: Bearer TOKEN_USUARIO' \
--header 'Accept: application/json'
Caso você não consiga obter um JSON com os dados do usuário, significa que o Token está expirado e você precisa renová-lo.
2. Listando Aplicativos
Com um Token válido, é possível listar todos os aplicativos que este Usuário está associado.
Abaixo, demonstramos um exemplo de endpoint:
curl --request GET \
--header 'Authorization: Bearer TOKEN_USUARIO' \
--header 'Accept: application/json'
Na response desse código você poderá obter o hash do aplicativo na tag "app_hash".
Grupos de Acesso
Se necessário, é possível listar os grupos de acesso existentes.
Abaixo, demonstramos um exemplo de endpoint:
curl --request GET \
--url https://app.omie.com.br/api/portal/apps/app-hash/groups/ \
--header 'Authorization: Bearer TOKEN'
Aplicativos x Usuários
Listando os Usuários do aplicativo
Através da API, é possível listar os usuários existentes em determinado aplicativo. Para isso, você precisará ter em mãos o Token do Usuário e o App Hash.
Abaixo, demonstramos um exemplo de endpoint:
curl --request GET \
--url https://app.omie.com.br/api/portal/apps/app-hash/users/ \
--header 'Authorization: Bearer TOKEN'
Incluindo ou alterando um Usuário do aplicativo
E também, é possível incluir um novo usuário a um aplicativo, ou alterar os dados de um usuário existente.
Lembrando que: caso o usuário já esteja registrado no aplicativo, suas permissões serão atualizadas. Contudo, se o usuário não existir, um novo será adicionado.
curl --request PUT \
--url https://app.omie.com.br/api/portal/apps/app-hash/users/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
"user_email": "email@teste.com.br",
"group_id": "auth_group_id",
"notify": false,
"accept": true
}'
Excluindo um Usuário do aplicativo
Através da API, é possível excluir e cancelar o acesso de um usuário.
Abaixo, demonstramos um exemplo de endpoint:
curl --request DELETE \
--url https://app.omie.com.br/api/portal/apps/app-hash/users/user_email=email@teste.com.br \
--header 'accept: application/json' \
--header 'Authorization: Bearer TOKEN'
Renovando o Token de Acesso
Para renovar o Token de Usuário, é necessário utilizar o par de tokens (Token de Acesso + Refresh Token) fornecido e trocá-los por novos tokens.
Abaixo, demonstramos um exemplo de endpoint:
curl --request POST \
--header 'Content-Type: application/json' \
--data '{
"token": "TOKEN_USUÁRIO (ANTIGO)",
"refresh_token": "REFRESH_TOKEN"
}'
Com tudo certo, você receberá na response um JSON com os novos tokens!
FAQ - API de Gestão de Usuários
1) Não consigo obter os dados do usuário. O que acontece?
Se você não consegue obter os dados do usuário, é provável que as chaves de acesso estejam inválidas e precisem ser renovadas.
2) Por que não consigo renovar as chaves de um usuário?
Se você está tendo dificuldades para renovar as chaves de um usuário, pode ser que a chave original tenha sido revogada ou o usuário já não exista mais.
Nesse caso, converse com o time Omie para ajudá-lo.
3) O usuário pode passar o token do usuário para o cliente? E pode deixá-las configuradas no ambiente do cliente?
Não, as chaves devem ser mantidas de forma segura em um ambiente controlado pelo usuário, preferencialmente em um cofre de senhas.
