1. Introdução

O consumo das APIs do OneFlow é baseado em tokens JWT e dois tipos serão utilizados na integração:

1.1 - Token de usuário parceiro

Esse token contém informações do usuário parceiro e será usado para obter acesso aos aplicativos. Deve ser mantido num cofre bem seguro pois pode conceder acesso em todos os aplicativos que o parceiro está vinculado.

Para gerar esse token:

Acesse o portal Omie (por onde é feito o acesso do OneFlow – app.omie.com.br).
Depois de logado, acesse a seguinte URL: https://app.omie.com.br/api/portal/users/me/token/

1.2 - Token de aplicativo

Agora que já sabemos “quem” (token citado acima), falta identificar quais aplicativos queremos acessar. Para isso, vamos usar o token do usuário para gerar um novo token de acesso com identificação de cada aplicativo ou empresa.

2. Trabalhando com o token do usuário

2.1. Testando

A forma mais simples para testar um token, é consumir o endpoint que vai retornar os dados do usuário atual.

Exemplo:

 curl --request GET \
  --url https://app.omie.com.br/api/portal/users/me/ \
  --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.2 - Renovando

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.3 - Listando aplicativos e empresas

Com um token válido, é possível listar todos os aplicativos e empresas que este parceiro está associado.
Lembrando que no caso do OneFlow, cada empresa corresponde a um aplicativo criado.

Exemplo:

 curl --request GET \
  --url https://app.omie.com.br/api/portal/apps/ \
  --header 'Authorization: Bearer TOKEN_USUARIO' \
  --header 'Accept: application/json'

3. Aplicativos e empresas

3.1 - Obtendo o token do aplicativo/empresa

Com o access_token do usuário, obtido nos passos anteriores, vamos convertê-lo em um token de aplicativo:

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) quanto o token do usuário deverá ser obtido nos passos anteriores.

3.2 - Renovando o token de um aplicativo/empresa

Assim como é feito com o token do usuário, também é possível renovar o token de um aplicativo.

 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"
}'

4. Consumo de APIs OneFlow

Com o token obtido no passo anterior, podemos consumir as APIs do OneFlow:

Exemplo:

 curl --request POST \
  --url https://rest.oneflow.com.br/api/colaboradores/desconto \
  --header 'Authorization: Bearer TOKEN_DO_APLICATIVO' \
  --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. 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?

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 parceiro pode passar o token do usuário para o cliente? E pode deixá-las configuradas no ambiente do cliente?

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 o aplicativo do cliente?

Apenas o token do aplicativo precisa ser usado e a aplicação precisa estar pronta para renovar essa chave quando necessário.