OAuth 2.0

Para acessar as APIs do VPSA, o aplicativo deve solicitar a permissão do seu usuário. Este processo é feito através do protoloco OAuth. Quando o aplicativo desejar acessar os serviços da API do VPSA, ele deve iniciar o fluxo abaixo para obter um token de acesso. Este token fornecerá ao aplicativo permissões para acessar os dados da empresa do seu usuário.

Cadastro do aplicativo

Para acessar os dados no VPSA, o desenvolvedor deve criar uma conta no DevCenter e cadastrar seu aplicativo. Este cadastro gerará duas informações:

• client_id: o ID do aplicativo no VPSA
• client_secret: a chave do aplicativo para acesso à API. Esta chave deve ser mantida em segredo.

Ambas as informações serão necessárias para realizar o fluxo de autorização.

Fluxo de autorização

A obtenção do token se dá em duas etapas. Na primeira, o aplicativo obtém um authorization code. Na segunda, o aplicativo usa o authorization code para obter o token.

Obtendo o authorization code

Para iniciar o fluxo de autorização via OAuth, o aplicativo deve redirecionar o usuário para o seguinte endereço:

https://www.vpsa.com.br/apps/oauth/authorization?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI

Onde:

• client_id: o client_id gerado no cadastro do aplicativo
• redirect_uri: URL do aplicativo para onde o usuário deve ser redirecionado de volta. Exemplo: http://www.meuapp.com.br/oauth/callback

Quando o usuário é redirecionado, o VPSA solicita o seu login e pergunta se ele permite que o aplicativo acesse seus dados. Se o usuário aceitar, o VPSA o redireciona para a redirect_uri informada.

Ao redirecionar, o VPSA envia na requisição o seguinte parâmetro:

• code: authorization code gerado.

Exemplo:

http://www.meuapp.com.br/oauth/callback?code=AUTHORIZATION_CODE

Obtendo o token

Ao receber a requisição na redirect_uri o aplicativo deve guardar o authorization_code recebido e realizar a seguinte chamada para obter o token, direto do seu servidor para o servidor da VPSA:

POST https://www.vpsa.com.br/apps/oauth/token

Passando no corpo da requisição os seguintes parâmetros:

• grant_type: usar o texto "authorization_code".
• client_id: O ID do aplicativo no VPSA, obtido no cadastro.
• client_secret: A chave do aplicativo para acesso à API, obtida no cadastro.
• redirect_uri: a mesma redirect_uri utilizada na obtenção do authorization code.
• code: o authorization_code obtido no passo anterior.

Esses parâmetros podem ser enviados tanto com "Content-Type: application/x-www-form-urlencoded" quanto com "Content-Type: application/json".

Exemplos:

POST https://www.vpsa.com.br/apps/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=506329c6d93aab197a000013&client_secret=9182dcef5abc948c845236c0dad0b3c6201f56545a232a9c21803e3a2433372b&
code=21111f6f88fb5d70a6441f862a2342d40f8345fa7cf75ca45654a7b21381049&grant_type=authorization_code&
redirect_uri=http%3A%2F%2Fmeudominio%2Foauth%2Fcallback

POST https://www.vpsa.com.br/apps/oauth/token
Content-Type: application/json

{
  "grant_type":"authorization_code",
  "client_id":"502e7de8d93a4b4aad000010",
  "client_secret":"2f630161f708371433e0ff24e6a5b3705b566bbda8c85205b3d6deb6b1b744c9",
  "redirect_uri":"http://www.meuapp.com.br/oauth/calback",
  "code":"5d27be8e3bc6fac6ecfcd30c46188da0223b1b7df2e451a7f8aa643058c362cf"
}

A resposta desta requisição trará um JSON, contendo os seguintes parâmetros:

• access_token: o token gerado.
• expires_in: segundos de duração do token.
• refresh_token: token utilizado para gerar um novo token com nova data de expiração.
• cnpj_empresa: o CNPJ da empresa, cliente da VPSA, na qual o usuário logou.
• id_terceiro: o id do usuário logado. Para obter mais dados do usuário é possível consultar a API de terceiros com este ID.
• nome_terceiro: o nome do usuário logado.

Exemplo:

{
  "access_token":"4285007069f6e024ff10bece2c772acd4733bc4f363e316517147f751fd351e9",
  "expires_in":1800,
  "refresh_token":"e4e8ae71ddf715db5b75f32349719e05acd64c80b5ac633861ed0e4af4dddaf0",
  "cnpj_empresa":"99999999000199",
  "id_terceiro":"123",
  "nome_terceiro":"Nome do Usuário"
}

Usando o token

Com o token, o aplicativo pode realizar as chamadas à API do VPSA.

O token pode ser enviado no body da requisição, em um JSON. Exemplo:

GET: https://www.vpsa.com.br/apps/api/terceiros
{
  "token":"4285007069f6e024ff10bece2c772acd4733bc4f363e316517147f751fd351e9"
}

Ou pode ser enviado como parâmetro da requisição. Exemplo:

GET: https://www.vpsa.com.br/apps/api/terceiros?token=4285007069f6e024ff10bece2c772acd4733bc4f363e316517147f751fd351e9

Exemplos de implementação

• Rails: rails-oauth-client