Perguntas frequentes

Como gerar o Access Token?

O primeiro passo é a criação de um aplicativo. Após o desenvolvedor irá solicitar por meio do aplicativo, acesso à conta do Bling que deseja operar. Nesse momento o cliente que opera a conta irá fazer login e autorizar o aplicativo a realizar as operações na mesma, retornando de forma automática o authorization code na URL de redirecionamento configurada no aplicativo. Por fim, será necessário o desenvolvedor realizar uma requisição ao authorization server com o authorization code obtido, e então o access token será retornado no formato JSON. Para o passo a passo detalhado, acesse a seção de fluxo de autorização.

Como gerar o client_id e o client_secret?

Após a criação do aplicativo, será exibido ao lado do formulário o client_id e client_secret.

Qual é o formato de retorno das respostas da API?

O formato de retorno é em JSON, conforme o exemplo:

{
	"data": {
		"id": 123,
		"nome": "Bling",
		"numero": 1
	}
}

Quais são os limites da API?

No Bling existem limites de frequência, no qual a regra permite até 3 requisições por segundo e 120 mil requisições por dia. Entretanto, existe também outras validações por bloqueio de IP.

A limitação de API é o processo de limitar o número de requisições que um usuário pode fazer em um determinado período.

Quantos registros são retornados por página em cada requisição?

Por padrão são retornados até 100 registros por requisição.

APIs que possuem paginação irão retornar os resultados em páginas, ou seja, para obter todos os registros serão necessárias mais de uma requisição, informando o parâmetro pagina. Mais informações podem ser encontradas na seção de boas práticas.

Qual é a utilidade do campo state?

A utilidade principal do campo state é evitar cross-site request forgery (CSRF) para o endpoint configurado na URL de redirecionamento do aplicativo. O client app gera um token aleatório e o informa no campo state ao solicitar o Authorization code, após o usuário conceder acesso ao aplicativo, o token é retornado ao client app junto à URL de redirecionamento, dessa forma, é possível verificar que a origem é de fato o Bling.

Além disso, pode ser usado de maneira flexível, já que é possível informar qualquer valor para o campo e reinterpretá-lo no redirecionamento. Por exemplo, criptografando um json contendo um timestamp e um ambiente {"timestamp":1698757251.796,"environment":"dev"}, após o redirecionamento ao client app, é possível descriptografar o state e verificar se o processo foi realizado em tempo hábil e se o ambiente que o usuário está é valido para a utilização do aplicativo.

Preciso criar uma conta no Bling para utilizar a API?

Sim. A utilização da API do Bling requer a criação de uma conta, para cadastro de um aplicativo de visibilidade pública. É necessário também passar por um processo de homologação, o qual assegura a conformidade da conta com os padrões exigidos pela API. Concluída a etapa de testes de 30 dias, a conta permanece ativa, dispensando a necessidade de solicitar isenções para prosseguir com o uso do serviço.