«Mostra-me todas as faturas deste mês.» O agente devolve uma tabela com 100 linhas, soma os valores e responde com segurança. Abres alguns documentos no Bling: os números estão certos. Mas ainda falta verificar a palavra mais importante do teu pedido: todas.
Uma resposta pode estar certa em cada linha e errada no conjunto. Se a integração leu apenas a primeira página, não inventou faturas. Omitiu as restantes. Para quem está a preparar o fecho ou a conferir documentos, essa diferença não é um pormenor técnico: muda o trabalho que fica por fazer.
O teste a um agente ligado ao ERP não termina quando ele consegue consultar dados reais. Termina quando consegue demonstrar o que consultou, até onde chegou e o que ficou de fora.
No Bling, 100 registos podem ser só o princípio
Segundo as perguntas frequentes e as boas práticas da API do Bling, consultadas em 19 de outubro de 2026, são devolvidos até 100 registos por pedido por predefinição. Nas consultas que suportam paginação, o parâmetro pagina permite pedir outras páginas e limite controla a quantidade devolvida por pedido.
Isto não significa que 100 seja um máximo absoluto. Significa que uma integração que faça um único pedido, sem tratar a continuação, pode receber uma parte dos resultados e apresentá-la como o conjunto completo.
A paginação é normal: evita transportar uma base de dados inteira em cada consulta. O erro está em confundir o tamanho de uma resposta com o tamanho do universo pesquisado. Receber exatamente 100 linhas não prova que existam apenas 100. Também não prova, por si só, que existam mais. Obriga a verificar a continuação segundo o contrato do endpoint utilizado.
Neste artigo, «faturas» é a expressão do pedido do operador. Num projeto com o Bling, é preciso identificar o recurso concreto — por exemplo, notas fiscais — e confirmar os seus campos, estados e filtros. Não se devem transportar automaticamente categorias fiscais portuguesas para documentos brasileiros.
Um exemplo: 237 documentos, não 100
Considera um cenário de teste fictício, sem dados de clientes: uma empresa tem 237 documentos elegíveis num determinado período. Todos estão em reais, pertencem à mesma empresa e usam o mesmo campo de valor. O conjunto mantém-se estável durante a consulta e o endpoint permite páginas de 100 registos.
| Página com dados | Documentos | Soma do campo de valor escolhido |
| — | —: | —: |
| Primeira | 100 | R$ 18 400 |
| Segunda | 100 | R$ 21 700 |
| Terceira | 37 | R$ 9 600 |
| Conjunto completo | 237 | R$ 49 700 |
Se o agente parar na primeira página, apresenta R$ 18 400. Esse subtotal está aritmeticamente certo. Mas faltam 137 documentos e R$ 31 300 ao conjunto pedido. Nenhuma melhoria na redação da resposta recupera informação que o conector não foi buscar.
Também seria errado transformar automaticamente R$ 49 700 em «faturação líquida», «valor recebido» ou «saldo por cobrar». A soma representa apenas o campo selecionado nos documentos abrangidos. A interpretação depende do recurso, dos estados incluídos e das regras do relatório.
Uma resposta útil, depois de validada a cobertura, seria: «A consulta reuniu 237 documentos únicos no período e nos estados definidos. A soma do campo selecionado é R$ 49 700. A listagem completa está disponível no ficheiro de conferência.» O resumo pode ser curto. A recolha não pode ser cortada em silêncio.
Antes das páginas, define o que significa «todas»
O primeiro problema é de âmbito. «Deste mês» refere-se à emissão, ao vencimento ou a outra data disponível no recurso? Inclui documentos cancelados? Abrange que empresa e que permissões? Qual é o fuso horário usado nos limites do período?
A integração deve traduzir o pedido em filtros explícitos. Quando houver uma ambiguidade que altere o resultado, pergunta ou apresenta o critério configurado. Não deve decidir em silêncio que «todas» significa «as primeiras que a API devolveu».
Depois mantém esses filtros em todas as páginas. Mudar um estado ou perder uma data entre pedidos pode produzir uma lista longa, mas já não responde à mesma pergunta. E uma consulta completa dentro das permissões de um utilizador não é necessariamente uma consulta completa de toda a empresa. Essa fronteira tem de aparecer no resultado.
A ação executada é percorrer, conferir e provar
Numa arquitetura só de leitura, o agente não precisa de emitir nem alterar documentos para executar trabalho útil. Pode percorrer as páginas, reunir identificadores, calcular totais por código e preparar um ficheiro de conferência. A diferença está na execução verificável, não numa frase mais convincente.
O conector deve seguir a condição de fim documentada para o endpoint. Se houver metadados de continuação ou um total fiável, usa-os. Se o contrato determinar que uma página vazia assinala o fim, trata essa resposta como tal. Uma página curta só deve servir de prova de fim quando o comportamento do endpoint o permitir. Não existe uma regra universal que se possa copiar sem verificar.
A documentação geral consultada não garante, por si só, ordenação estável, contagem total ou uma fotografia imutável dos dados durante a leitura. Estas propriedades têm de ser confirmadas no recurso concreto e testadas.
Há ainda uma distinção essencial: uma página vazia não é uma página que falhou. Se um pedido exceder o tempo de espera, ou receber uma rejeição, o conector não pode convertê-lo numa lista vazia e concluir que acabou.
O ERP continua a mudar enquanto lês
Imagina que, entre a primeira e a segunda página, entram novos documentos ou outros mudam de estado. Numa paginação baseada na posição dos registos, essas alterações podem deslocar resultados. O mesmo documento pode aparecer duas vezes; outro pode ficar por ler.
Eliminar duplicados pelo identificador ajuda, mas não recupera o documento omitido. É preciso combinar o que o endpoint realmente oferece: ordenação estável, critérios de corte adequados, comparação com uma exportação de referência ou nova conferência num período sem alterações. Fixar uma data de emissão, por exemplo, não impede necessariamente alterações posteriores aos estados.
Quando não for possível assegurar uma visão consistente, a resposta deve explicar a limitação. «Consulta recolhida entre estas horas, ainda por reconciliar» é menos elegante do que «está tudo». É também mais útil para quem vai tomar uma decisão.
Num armazém, uma listagem incompleta de documentos associados às expedições pode deixar trabalho fora da conferência. Num laboratório ou numa operação de saúde, o mesmo princípio aplica-se às listas dos respetivos sistemas: ver os primeiros resultados não demonstra cobertura. Isto não implica que esses sistemas usem o limite do Bling ou que já exista um conector comum.
Em 19 de outubro de 2026, faltam 12 dias para 31 de outubro e 39 para a Black Friday de 27 de novembro. São referências de calendário, não previsões de volume. Se a tua operação usa estes momentos para fechar ou preparar trabalho, é antes deles que convém testar a passagem do registo 100 para o 101.
Mais páginas não justificam ignorar os limites
A página de limites do Bling documenta 3 pedidos por segundo e 120 000 por dia, por conta, partilhados pelos endpoints e módulos. Ao ultrapassar os limites, os pedidos seguintes não são processados e a API pode devolver HTTP 429.
O agente não é necessariamente a única integração a consumir essa capacidade. Pedir todas as páginas em paralelo, sem coordenação, pode competir com outros processos. O conector precisa de controlar o ritmo, tratar as falhas e limitar as tentativas de recuperação.
Se a recolha for interrompida, deve preservar um estado de resultado parcial. Por exemplo: «Foram recolhidos 200 documentos; a continuação falhou. O total completo ainda não está confirmado.» Se existia uma contagem de referência, pode indicá-la como tal, sem a apresentar como informação acabada de verificar.
Uma nova tentativa também tem de considerar se o conjunto mudou entretanto. Retomar uma página antiga sem revalidar o contexto pode conservar uma omissão. O objetivo não é apenas acabar depressa; é acabar com um resultado que se consiga defender.
Um bot de 25 € não se avalia pelo preço da conversa
A oferta pública da 3HASH consultada para esta análise anuncia 100 € de implementação e 25 €/mês, com IVA, para website e WhatsApp. Descreve conhecimento preparado a partir de informação do negócio, API oficial da Meta e encaminhamento humano. Essa página não documenta uma integração ERP incluída; isso não prova que o fornecedor seja incapaz de a desenvolver.
Também não seria correto dizer que ferramentas de construção de bots nunca têm API. A Landbot, por exemplo, anuncia API e webhooks em determinados planos. Ter acesso HTTP é uma capacidade da ferramenta. Entregar paginação, controlo de permissões, recuperação de falhas e reconciliação é trabalho de integração.
Por isso, um preço superior não prova qualidade. Uma solução barata que passa os testes do teu processo é mais útil do que uma solução cara que devolve a primeira página com confiança. Pede demonstração do resultado, não apenas demonstração da conversa.
«Então basta exportar um ficheiro?»
Por vezes, sim. Se fazes esta conferência uma vez por mês e a exportação nativa já te dá o conjunto necessário, talvez não precises de um agente para esta tarefa. Automatizar sem retirar trabalho real só acrescenta manutenção.
A integração ganha interesse quando a consulta é recorrente, precisa de respeitar acessos diferentes ou deve devolver rapidamente um resultado verificável a quem não trabalha diariamente no ERP. A camada de linguagem interpreta o pedido e explica o resultado; o código do conector recolhe e valida os dados. Os totais não devem depender da capacidade do modelo para contar linhas numa conversa.
É isto que significa estar ancorado nos dados do cliente. Não basta dar ao modelo alguns documentos reais. Também é preciso impedir que apresente uma amostra real como se fosse a totalidade.
O teste que deves pedir antes de aceitar a integração
Prepara um conjunto controlado com resultados conhecidos e testa consultas com zero, 100, 101 e 237 registos. Os números são casos de teste, não medições de clientes. O caso de 100 verifica se o sistema confirma o fim; o de 101 revela se consegue passar da primeira página.
Depois provoca uma falha a meio e confirma que a resposta fica marcada como parcial. Testa também duplicados e alterações durante a leitura. Compara os identificadores obtidos com os do conjunto de referência, além da contagem e da soma: duas listas podem ter o mesmo tamanho e conter documentos diferentes.
O registo de auditoria deve permitir reconstruir quem pediu, em que empresa, com que filtros, quando começou e terminou, que páginas foram processadas e porque se considerou a recolha concluída ou interrompida. Não exige copiar documentos inteiros para os registos técnicos nem guardar credenciais neles.
Na Leiritech, a abordagem é acesso conversacional aos dados do cliente, só de leitura e auditado. O desenho apresentado aqui é uma proposta de implementação e validação; não é a afirmação de que temos um conector Bling pronto nem um caso de cliente já entregue.
Envia para hello@leiritech.com a pergunta que precisas de fazer ao Bling e os critérios da tua listagem, sem credenciais nem documentos pessoais. O próximo passo é definir um teste de completude: que conjunto deve sair, como se confere e o que o sistema deve dizer quando não consegue chegar ao fim.
