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: 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. Como emitir uma nota de venda com itens de brinde ou bonificação? É possível emitir uma única NF-e com itens de venda e itens de brinde ou bonificação juntos, cada um com seu próprio CFOP, vinculando uma natureza de operação específica a cada item especial do pedido de venda.

1. Cadastre uma natureza de operação com o CFOP e as regras fiscais de brinde/bonificação. Esse cadastro é manual, não existindo endpoint de criação via API. Dessa forma, alinhe os dados com seu contador.
2. Liste as naturezas de operação e localize o id da que foi configurada para esse fim: GET /naturezas-operacoes?situacao=1&descricao=Bonificação.
3. Ao criar ou atualizar o pedido de venda, informe naturezaOperacao.id no item que deve sair como brinde/bonificação. Os demais itens não precisam ter a natureza vinculada pois ao gerar a nota o sistema atribuirá de forma automática, conforme cadastro prévio.

4. Ao gerar a NF-e a partir do pedido, o item que recebeu essa natureza de operação usa o CFOP e as regras fiscais configuradas nela.

A natureza de operação precisa existir e estar ativa (situacao=1), caso contrário a API retorna erro de natureza de operação inválida ou inativa. 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.