As APIs do OneFlow são executadas por empresa e sua autenticação é baseada em tokens JWT.
Por segurança, para realizar as integrações, é necessário estar autenticado no contexto da empresa desejada. Desta forma, é preciso que o sistema que irá integrar com o OneFlow, possua a capacidade de gerenciar as autenticações por empresa.
Pensando que um escritório contábil possui N empresas, tenha em mente que a autenticação ocorre em camadas. Primeiramente é necessário se conectar no aplicativo OneFlow do escritório, para na sequência obter e se autenticar nas empresas relacionadas.
Siga os seguintes passos para autenticar as APIs:
1. Usuário de integração
O consumo das APIs do OneFlow é baseado em tokens JWT e dois tipos serão utilizados na integração:
É necessário possuir um usuário cadastrado no sistema e com acesso ao OneFlow e dentro deste às empresas desejadas. Recomendamos que seja criado um usuário de integração (para que não seja utilizado um “usuário real”) e que esse login e senha não seja compartilhado.
Tendo o usuário já cadastrado, será necessário obter o token de acesso deste usuário que será utilizado na integração.
1.1. Geração do token do usuário
Para gerar esse token:
Acesse o portal OneFlow (portal.oneflow.com.br) ou o portal Omie (app.omie.com.br) com o usuário que será utilizado na integração.
Depois de logado, acesse a seguinte URL: https://app.omie.com.br/api/portal/users/me/token/
Será exibido o token do usuário de integração. Esse token deve ser mantido em um cofre bem seguro pois pode conceder acesso ao OneFlow e às empresas do usuário de integração.
Importante: O token de usuário expira a cada 24 horas. Por isso, após esse período é necessário executar o procedimento de renovação, que é feito por API específica.
1.2. Renovação do token do usuário
A renovação pode ser automatizada. Para renovar o token de usuário, será necessário usar o par de tokens (token + refresh token) que foi disponibilizado e trocá-los por novos tokens:
Exemplo:
curl --request POST \
--url https://app.omie.com.br/api/portal/users/refresh-token/ \
--header 'Content-Type: application/json' \
--data '{
"token": "TOKEN_ANTIGO",
"refresh_token": "REFRESH_TOKEN"
}'
2. Aplicativo OneFlow que será utilizado
Com um token válido, é possível listar todos os aplicativos OneFlow que o usuário tem acesso. Caso esse usuário também tenha acesso à aplicativos do Omie ERP, eles também serão exibidos.
Para integração com o OneFlow, precisamos do HASH (app_hash) do sistema do escritório de contabilidade que pode ser identificado pelo “app_type” = “ONEFLOW”.
Exemplo:
curl --request GET \
--url https://app.omie.com.br/api/portal/apps/ \
--header 'Authorization: Bearer TOKEN_USUARIO' \
--header 'Accept: application/json'
É necessário utilizar sempre um token de usuário válido (conforme explicado no item 1).
2.1 - Obtendo o token do aplicativo OneFlow
Agora, precisamos obter o TOKEN e o REFRESH TOKEN do aplicativo OneFlow:
Exemplo:
curl --request GET \
--url https://app.omie.com.br/api/portal/apps/[app-hash]/token/ \
--header 'Authorization: Bearer TOKEN_DO_USUARIO'
Tanto o app-hash (identificando o aplicativo OneFlow) quanto o token do usuário deverá ser obtido nos passos anteriores.
3. Empresas que serão acessadas
Agora, será necessário listar as empresas do escritório que o usuário tem acesso:
Exemplo:
curl -X 'GET' \ 'https://rest.oneflow.com.br/api/oneflow/escritorio/empresas/listar?pagina=XXXX' \
--header 'Authorization: Bearer TOKEN_DO_ESCRITORIO'
Nessa listagem serão retornados a RAZÃO SOCIAL, CNPJ e o HASH (app_hash) de cada empresa que o usuário tem acesso no aplicativo OneFlow em questão.
O token do escritório (aplicativo OneFlow) deverá ser obtido conforme item 2.1.
3.1. Autenticação de cada empresa
Tendo o HASH de cada empresa, é necessário pegar o TOKEN e o REFRESH TOKEN de cada empresa:
Exemplo:
curl --request GET \
--url https://app.omie.com.br/api/portal/apps/[app-hash]/token/ \
--header 'Authorization: Bearer TOKEN_DO_USUARIO'
O token do usuário deverá ser obtido conforme item 1.
O app-hash da empresa deverá ser obtido conforme item 3.
4. Consumo de APIs OneFlow
Com o token obtido no passo anterior, podemos consumir as APIs do OneFlow por empresa:
Exemplo:
curl --request POST \
--url https://rest.oneflow.com.br/api/colaboradores/desconto \
--header 'Authorization: Bearer TOKEN_DA_EMPRESA' \
--data '{
"parcelas": [
{
"cpf": "860.361.525-07",
"idContrato": "113123",
"idProposta": "113123",
"idParcela": "installment-0008b894-8939-47d2-918b-fa2898c23190",
"valor": 423.19,
"mesReferencia": 9,
"anoReferencia": 2022,
"NumeroParcela": 3,
"cancelado": false
}
]
}'
5. Renovando o token de um aplicativo OneFlow ou de uma empresa
Uma vez tendo as informações de token, refresh token e hash de um aplicativo OneFlow ou de uma empresa, é possível renovar o token:
curl --request GET \
--url https://app.omie.com.br/api/portal/apps/app-hash/refresh-token \
--header 'Content-Type: application/json' \
--data '{
"token": "TOKEN_ANTIGO",
"refresh_token": "REFRESH_TOKEN"
}'
6. Perguntas e respostas sobre a utilização de APIs
Não consigo obter os dados do usuário. O que acontece?
Provavelmente as chaves foram invalidadas e é necessário renová-las.
Por que não consigo renovar as chaves de um usuário?
É possível que a chave original tenha sido expurgada ou o usuário não exista mais.
O que significa o código 403 ao tentar gerar o token de um aplicativo ou empresa?
Isso significa que o usuário não possui acesso ao aplicativo ou a empresa. Siga os seguintes passos:
Já verificou se esse aplicativo está sendo retornado na lista de aplicativos?
Se o aplicativo/empresa não está na lista, significa que ainda está sem acesso. Peça ajuda para o time do suporte informando o ID do aplicativo e o e-mail do usuário parceiro.
O token do usuário pode ser compartilhado?
Não. Essas chaves deverão ser bem guardadas num ambiente gerido pelo parceiro e de preferência num cofre de senhas.
Qual chave deve ser usada para acessar cada empresa?
Apenas o token da empresa precisa ser usado e a aplicação precisa estar pronta para renovar essa chave quando necessário.
Quais são as APIs disponibilizadas pelo OneFlow?
Clique aqui para acessar a documento das APIs disponíveis.