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 like 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. Se você desenvolve para desktop ou mobile, veja na seção a baixo como configurar a redirect_uri.

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 \
    -u $BOLETOSIMPLES_TOKEN:x \
    -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 configurar a url para: urn:ietf:wg:oauth:2.0:oob. Isto faz com que o servidor mostre uma página em branco com o código de autorização na url e título da página. Você pode ler essa informação de alguma forma dentro da sua aplicação para poder utilizada mais tarde.

Isso usa a mesma técnica adotada pelo Google.

Aqui tem um guia (Em inglês) com um exemplo para iOS e Android.