Como integrar o Bling com o Google Sheets
Dá para integrar o Bling ao Google Sheets de três formas: conector pronto de automação, script próprio no Apps Script consumindo a API v3 do Bling, ou uma rotina externa que escreve na planilha. O conector resolve fluxo simples em minutos. Script próprio é necessário quando você precisa de histórico, volume alto ou regra de negócio na transformação.
A API v3 usa OAuth, e isso muda o projeto
A versão antiga da API do Bling autenticava com uma chave fixa que você colava no código. A v3 usa OAuth 2.0: você registra um aplicativo, o usuário autoriza uma vez e você recebe um access token de vida curta mais um refresh token para renovar.
A consequência prática é que a integração deixa de ser sem estado. Alguém precisa guardar o token com segurança e renovar antes de expirar. No Apps Script isso significa usar o armazenamento de propriedades do script, nunca uma constante no código, porque quem tiver acesso à planilha enxerga o código.
O teto de 6 minutos do Apps Script
Apps Script encerra a execução ao atingir o limite de tempo da conta, que na conta gratuita é de 6 minutos por execução. Uma sincronização que percorre milhares de pedidos com paginação estoura esse teto e morre no meio, deixando a planilha pela metade.
A saída não é otimizar a chamada, é mudar o desenho: guarde a página em que parou, processe um lote por execução e agende o gatilho para rodar de novo. A rotina passa a ser retomável em vez de tudo ou nada.
Se o volume é grande o bastante para exigir muitos lotes, o Apps Script deixou de ser a ferramenta certa. Uma rotina externa escrevendo na planilha via API do Sheets sai mais simples de manter.
Paginação e limite de requisição
A API do Bling devolve resultado paginado e aplica limite de requisição por segundo e por dia. Um laço que dispara chamada sem pausa recebe erro de excesso de requisição e, dependendo de como o código trata, grava dado parcial sem avisar.
Trate o código de erro de limite como caso esperado, não como falha: aguarde e tente de novo com intervalo crescente. E confira os valores vigentes na documentação do Bling, porque limite de API muda sem aviso.
Escrever na planilha do jeito certo
O erro de performance mais comum não está na API do Bling, está na escrita. Chamar a função de gravação uma vez por linha faz uma chamada de serviço por pedido e é ordens de grandeza mais lento que montar a matriz inteira em memória e gravar de uma vez só.
Grave sempre em bloco. Além de rápido, reduz o risco de estourar o tempo de execução no meio da escrita e deixar a planilha inconsistente.
Passo a passo com Apps Script
- Registre o aplicativo no Bling. No painel do Bling, crie um aplicativo para obter client id e client secret, e cadastre a URL de retorno que o seu fluxo de autorização vai usar.
- Faça a autorização uma vez. Percorra o fluxo de autorização do OAuth com o usuário logado no Bling e troque o código recebido pelo par de access token e refresh token.
- Guarde os tokens fora do código. Salve os dois tokens no armazenamento de propriedades do script. Nunca deixe token em constante no arquivo, porque qualquer pessoa com acesso de edição à planilha lê o código.
- Implemente a renovação do token. Antes de cada chamada, verifique a validade do access token e renove usando o refresh token quando necessário. Grave o novo par imediatamente, porque o refresh token pode ser rotacionado.
- Busque os dados em lotes com paginação. Consuma o endpoint desejado percorrendo as páginas e guarde o número da última página processada. Trate o erro de limite de requisição aguardando e repetindo, em vez de abortar.
- Grave na planilha em bloco. Acumule as linhas numa matriz em memória e faça uma única gravação no intervalo de destino. Evite gravar linha a linha.
- Agende o gatilho e monitore. Crie um gatilho por tempo com a frequência necessária e registre em uma aba de log o horário, a página processada e os erros. Sem log, a falha silenciosa só aparece quando alguém desconfia do número.
Conector pronto, script próprio ou rotina externa
A escolha depende de três coisas: volume, se você precisa de histórico e se existe regra de negócio entre o Bling e a planilha.
| Abordagem | Custo | Prazo | Onde para de servir |
|---|---|---|---|
| Conector pronto de automação | Assinatura mensal, cresce por volume de tarefa | Minutos | Ótimo para "criou pedido, adiciona linha". Ruim para carga histórica, transformação de dados e reprocessamento. |
| Apps Script na própria planilha | Zero de licença, custo em tempo de desenvolvimento | 2 a 5 dias | Teto de tempo por execução e cotas diárias. Código vive dentro da planilha, sem revisão nem versionamento decente. |
| Rotina externa escrevendo na planilha | Desenvolvimento mais hospedagem barata | 1 a 2 semanas | Sem limite de tempo de execução e com log de verdade. Exige um lugar para rodar e alguém para manter. |
| Trocar a planilha por um painel | Mais alto na primeira entrega | 2 a 4 semanas | Resolve controle de acesso e volume, mas tira a liberdade de quem gosta de mexer na planilha. Só vale quando a planilha já virou gargalo. |
Perguntas frequentes
Referências
Quer isso rodando na sua operação?
Escopo, prazo e preço travados antes de começar, com 90 dias de garantia.
Quero automatizar essa planilha