Aplicativos

Introdução

Este manual contempla o passo a passo aos integradores que desejam criar um aplicativo e entender o funcionamento do fluxo de autorização para a obtenção dos tokens de acesso do OAuth 2.0.

Acesso ao módulo

É possível cadastrar um aplicativo pela conta do administrador ou criando um usuário para tal finalidade. Recomendamos a criação de um usuário para cada desenvolvedor, dessa forma, cada usuário poderá gerenciar somente os seus aplicativos.

1. Para criar um usuário acesse o menu "Preferências > Sistema > Usuários", clique em "Incluir usuário".
   
2. Nas permissões de "Cadastros" selecione "Cadastro de aplicativos" e preencha as informações da conta do usuário.
   

Após esse processo, o usuário possuirá acesso ao módulo de Cadastro de aplicativos.

Como cadastrar

Na tela de preferências clique na aba Cadastros, e em seguida, na opção Cadastro de aplicativos.

Na tela de cadastro de aplicativos clique no botão CRIAR NOVO APLICATIVO.

Visibilidade

Escolha a visibilidade do aplicativo:

Visibilidade	Descrição
Público	O aplicativo será utilizado para realizar operações em outras contas Bling e passará pelo processo de homologação. Enquanto não for homologado, o número de usuários que podem autorizá-lo estará restrito a 10.
Privado	O aplicativo será utilizado para realizar operações na própria conta Bling.

No tipo do aplicativo, selecione a opção API e clique no botão Próximo.

Na sequência preencha os seguintes dados do aplicativo:

• Logo: Exibido aos usuários do aplicativo. Automaticamente um logo com as iniciais do nome do aplicativo será criado, caso nenhuma imagem for inserida.
• Nome: Exibido aos seus usuários.
• Categoria: Classificação de negócio.
• Descrição: Detalhamento das principais características e finalidades deste aplicativo.
• URL de redirecionamento: Utilizado na etapa de autorização.
• URL da homepage: Endereço do site do aplicativo.
• Lista de escopos: Escopos referentes aos dados dos usuários que serão acessados pelo aplicativo.

Após o preenchimento dos dados, clique no botão Salvar para finalizar a criação do aplicativo. O botão será habilitado somente após a inserção de um escopo.

Escopos

O Escopo é a representação da permissão para operar sobre os recursos do usuário. Portanto, informe somente os escopos necessários, passando maior clareza e segurança ao usuário no momento da autorização do aplicativo.

Para inserir os escopos clique no botão Adicionar, conforme ilustrado na imagem a seguir.

Marque os escopos que serão utilizados pelo aplicativo e clique no botão Adicionar. Caso seja necessário, é possível filtrar os escopos por módulo e nome, usando a busca localizada no topo desta janela.

Os escopos escolhidos serão listados no formulário. Para excluir um escopo, passe o cursor sobre a linha desejada e clique no ícone da lixeira, uma janela pedindo a confirmação da exclusão será exibida.

Se precisar inserir novos escopos, clique na ação de Adicionar escopo logo abaixo da listagem.

É importante lembrar que o aplicativo só terá acesso aos dados referentes aos escopos selecionados. Qualquer adição ou exclusão de escopos só será confirmada após o salvamento do aplicativo. Se isso acontecer, uma janela de confirmação será exibida.

Ao confirmar a edição, todos os usuários do aplicativo serão automaticamente revogados. Desta forma, é garantida a segurança das informações dos usuários, exibindo a nova listagem de escopos no momento da autorização.

Visualização

Após a criação de um aplicativo, será exibido ao lado do formulário o número de usuários. O Client Id e o Client Secret, que serão utilizados no momento da autorização.

É possível revogar os usuários do aplicativo. Essa ação exclui todos os tokens de acesso e faz com que os usuários tenham que realizar novamente a etapa de autorização. Ao executar a ação através do botão Revogar, será solicitanda a confirmação da ação.

