{"id":664,"date":"2026-10-19T09:00:00","date_gmt":"2026-10-19T09:00:00","guid":{"rendered":"https:\/\/leiritech.pt\/blog\/bling-lista-completa-alem-primeiros-100"},"modified":"2026-10-19T09:00:00","modified_gmt":"2026-10-19T09:00:00","slug":"bling-lista-completa-alem-primeiros-100","status":"publish","type":"post","link":"https:\/\/leiritech.pt\/blog\/bling-lista-completa-alem-primeiros-100","title":{"rendered":"Bling: a lista completa n\u00e3o acaba nos primeiros 100"},"content":{"rendered":"

\u00abMostra-me todas as faturas deste m\u00eas.\u00bb O agente devolve uma tabela com 100 linhas, soma os valores e responde com seguran\u00e7a. Abres alguns documentos no Bling: os n\u00fameros est\u00e3o certos. Mas ainda falta verificar a palavra mais importante do teu pedido: todas<\/strong>.<\/p>\n

Uma resposta pode estar certa em cada linha e errada no conjunto. Se a integra\u00e7\u00e3o leu apenas a primeira p\u00e1gina, n\u00e3o inventou faturas. Omitiu as restantes. Para quem est\u00e1 a preparar o fecho ou a conferir documentos, essa diferen\u00e7a n\u00e3o \u00e9 um pormenor t\u00e9cnico: muda o trabalho que fica por fazer.<\/p>\n

O teste a um agente ligado ao ERP n\u00e3o termina quando ele consegue consultar dados reais. Termina quando consegue demonstrar o que consultou, at\u00e9 onde chegou e o que ficou de fora.<\/p>\n

\"Uma<\/p>\n

No Bling, 100 registos podem ser s\u00f3 o princ\u00edpio<\/h2>\n

Segundo as perguntas frequentes e as boas pr\u00e1ticas da API do Bling, consultadas em 19 de outubro de 2026, s\u00e3o devolvidos at\u00e9 100 registos por pedido por predefini\u00e7\u00e3o<\/strong>. Nas consultas que suportam pagina\u00e7\u00e3o, o par\u00e2metro pagina<\/code> permite pedir outras p\u00e1ginas e limite<\/code> controla a quantidade devolvida por pedido.<\/p>\n

Isto n\u00e3o significa que 100 seja um m\u00e1ximo absoluto. Significa que uma integra\u00e7\u00e3o que fa\u00e7a um \u00fanico pedido, sem tratar a continua\u00e7\u00e3o, pode receber uma parte dos resultados e apresent\u00e1-la como o conjunto completo.<\/p>\n

A pagina\u00e7\u00e3o \u00e9 normal: evita transportar uma base de dados inteira em cada consulta. O erro est\u00e1 em confundir o tamanho de uma resposta com o tamanho do universo pesquisado. Receber exatamente 100 linhas n\u00e3o prova que existam apenas 100. Tamb\u00e9m n\u00e3o prova, por si s\u00f3, que existam mais. Obriga a verificar a continua\u00e7\u00e3o segundo o contrato do endpoint utilizado.<\/p>\n

Neste artigo, \u00abfaturas\u00bb \u00e9 a express\u00e3o do pedido do operador. Num projeto com o Bling, \u00e9 preciso identificar o recurso concreto \u2014 por exemplo, notas fiscais \u2014 e confirmar os seus campos, estados e filtros. N\u00e3o se devem transportar automaticamente categorias fiscais portuguesas para documentos brasileiros.<\/p>\n

Um exemplo: 237 documentos, n\u00e3o 100<\/h2>\n

Considera um cen\u00e1rio de teste fict\u00edcio<\/strong>, sem dados de clientes: uma empresa tem 237 documentos eleg\u00edveis num determinado per\u00edodo. Todos est\u00e3o em reais, pertencem \u00e0 mesma empresa e usam o mesmo campo de valor. O conjunto mant\u00e9m-se est\u00e1vel durante a consulta e o endpoint permite p\u00e1ginas de 100 registos.<\/p>\n

| P\u00e1gina com dados | Documentos | Soma do campo de valor escolhido |
\n| — | —: | —: |
\n| Primeira | 100 | R$ 18 400 |
\n| Segunda | 100 | R$ 21 700 |
\n| Terceira | 37 | R$ 9 600 |
\n| Conjunto completo | 237 | R$ 49 700 |<\/p>\n

Se o agente parar na primeira p\u00e1gina, apresenta R$ 18 400. Esse subtotal est\u00e1 aritmeticamente certo. Mas faltam 137 documentos e R$ 31 300 ao conjunto pedido. Nenhuma melhoria na reda\u00e7\u00e3o da resposta recupera informa\u00e7\u00e3o que o conector n\u00e3o foi buscar.<\/p>\n

Tamb\u00e9m seria errado transformar automaticamente R$ 49 700 em \u00abfatura\u00e7\u00e3o l\u00edquida\u00bb, \u00abvalor recebido\u00bb ou \u00absaldo por cobrar\u00bb. A soma representa apenas o campo selecionado nos documentos abrangidos. A interpreta\u00e7\u00e3o depende do recurso, dos estados inclu\u00eddos e das regras do relat\u00f3rio.<\/p>\n

Uma resposta \u00fatil, depois de validada a cobertura, seria: \u00abA consulta reuniu 237 documentos \u00fanicos no per\u00edodo e nos estados definidos. A soma do campo selecionado \u00e9 R$ 49 700. A listagem completa est\u00e1 dispon\u00edvel no ficheiro de confer\u00eancia.\u00bb O resumo pode ser curto. A recolha n\u00e3o pode ser cortada em sil\u00eancio.<\/p>\n

Antes das p\u00e1ginas, define o que significa \u00abtodas\u00bb<\/h2>\n

O primeiro problema \u00e9 de \u00e2mbito. \u00abDeste m\u00eas\u00bb refere-se \u00e0 emiss\u00e3o, ao vencimento ou a outra data dispon\u00edvel no recurso? Inclui documentos cancelados? Abrange que empresa e que permiss\u00f5es? Qual \u00e9 o fuso hor\u00e1rio usado nos limites do per\u00edodo?<\/p>\n

A integra\u00e7\u00e3o deve traduzir o pedido em filtros expl\u00edcitos. Quando houver uma ambiguidade que altere o resultado, pergunta ou apresenta o crit\u00e9rio configurado. N\u00e3o deve decidir em sil\u00eancio que \u00abtodas\u00bb significa \u00abas primeiras que a API devolveu\u00bb.<\/p>\n

Depois mant\u00e9m esses filtros em todas as p\u00e1ginas. Mudar um estado ou perder uma data entre pedidos pode produzir uma lista longa, mas j\u00e1 n\u00e3o responde \u00e0 mesma pergunta. E uma consulta completa dentro das permiss\u00f5es de um utilizador n\u00e3o \u00e9 necessariamente uma consulta completa de toda a empresa. Essa fronteira tem de aparecer no resultado.<\/p>\n

A a\u00e7\u00e3o executada \u00e9 percorrer, conferir e provar<\/h2>\n

Numa arquitetura s\u00f3 de leitura, o agente n\u00e3o precisa de emitir nem alterar documentos para executar trabalho \u00fatil. Pode percorrer as p\u00e1ginas, reunir identificadores, calcular totais por c\u00f3digo e preparar um ficheiro de confer\u00eancia. A diferen\u00e7a est\u00e1 na execu\u00e7\u00e3o verific\u00e1vel, n\u00e3o numa frase mais convincente.<\/p>\n

O conector deve seguir a condi\u00e7\u00e3o de fim documentada para o endpoint. Se houver metadados de continua\u00e7\u00e3o ou um total fi\u00e1vel, usa-os. Se o contrato determinar que uma p\u00e1gina vazia assinala o fim, trata essa resposta como tal. Uma p\u00e1gina curta s\u00f3 deve servir de prova de fim quando o comportamento do endpoint o permitir. N\u00e3o existe uma regra universal que se possa copiar sem verificar.<\/p>\n

A documenta\u00e7\u00e3o geral consultada n\u00e3o garante, por si s\u00f3, ordena\u00e7\u00e3o est\u00e1vel, contagem total ou uma fotografia imut\u00e1vel dos dados durante a leitura. Estas propriedades t\u00eam de ser confirmadas no recurso concreto e testadas.<\/p>\n

H\u00e1 ainda uma distin\u00e7\u00e3o essencial: uma p\u00e1gina vazia n\u00e3o \u00e9 uma p\u00e1gina que falhou<\/strong>. Se um pedido exceder o tempo de espera, ou receber uma rejei\u00e7\u00e3o, o conector n\u00e3o pode convert\u00ea-lo numa lista vazia e concluir que acabou.<\/p>\n

O ERP continua a mudar enquanto l\u00eas<\/h2>\n

Imagina que, entre a primeira e a segunda p\u00e1gina, entram novos documentos ou outros mudam de estado. Numa pagina\u00e7\u00e3o baseada na posi\u00e7\u00e3o dos registos, essas altera\u00e7\u00f5es podem deslocar resultados. O mesmo documento pode aparecer duas vezes; outro pode ficar por ler.<\/p>\n

Eliminar duplicados pelo identificador ajuda, mas n\u00e3o recupera o documento omitido. \u00c9 preciso combinar o que o endpoint realmente oferece: ordena\u00e7\u00e3o est\u00e1vel, crit\u00e9rios de corte adequados, compara\u00e7\u00e3o com uma exporta\u00e7\u00e3o de refer\u00eancia ou nova confer\u00eancia num per\u00edodo sem altera\u00e7\u00f5es. Fixar uma data de emiss\u00e3o, por exemplo, n\u00e3o impede necessariamente altera\u00e7\u00f5es posteriores aos estados.<\/p>\n

Quando n\u00e3o for poss\u00edvel assegurar uma vis\u00e3o consistente, a resposta deve explicar a limita\u00e7\u00e3o. \u00abConsulta recolhida entre estas horas, ainda por reconciliar\u00bb \u00e9 menos elegante do que \u00abest\u00e1 tudo\u00bb. \u00c9 tamb\u00e9m mais \u00fatil para quem vai tomar uma decis\u00e3o.<\/p>\n

\"Uma<\/p>\n

Num armaz\u00e9m, uma listagem incompleta de documentos associados \u00e0s expedi\u00e7\u00f5es pode deixar trabalho fora da confer\u00eancia. Num laborat\u00f3rio ou numa opera\u00e7\u00e3o de sa\u00fade, o mesmo princ\u00edpio aplica-se \u00e0s listas dos respetivos sistemas: ver os primeiros resultados n\u00e3o demonstra cobertura. Isto n\u00e3o implica que esses sistemas usem o limite do Bling ou que j\u00e1 exista um conector comum.<\/p>\n

Em 19 de outubro de 2026, faltam 12 dias para 31 de outubro e 39 para a Black Friday de 27 de novembro. S\u00e3o refer\u00eancias de calend\u00e1rio, n\u00e3o previs\u00f5es de volume. Se a tua opera\u00e7\u00e3o usa estes momentos para fechar ou preparar trabalho, \u00e9 antes deles que conv\u00e9m testar a passagem do registo 100 para o 101.<\/p>\n

Mais p\u00e1ginas n\u00e3o justificam ignorar os limites<\/h2>\n

A p\u00e1gina de limites do Bling documenta 3 pedidos por segundo e 120 000 por dia, por conta<\/strong>, partilhados pelos endpoints e m\u00f3dulos. Ao ultrapassar os limites, os pedidos seguintes n\u00e3o s\u00e3o processados e a API pode devolver HTTP 429.<\/p>\n

O agente n\u00e3o \u00e9 necessariamente a \u00fanica integra\u00e7\u00e3o a consumir essa capacidade. Pedir todas as p\u00e1ginas em paralelo, sem coordena\u00e7\u00e3o, pode competir com outros processos. O conector precisa de controlar o ritmo, tratar as falhas e limitar as tentativas de recupera\u00e7\u00e3o.<\/p>\n

Se a recolha for interrompida, deve preservar um estado de resultado parcial. Por exemplo: \u00abForam recolhidos 200 documentos; a continua\u00e7\u00e3o falhou. O total completo ainda n\u00e3o est\u00e1 confirmado.\u00bb Se existia uma contagem de refer\u00eancia, pode indic\u00e1-la como tal, sem a apresentar como informa\u00e7\u00e3o acabada de verificar.<\/p>\n

Uma nova tentativa tamb\u00e9m tem de considerar se o conjunto mudou entretanto. Retomar uma p\u00e1gina antiga sem revalidar o contexto pode conservar uma omiss\u00e3o. O objetivo n\u00e3o \u00e9 apenas acabar depressa; \u00e9 acabar com um resultado que se consiga defender.<\/p>\n

Um bot de 25 \u20ac n\u00e3o se avalia pelo pre\u00e7o da conversa<\/h2>\n

A oferta p\u00fablica da 3HASH consultada para esta an\u00e1lise anuncia 100 \u20ac de implementa\u00e7\u00e3o e 25 \u20ac\/m\u00eas, com IVA, para website e WhatsApp. Descreve conhecimento preparado a partir de informa\u00e7\u00e3o do neg\u00f3cio, API oficial da Meta e encaminhamento humano. Essa p\u00e1gina n\u00e3o documenta uma integra\u00e7\u00e3o ERP inclu\u00edda; isso n\u00e3o prova que o fornecedor seja incapaz de a desenvolver.<\/p>\n

Tamb\u00e9m n\u00e3o seria correto dizer que ferramentas de constru\u00e7\u00e3o de bots nunca t\u00eam API. A Landbot, por exemplo, anuncia API e webhooks em determinados planos. Ter acesso HTTP \u00e9 uma capacidade da ferramenta. Entregar pagina\u00e7\u00e3o, controlo de permiss\u00f5es, recupera\u00e7\u00e3o de falhas e reconcilia\u00e7\u00e3o \u00e9 trabalho de integra\u00e7\u00e3o.<\/p>\n

Por isso, um pre\u00e7o superior n\u00e3o prova qualidade. Uma solu\u00e7\u00e3o barata que passa os testes do teu processo \u00e9 mais \u00fatil do que uma solu\u00e7\u00e3o cara que devolve a primeira p\u00e1gina com confian\u00e7a. Pede demonstra\u00e7\u00e3o do resultado, n\u00e3o apenas demonstra\u00e7\u00e3o da conversa.<\/p>\n

\u00abEnt\u00e3o basta exportar um ficheiro?\u00bb<\/h2>\n

Por vezes, sim. Se fazes esta confer\u00eancia uma vez por m\u00eas e a exporta\u00e7\u00e3o nativa j\u00e1 te d\u00e1 o conjunto necess\u00e1rio, talvez n\u00e3o precises de um agente para esta tarefa. Automatizar sem retirar trabalho real s\u00f3 acrescenta manuten\u00e7\u00e3o.<\/p>\n

A integra\u00e7\u00e3o ganha interesse quando a consulta \u00e9 recorrente, precisa de respeitar acessos diferentes ou deve devolver rapidamente um resultado verific\u00e1vel a quem n\u00e3o trabalha diariamente no ERP. A camada de linguagem interpreta o pedido e explica o resultado; o c\u00f3digo do conector recolhe e valida os dados. Os totais n\u00e3o devem depender da capacidade do modelo para contar linhas numa conversa.<\/p>\n

\u00c9 isto que significa estar ancorado nos dados do cliente. N\u00e3o basta dar ao modelo alguns documentos reais. Tamb\u00e9m \u00e9 preciso impedir que apresente uma amostra real como se fosse a totalidade.<\/p>\n

\"Um<\/p>\n

O teste que deves pedir antes de aceitar a integra\u00e7\u00e3o<\/h2>\n

Prepara um conjunto controlado com resultados conhecidos e testa consultas com zero, 100, 101 e 237 registos. Os n\u00fameros s\u00e3o casos de teste, n\u00e3o medi\u00e7\u00f5es de clientes. O caso de 100 verifica se o sistema confirma o fim; o de 101 revela se consegue passar da primeira p\u00e1gina.<\/p>\n

Depois provoca uma falha a meio e confirma que a resposta fica marcada como parcial. Testa tamb\u00e9m duplicados e altera\u00e7\u00f5es durante a leitura. Compara os identificadores obtidos com os do conjunto de refer\u00eancia, al\u00e9m da contagem e da soma: duas listas podem ter o mesmo tamanho e conter documentos diferentes.<\/p>\n

O registo de auditoria deve permitir reconstruir quem pediu, em que empresa, com que filtros, quando come\u00e7ou e terminou, que p\u00e1ginas foram processadas e porque se considerou a recolha conclu\u00edda ou interrompida. N\u00e3o exige copiar documentos inteiros para os registos t\u00e9cnicos nem guardar credenciais neles.<\/p>\n

Na Leiritech, a abordagem \u00e9 acesso conversacional aos dados do cliente, s\u00f3 de leitura e auditado. O desenho apresentado aqui \u00e9 uma proposta de implementa\u00e7\u00e3o e valida\u00e7\u00e3o; n\u00e3o \u00e9 a afirma\u00e7\u00e3o de que temos um conector Bling pronto nem um caso de cliente j\u00e1 entregue.<\/p>\n

Envia para hello@leiritech.com a pergunta que precisas de fazer ao Bling e os crit\u00e9rios da tua listagem, sem credenciais nem documentos pessoais.<\/strong> O pr\u00f3ximo passo \u00e9 definir um teste de completude: que conjunto deve sair, como se confere e o que o sistema deve dizer quando n\u00e3o consegue chegar ao fim.<\/p>\n","protected":false},"excerpt":{"rendered":"

O agente encontrou 100 faturas no Bling. Eram todas? V\u00ea como testar pagina\u00e7\u00e3o, reconciliar totais e detetar uma resposta incompleta antes do fecho.<\/p>\n","protected":false},"author":1,"featured_media":660,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[42],"tags":[44,839,842,841,840,838],"class_list":["post-664","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-integracao","tag-agente-ia-erp","tag-bling-100-registos","tag-conferencia-de-faturas","tag-integracao-bling-ia","tag-listar-todas-as-notas-fiscais-bling","tag-paginacao-api-bling"],"_links":{"self":[{"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/posts\/664","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/comments?post=664"}],"version-history":[{"count":0,"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/posts\/664\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/media\/660"}],"wp:attachment":[{"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/media?parent=664"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/categories?post=664"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/leiritech.pt\/blog\/wp-json\/wp\/v2\/tags?post=664"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}