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. Inscrição Caso você ainda não possua uma conta no Bling clique aqui e faça a sua inscrição. 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

1. Acesse a Central de Extensões
2. Clique em "Área do Integrador"

Na tela de cadastro de aplicativos clique no botão Criar aplicativo. Visibilidade Escolha a visibilidade do aplicativo: Clique em próximo. Na sequência preencha os seguintes dados do aplicativo:

• Logo: Exibido aos usuários do aplicativo.
• Nome: Exibido aos seus usuários.
• Categoria: Classificação de negócio.
• Descrição: Detalhamento das principais características e finalidades deste aplicativo.
• Descrição curta: Descrição curta do aplicativo, utilizada na Central de Extensões.
• Link de redirecionamento: Utilizado na etapa de autorização.
• Link da homepage: Endereço do site do aplicativo.
• Link do manual: Link para o manual do aplicativo.
• Link do vídeo demonstrativo: Vídeo do Youtube ou Vimeo que apresenta as funcionalidades do aplicativo.
• Nome do desenvolvedor: Nome do desenvolvedor do aplicativo.
• Email: Email para eventuais contatos do nosso time.
• Celular: Celular para eventuais contatos do nosso time.
• 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. Categorias As categorias são utilizadas para facilitar o cliente na busca por um aplicativo, sendo elas: Imagens do aplicativo Utilizadas somente em aplicativos públicos. As imagens do aplicativo são exibidas na tela de contratação do aplicativo e podem ser usadas como uma forma de divulgar as funcionalidades presentes no sistema. É permitido realizar o upload de até cinco imagens. Exemplo de aplicativo com imagens: 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. Modelo de manual Informações do aplicativo Após a criação do aplicativo, a aba "Informações do app" ficará disponível. Atente-se ao Client Id e ao 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 usuários, será solicitada 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. Essa 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 Redefinir client secret. Após pressionar o botão Redefinir 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 Com a exclusão do aplicativo, todos os tokens de acesso dos usuários serão automaticamente revogados. Para excluir, na aba "Informações do app", ao confirmar a ciência da ação, o botão Excluir aplicativo será exibido. 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 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: 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: 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: Exemplo de URL usada como callback com os parâmetros utilizados no retorno do authorization server: 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: 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: 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: 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. 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. 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: Exemplo de uma requisição cURL para a API de contatos: Revogando o access token É possível revogar um access_token ou refresh_token para impedir que um usuário ou uma empresa continuem acessando a API. Essa funcionalidade garante que apenas os tokens desejados sejam invalidados. Para revogar um token, o client app deve realizar uma requisição POST para o endpoint /oauth/revoke, utilizando o esquema "Basic" de autenticação HTTP para fornecer suas credenciais, conforme exemplo: Se essa requisição for bem-sucedida, o token informado será revogado, impedindo seu uso para novas requisições na API. Revogação avançada Para atender a necessidade de remoção de todos os tokens associados a um usuário ou empresa, foram adicionados os parâmetros revoke_action e revoke_target, que ampliam o escopo da revogação. Minhas Instalações Gerenciamento Através da aba Minhas instalações da Central de Extensões é possível gerenciar os aplicativos que foram autorizados a operar a conta. Ao clicar sobre o menu de contexto de uma instalação, será possível reportá-lo, desinstalá-lo ou reautenticá-lo, caso os códigos de acesso tenham expirados e seja preciso autorizar o aplicativo novamente.