Logo abaixo da quantidade de usuários é possível visualizar as credenciais do aplicativo. Para revelar o Client Secret clique no ícone de olho. Assim como qualquer credencial, é importante manter a chave em segredo. Esta credencial será utilizada nas requisições para obtenção de tokens de acesso. O Client Secret poderá ser alterado a qualquer momento clicando no botão Resetar client secret.

Após pressionar o botão Resetar client secret será solicitada a confirmação da ação. A ação gera um novo Client Secret, portanto será necessário realizar a alteração nas requisições que fazem uso do Client Secret anterior.

Exclusão

Para excluir um aplicativo clique no botão Excluir.

Ao pressionar o botão Excluir, será solicitada a confirmação da ação. A exclusão de um aplicativo fará com que todos os tokens de acesso dos seus usuários sejam automaticamente revogados, ou seja, os usuários não terão mais acesso ao aplicativo.

Códigos de acesso

Para gerar os códigos de acesso é necessário que os usuários deem autorização sobre o acesso aos dados das contas, ao aplicativo. O OAuth 2 protocola 4 tipos de concessão para que essa autorização seja realizada, no entanto o Bling fará uso de apenas uma delas, que é o Authorization Code. Portanto, será necessário seguir o fluxo de autorização descrito abaixo para obter os códigos de acesso.

Terminologia

Termo	Detalhamento
Client App	Aplicativo que fará uso dos dados das contas dos usuários (conta Bling).
Authorization Code	Código enviado ao Client App quando um usuário autoriza acesso aos dados.
Access Token	Token utilizado para requisição do recurso dos usuários.
Refresh Token	Token utilizado para requisitar um novo access_token, quando o mesmo expirar.

Fluxo de autorização

Segue abaixo um resumo das etapas do fluxo de autorização.

1. O client app, com a intenção de obter o authorization_code, redireciona o usuário (através do seu user agent) para o authorization server.
2. O usuário se autentica no sistema e autoriza, ou não, o aplicativo.
3. O authorization server redireciona o usuário (através do user agent) de volta ao client app, utilizando a “URL de redirecionamento” inserida no cadastro do aplicativo. Se o usuário autorizou o acesso aos seus recursos, o authorization_code será incluído no retorno e segue-se para o passo a seguir. Caso contrário, o fluxo de autorização termina aqui.
4. O client app requisita o access_token, fazendo uma requisição para o authorization server com o authorization_code recebido no passo anterior.
5. Se o authorization_code for válido, o authorization server retornará um JSON contendo o access_token e o refresh_token.

Authorization code

Utilizando redirecionamento de URL o client app direciona o usuário para o endpoint authorize:

GET
/Api/v3/oauth/authorize?response_type=code&client_id=[seu_client_id]&state=[sequencia_de_caracteres_aleatorios] HTTP/1.1
Host: https://www.bling.com.br

Parâmetro	Descrição
response_type	O valor deve ser code. Significa que o aplicativo está requisitando um authorization_code.
client_id	Client id do aplicativo, exibido na edição do aplicativo.
state	Sequência aleatória de caracteres e de preferência única para cada sessão. O valor informado será mantido pelo authorization server e incluído na resposta ao client. Assim, ao comparar o valor recebido do enviado, é possível amenizar problemas com cross-site request forgery (CSRF).

Os parâmetros redirect_uri e scope são considerados de uso opcional pela RFC, portanto, os mesmos não serão exigidos na requisição. Para estes dois parâmetros sempre serão usados os valores inseridos previamente no cadastro de aplicativos, mesmo que os mesmos sejam utilizados na requisição.

URL de exemplo da requisição:

https://www.bling.com.br/Api/v3/oauth/authorize?response_type=code&client_id=7dbf42c119eea8b65d2c1a1a9ad92b1577594&state=291e61b56ab3d845622cf137b1e1e2

Se o usuário autorizar a sua solicitação, o authorization server irá redirecionar o user agent para a URL de redirecionamento do aplicativo. Os parâmetros abaixo são incluídos na URL de redirecionamento:

