Documentação para Desenvolvedores

OAuth2

Nós recomendamos essa opção caso sua app necessite acessar contas de terceiros.

O protocolo OAuth2 permite o acesso parcial ou total por terceiros sem necessidade de compartilhar sua senha. É mais complexo que acessar por usuário e senha mas é mais flexível. OAuth2 funciona muito bem para aplicações web, assim como para desktop e mobile.

Bibliotecas

Há bibliotecas OAuth2 para quase todas as linguagens visto que é um protocolo amplamente utilizado na industria de software e por empresas como Google e Facebook.

Escolha uma biblioteca antes de começar.

Registro da Aplicação

Para começar você precisa cadastrar a sua aplicação. Nós te forneceremos um client_id e client_secret.

Você também deverá nos fornecer uma URL de Redirecionamento redirect_uri para o seu site.

Endpoints

Sandbox URL
Authorize URL GET https://sandbox.boletosimples.com.br/api/v1/oauth2/authorize
Token URL POST https://sandbox.boletosimples.com.br/api/v1/oauth2/token
Produção URL
Authorize URL GET https://boletosimples.com.br/api/v1/oauth2/authorize
Token URL POST https://boletosimples.com.br/api/v1/oauth2/token

Resumo do funcionamento

OAuth2 requer que o usuário autorize o acesso da sua app à conta dele. Para autenticar o usuário no OAuth2:

  • Use o client_id e client_secret que você obteve conosco durante o registro para redircionar o usuário para a Authorize URL. Opcionalmente inclua o scope para acessar alguma informação em específico.
  • Se o usuário autorizar sua app, ele será redirecionado para a redirect_uri que você configurou no registro com o parâmetro code.
  • Use o parâmetro code recebido para gerar um access_token fazendo uma requisição no Token URL.
  • Use o access_token para fazer as requisições em nome do usuário.

Passo a Passo detalhado

  1. Considerando as seguintes informações:

    • Client ID -> fc4e525ff3
    • Client Secret -> 95ea9a477d
    • Redirect URL -> http://seusite.com.br
  2. Redirecione o usuário para o endereço abaixo.

    https://sandbox.boletosimples.com.br/api/v1/oauth2/authorize?response_type=code&client_id=fc4e525ff3&redirect_uri=http://seusite.com.br
     client_id = 'fc4e525ff3'
     client_secret = '95ea9a477d'
     redirect_url = 'http://seusite.com.br'
    
     client = OAuth2::Client.new(client_id, client_secret, site: 'https://sandbox.boletosimples.com.br/api/v1')
     redirect_to client.auth_code.authorize_url(redirect_uri: redirect_url)
         
  3. O usuário verá uma tela solicitando a autorização para a sua aplicação acessar os dados dele e com dois links, um para declinar e outro para autorizar que redirecionam para os seguintes endereços:

    Caso seja declinado

    http://seusite.com.br/?error=access_denied&error_description=O+dono+do+recurso+ou+servidor+de+autorização+negou+a+solicitação

    Caso seja autorizado

    http://seusite.com.br/?code=57858ba460

    code é o código para que você possa solicitar o token de acesso.

  4. Faça uma requisição POST para o endereço abaixo para receber o access token.

    https://sandbox.boletosimples.com.br/api/v1/oauth2/token?grant_type=authorization_code&code=57858ba460&redirect_uri=http://seusite.com.br&client_id=fc4e525ff3&client_secret=95ea9a477d
    Requisição:
    curl -i \
    -d 'grant_type=authorization_code&code=57858ba460&redirect_uri=http://seusite.com.br&client_id=fc4e525ff3&client_secret=95ea9a477d' \
    -H 'User-Agent: MyApp (myapp@example.com)' \
    -X POST 'https://sandbox.boletosimples.com.br/api/v1/oauth2/token'
         
    Resposta em caso de erro:
     HTTP/1.1 401 Unauthorized
     Date: Fri, 17 Oct 2014 18:39:47 GMT
     Status: 401 Unauthorized
     Content-Type: application/json; charset=utf-8
     ...
    
     {"error":"invalid_grant","error_description":"A permissão de autorização provida é inválida, está expirada, revogada, não coincide com a URL de redirecionamento usada na requisição de autorização ou foi emitida por outro cliente."}
     
    Resposta em caso de sucesso:
     HTTP/1.1 200 OK
     Date: Fri, 17 Oct 2014 18:39:47 GMT
     Status: 200 OK
     Content-Type: application/json; charset=utf-8
     ...
    
     {"access_token":"ada046e3cc","token_type":"bearer","scope":"login"}
     
     client_id = 'fc4e525ff3'
     client_secret = '95ea9a477d'
     redirect_url = 'http://seusite.com.br'
     code = 'código de autorização retornado'
    
     client = OAuth2::Client.new(client_id, client_secret, site: 'https://sandbox.boletosimples.com.br/api/v1')
     access_token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
         
  5. Agora você pode usar o access_token para realizar chamadas a API. Esse token não expira.

    Requisição:
    curl -i \
    -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
    -H 'Content-Type: application/json' \
    -H 'User-Agent: MyApp (myapp@example.com)' \
    -X GET 'https://sandbox.boletosimples.com.br/api/v1/userinfo'
         
    Resposta:
     HTTP/1.1 200 OK
     Date: Fri, 17 Oct 2014 18:14:56 GMT
     Status: 200 OK
     ...
    
     # dados do usuário que autorizou o acesso
     
    access_token.get('/api/v1/userinfo').body
         

Cadastrando contas no Boleto Simples com a API de Parceiro

Para parceiros interessados na criação de novas contas no Boleto Simples a partir do seu produto, será necessário obter um tipo especial de token de acesso.

Para isso, cadastre a sua aplicação e obtenha o client_id e client_secret.

Depois obtenha o token de acesso usando o tipo de permissão client_credentials:

Requisição:
curl https://sandbox.boletosimples.com.br/api/v1/oauth2/token \
-d 'grant_type=client_credentials&client_id=seu_client_id&client_secret=seu_client_secret'
Resposta:
{
  "access_token":"397946a4ad90110b918c111261c184beb6cb515988688d6db9c31d5dabd03459",
  "token_type":"bearer",
  "scope":"login",
  "created_at":1434463054
}
Requisição:
require 'boletosimples'

BoletoSimples.configure do |c|
  c.environment = :sandbox
  c.application_id = 'seu_client_id'
  c.application_secret = 'seu_client_secret'
end

puts BoletoSimples.configuration.client_credentials


Resposta:
  {
    :access_token=>"397946a4ad90110b918c111261c184beb6cb515988688d6db9c31d5dabd03459", 
    :token_type=>"bearer", 
    :scope=>"login", 
    :created_at=>1434492337
  }
  

Utilize esse token na api de parceiros para criar novas contas no Boleto Simples.

Desenvolvendo aplicações para Mobile e Desktop

Se você está desenvolvendo para mobile ou desktop, você talvez não tenha uma url de redirecionamento.

Nestes casos você pode conferir as formas de se usar OAuth 2.0 para diversos tipos de devices.