Parâmetro	Descrição
code	Authorization code, que possui tempo de expiração de 1 minuto. Utilizado para obtenção dos tokens de acesso.
state	Mesmo valor informado na requisição. Caso o state retornado for diferente do utilizado na requisição, ignore-a e interrompa o fluxo de autorização.

Exemplo de URL usada como callback com os parâmetros utilizados no retorno do authorization server:

https://www.clientapp.com.br/callback?code=6521791563472106326454c818bd19f60febdcf3&state=291e61b56ab3d845622cf137b1e1e2

Tokens de acesso

Com o authorization_code o client app deve realizar uma requisição POST para o endpoint /token, nisso o code será validado e os tokens de acesso serão retornados. Lembrando que o prazo para realizar esta requisição é de 1 minuto, este é o tempo de expiração do code.

Formato da requisição HTTP que deve ser utilizado e uma tabela com o conteúdo que deve ser inserido no body:

POST /Api/v3/oauth/token? HTTP/1.1
Host: https://www.bling.com.br
Content-Type: application/x-www-form-urlencoded
Accept: 1.0
Authorization: Basic [base64_das_credenciais_do_client_app]
grant_type=authorization_code&code=[authorization_code]

Parâmetro no body	Descrição
grant_type	O valor deve ser authorization_code. Informa o tipo de concessão utilizado.
code	Authorization code obtido na requisição do tópico anterior.

O client app precisa ser autenticado para realizar esta operação, portanto, será necessário informar as suas credenciais no cabeçalho da requisição (não é permitida a inserção destes parâmetros no body). Para isso use o esquema “Basic” de autenticação HTTP inserindo um cabeçalho no formato:

Authorization: Basic [credenciais_do_client_app]

Lembrando que estas credenciais devem ser o client_id junto do client_secret separados por ":" e codificados em base64. Também é importante utilizar HTTPS / TLS para garantir a segurança dos seus dados.

Faça a requisição inteiramente no lado do servidor, busque evitar a exposição de qualquer dado inserido nela, como as credenciais do app ou o authorization_code.

Segue um exemplo de requisição dos tokens de acesso utilizando cURL:

curl --location --request POST 'https://www.bling.com.br/Api/v3/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: 1.0' \
--header 'Authorization: Basic ZWRkNTE4NjQzNDYxNzdiMTE5NzFlNmY0YTUyMmM5ZmYxZGZjNjNkZjo2OGViODVkY2FkOTY3Mzk2ZDA1ZmVjZGQwMDgwMjExN2Q3NTE1MjY0YjUyMGMzNjJlN2Y0NjYxOWFhMDk=' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=6521791563472106326454c818bd19f60febdcf3'

Caso a requisição seja válida, será retornado um objeto JSON contendo o access_token, com o seu tipo, tempo de expiração, escopos permitidos e o refresh_token. Veja abaixo um exemplo desse retorno e um quadro com a explicação de cada parâmetro.

{
	"access_token": "4a9de71b8aaf91c8ebbf830888354d5479e83a01",
	"expires_in": 21600,
	"token_type": "Bearer",
	"scope": "98309 318257570 5862218180",
	"refresh_token": "e4d61baafd951bbbdec0a92cf9700a49b4cbc005"
}

Parâmetro da resposta	Descrição
access_token	Token utilizado para requisitar os recursos do usuário.
expires_in	Tempo de expiração do access_token em segundos.
token_type	Tipo do esquema de autenticação (Bearer Authentication).
scope	Lista dos ids dos escopos que o app possui permissão de acesso.
refresh_token	Token utilizado para requisitar um novo token de acesso, após a expiração do access_token.

Refresh Token

Quando o tempo do access_token terminar é possível requisitar um novo utilizando o refresh_token, o qual foi enviado junto do access_token e possui um tempo de expiração superior, de 30 dias. Para isso é realizada uma requisição POST para o endpoint token, na mesma estrutura da requisição apresentada anteriormente, a única diferença está nos parâmetros que devem ser apresentados no body. Veja abaixo o formato da requisição HTTP que deve ser utilizado e a tabela com o conteúdo que deve ser inserido no body.

POST /Api/v3/oauth/token? HTTP/1.1
Host: https://www.bling.com.br
Content-Type: application/x-www-form-urlencoded
Accept: 1.0
Authorization: Basic [base64_das_credenciais_do_client_app]

grant_type=refresh_token&refresh_token=[refresh_token]

Parâmetros no body	Descrição
grant_type	O valor deve ser refresh_token. Informa o tipo de concessão utilizado.
refresh_token	Refresh token obtido na requisição do access_token que expirou.

O retorno desta requisição é o mesmo JSON retornado na requisição do access_token com uso do authorization_code.

Utilizando o access token

Com o access_token é possível realizar requisições para a API do Bling e, assim, acessar os recursos do usuário. Lembrando que este tipo de autenticação só está disponível pela API v3 e só será possível requisitar os dados dos escopos que foram permitidos pelo usuário.

Como informado no JSON de retorno dos tokens de acesso, o tipo do token fornecido é o Bearer, portanto, utilize o esquema "Bearer" de autenticação HTTP, inserindo a chave de acesso no cabeçalho da requisição, conforme exemplo:

GET /Api/v3/[caminho_da_api_desejada] HTTP/1.1
Host: https://www.bling.com.br
Authorization: Bearer [access_token]

Exemplo de uma requisição cURL para a API de contatos:

curl --location --request GET 'https://www.bling.com.br/Api/v3/contatos' \
--header 'Authorization: Bearer 4a9de71b8aaf91c8ebbf830888354d5479e83a01' \

Exceções

Obtenção do authorization code

Neste tópico são citados alguns erros que poderão ocorrer na etapa de requisição do authorization_code. De modo geral, os erros serão retornados para a URL de redirecionamento informada no cadastro do aplicativo com a estrutura de parâmetros demonstrada na tabela abaixo.

Parâmetro	Descrição
error	O código do erro. Ex.: "invalid_request".
error_description	Descrição sobre o erro.
error_uri	Link contendo informações adicionais sobre o erro.
state	Valor do parâmetro state informado na requisição.

Aplicativo não autorizado

Caso o usuário não autorize o acesso aos escopos solicitados pelo aplicativo, o erro será retornado através da URL de redirecionamento do aplicativo.

https://www.clientapp.com.br/callback?error=access_denied&error_description=The+user+denied+access+to+your+application&state=291e61b56ab3d845622cf137b1e1e2

Aplicativo inativado

Caso o aplicativo esteja inativado (conforme seção situação do aplicativo) você não será capaz de realizar nenhum tipo de requisição. Um erro, como o do exemplo abaixo, será retornado através da URL de redirecionamento do aplicativo.

https://www.clientapp.com.br/callback?error=app_inativo&error_description=Este+aplicativo+foi+inativado+temporariamente&state=291e61b56ab3d845622cf137b1e1e2

Usuário não autorizado

Exceções causadas por usuários não autorizados poderão ser redirecionadas para o callback do aplicativo, veja o exemplo abaixo.

https://www.clientapp.com.br/callback?error=UNAUTHORIZED_ERROR&error_description=O+usu%C3%A1rio+n%C3%A3o+possui+autoriza%C3%A7%C3%A3o+para+acessar+os+recursos+requisitados&state=xyz

Isso poderá ocorrer especificamente quando for requisitado um novo authorization_code para um usuário que já concedeu autorização previamente ao aplicativo. Porém, este usuário perdeu alguns privilégios durante este tempo (deixou de ter permissão para algum escopo solicitado na autorização) ou a conta passou para a situação inadimplente.

Obtenção da URL de redirecionamento

Ocorre geralmente quando o client_id da requisição for inválido.

Exceções na obtenção dos tokens de acesso

O formato dos erros retornados durante esta requisição seguem o modelo adotado pela API v3 do Bling, um objeto JSON contendo as informações sobre o erro no body da resposta HTTP.

Este tópico não é uma lista completa de todos os erros que poderão ocorrer durante a requisição dos tokens de acesso, porém, a leitura deste manual poderá ajudar na interpretação da maioria dos erros.

Sintaxe

Independente do grant type (authorization_code ou refresh_token) utilizado, os erros mais comuns durante esta etapa são causados por problemas na sintaxe da requisição. Os exemplos mais comuns são: ausência parâmetros obrigatórios no body ou as credenciais no cabeçalho, grant type inválido, credenciais inválidas, code inexistente ou expirado.

Veja abaixo os objetos JSON retornados nas requisições com erro nas credenciais do aplicativo e authorization_code expirado.

{
	"error": {
		"type": "invalid_client",
		"message": "invalid_client",
		"description": "The client credentials are invalid"
	}
}

{
	"error": {
		"type": "invalid_grant",
		"message": "invalid_grant",
		"description": "The authorization code has expired"
	}
}

Authorization code já utilizado

É permitido que cada authorization_code seja utilizado apenas uma vez. Caso um authorization_code válido (não expirado) for utilizado em uma segunda requisição para obtenção dos tokens de acesso, esta requisição não será válida e por medidas de segurança o usuário vinculado ao code terá o seu acesso revogado. Segue abaixo o JSON retornado neste caso.

{
	"error": {
		"type": "VALIDATION_ERROR",
		"message": "Invalid authorization code",
		"description": "This authorization code has already been used, for security reasons the user has been revoked."
	}
}

Empresa inativa

Assim como não é permitida a geração de um novo authorization_code aos usuários vinculados a empresas com situação diferente de ativa, não será permitida a obtenção de novos tokens de acesso com uso do refresh token. Nestes casos, o JSON abaixo será inserido no retorno.

{
	"error": {
		"type": "UNAUTHORIZED_ERROR",
		"message": "Empresa inativa",
		"description": "A empresa vinculada ao token esta inativa."
	}
}

Obter recurso do usuário

O formato dos erros retornados durante esta requisição seguem o modelo adotado pela API v3 do Bling, um objeto JSON contendo as informações sobre o erro no body da resposta HTTP.

Este tópico detalha os erros causados durante a validação do access_token utilizado na autenticação OAuth, não serão detalhados os demais erros que poderão ocorrer na requisição do recurso, para isso consulte o tópico sobre erros da API v3.

Problemas de sintaxe

Qualquer problema com relação à sintaxe da inserção do access token na requisição.

{
	"error": {
		"type": "invalid_request",
		"message": "invalid_request",
		"description": "Malformed auth header"
	}
}

Token expirou

Access token expirado.

{
	"error": {
		"type": "invalid_token",
		"message": "invalid_token",
		"description": "The access token provided has expired"
	}
}

Utilize o refresh token para gerar uma nova chave a este usuário, veja o tópico refresh token para mais informações.

Token não autorizado

Caso o recurso requisitado não tenha sido autorizado pelo usuário, ou seja, o access_token não possui permissão para acessar o escopo referente a este recurso.

{
	"error": {
		"type": "insufficient_scope",
		"message": "insufficient_scope",
		"description": "The request requires higher privileges than provided by the access token"
	}
}

Gerenciamento

Através do módulo de Aplicativos autorizados é possível gerenciar os aplicativos que foram autorizados a operar a conta.

Na listagem dos aplicativos pode-se revogar acesso a um determinado aplicativo, passando o mouse sobre a linha e clicando em "Revogar".

Clicando sobre um aplicativo, serão exibidas as informações do app, sendo possível também realizar a revogação da autorização de uso.

Reportar

Caso tenha identificado alguma ação maliciosa por parte do aplicativo, na visualização dos detalhes de um aplicativo autorizado, no canto superior direito, é possível reporta-lo para nossa equipe técnica.