Este texto registra o que os levantamentos públicos de 2025 dizem sobre apps feitos com IA por pessoas sem formação técnica, quais sintomas se repetem e por onde começar a arrumar. É o primeiro de uma série. Os dados citados são de relatórios e relatos abertos. Os dois casos vistos de perto vêm de trabalhos nossos.

Resumo

• Os sintomas se repetem: bug atrás de bug, qualquer mudança quebra tudo, sem versionamento, sem saber se está seguro, sem saber colocar no ar.
• Em outubro de 2025, uma varredura da Escape em mais de 5.600 apps públicos feitos em plataformas de IA achou mais de 2.000 vulnerabilidades.
• Em julho de 2025, um teste da Veracode com mais de 100 modelos de IA mostrou que o código gerado escolheu a opção insegura em 45% das tarefas.
• Na pesquisa do Stack Overflow de 2025, 46% dos desenvolvedores disseram não confiar na precisão do que a IA produz, e 66% apontaram respostas “quase certas” como o problema principal.
• Os problemas mudam conforme a ferramenta: plataforma no navegador, agente no computador ou código colado de um chat. Cada um tem um post nesta série.
• O caminho é o mesmo em todos: diagnosticar antes de editar, travar o que funciona, corrigir uma coisa por vez. Na nossa avaliação, refazer do zero raramente compensa.

Os sintomas

Os relatos públicos, de fóruns a boletins de segurança, descrevem, com frequência, a mesma lista. Em geral os sintomas chegam juntos.

Bug atrás de bug. A pessoa pede uma correção, a IA mexe em dez arquivos, e algo que funcionava para de funcionar. A próxima correção repete o ciclo. Sem testes automatizados, ninguém sabe o que a mudança afetou até um usuário reclamar.

Qualquer alteração quebra tudo. É o mesmo sintoma visto de outro ângulo. O código gerado em uma única conversa longa tende a ter funções que dependem umas das outras de formas que ninguém mapeou, porque ninguém leu.

Sem versionamento. Não há histórico. A versão que funcionava na terça não existe mais depois da mudança de quarta. Quem usa o Git, o sistema de controle de versões que a documentação do GitHub explica para iniciantes, tem cada estado guardado com data e descrição. Quem não usa só tem o estado atual.

Sem saber se está seguro. O app pede login, então parece protegido. Mas o banco pode estar acessível a quem souber o endereço, as chaves de serviços pagos podem estar no código que o navegador baixa, e dados de um cliente podem aparecer para outro ao trocar um número na URL. Um caso que vimos: um site com um endereço de recibos numerados em sequência. Trocando o número, qualquer pessoa abria o recibo de qualquer cliente, sem estar logada. A tela de login protegia a tela, não o dado.

Sem saber colocar no ar, ou tirar. A plataforma hospeda, e a pessoa não sabe o que acontece se parar de pagar, como levar o app para outro lugar ou como fazer uma cópia do banco.

Uma funcionalidade que não sai. Integrar pagamento, enviar e-mail, importar uma planilha. A IA tenta, quebra outra coisa, tenta de novo. Um relato em português no TabNews, de um engenheiro civil, conta mais de 5.000 créditos da Manus gastos em semanas num mapa interativo que nunca chegou a funcionar.

O que os números dizem

Os sintomas não são impressão de quem está frustrado. Há medições.

Vulnerabilidades em escala. Em outubro de 2025, a empresa de segurança Escape publicou a metodologia de uma varredura em mais de 5.600 aplicações públicas feitas em plataformas de criação por IA, cerca de 4.000 delas na Lovable. Resultado: mais de 2.000 vulnerabilidades, mais de 400 segredos expostos e 175 casos de dados pessoais acessíveis, incluindo registros médicos e dados bancários. Os apps funcionavam. O problema não aparecia na tela.

O código gerado escolhe o caminho inseguro. Em julho de 2025, a Veracode publicou um teste com 80 tarefas de programação em mais de 100 modelos de IA. Quando havia um jeito seguro e um inseguro de resolver a tarefa, o modelo escolheu o inseguro em 45% dos casos. A taxa não melhorou com modelos mais novos, embora o código sintaticamente correto tenha melhorado. É um estudo de uma empresa que vende ferramentas de segurança, com tarefas escolhidas por ela, mas o resultado é coerente, na nossa leitura, com o que a varredura da Escape achou em apps publicados.

Quem programa também desconfia. A pesquisa anual do Stack Overflow de 2025, com cerca de 49 mil respostas, mostra que 84% dos desenvolvedores usam ou planejam usar IA, mas 46% não confiam na precisão do que ela produz. O problema mais citado, por 66%, foi a resposta “quase certa, mas não exatamente”. Quem sabe programar percebe o quase. Quem não sabe só percebe quando quebra.

Mais rápido nem sempre. Em julho de 2025, a METR publicou um experimento controlado com 16 desenvolvedores experientes e 246 tarefas reais. Com IA, levaram 19% mais tempo, e ainda assim acharam que tinham sido 20% mais rápidos. A amostra é pequena e os autores pedem cautela, mas o resultado explica uma sensação comum: o progresso parece grande enquanto se conversa com a IA, e pequeno quando se olha o que ficou pronto.

Incidentes com nome. Em maio de 2025, o NVD, o banco de vulnerabilidades do governo americano, registrou uma falha em apps gerados pela Lovable: tabelas de banco sem a proteção por linha, legíveis e graváveis por qualquer pessoa sem login. A Lovable contesta o registro, dizendo que cada cliente é responsável pelos próprios dados. Em julho de 2025, a Wiz encontrou na Base44 uma falha de autenticação que dava acesso a apps privados com um identificador público. Foi corrigida em 24 horas. No mesmo mês, o registro de incidentes da OCDE documentou um agente da Replit que apagou um banco de dados em uso durante um teste, contra a instrução explícita do usuário. A Replit respondeu separando bancos de desenvolvimento e produção.

Nenhum desses casos é exclusivo de uma plataforma. São o mesmo problema: código e configuração que ninguém revisou, em produção, com dados de gente.

E não é exclusivo de quem não programa. Um caso que vimos era de um programador que trabalhava sozinho: o app baixava a coleção inteira do banco para o navegador de cada usuário, o que expunha os dados de todos e gerou uma conta de leituras que ele só notou quando cresceu. Saber programar não substitui olhar. A diferença é que quem sabe tem como olhar.

Três situações, três posts

O que fazer depende de como o app foi feito. Nesta série, separamos três situações.

Plataforma no navegador. Lovable, Bolt, Base44, Replit, v0. A pessoa nunca viu o código. Paga em créditos, hospeda na plataforma, usa o banco que a plataforma criou. O problema central é a dependência: não sabe o que custa, não sabe sair, não sabe o que está exposto.

Agente no computador. Cursor, Claude Code, Codex, Windsurf. O código está na máquina da pessoa, o que já é meio caminho. Falta método: sem Git, sem testes, conversas de horas num só chat, “aplicar tudo” sem ler. O problema central é organização.

Código colado de um chat. ChatGPT ou Gemini no navegador, e o código vai para uma planilha, um site em WordPress, um fluxo de automação, um script que roda no notebook de alguém. Não há projeto. O problema central é juntar o que está espalhado antes de qualquer outra coisa.

Por onde começar, em qualquer caso

A ordem é a mesma nos três.

1. Diagnosticar antes de editar. Listar o que existe: telas, rotas, tabelas, integrações, onde está hospedado, quem tem acesso. Pedir à IA que “conserte” antes disso é mais uma mudança sem controle.
2. Versionar o estado atual. Antes de qualquer alteração, o código vai para um repositório Git. É o ponto de retorno. O livro do Git em português é gratuito e os dois primeiros capítulos bastam para entender o que isso significa.
3. Travar o que funciona. Testes que registram o comportamento atual das partes que estão certas. Daí em diante, qualquer mudança que quebrar algo avisa na hora, e não pelo cliente. Rodar esses testes a cada commit, de forma automática, é o que mostramos no post sobre o build do Tauri no GitHub Actions.
4. Olhar a segurança com lista. O OWASP Top 10 é a lista pública das dez categorias de falha mais comuns em aplicações web. Controle de acesso quebrado é a primeira da lista, e é o tipo de falha dos incidentes citados acima: a tabela sem RLS, o acesso indevido na Base44 e os recibos abertos.
5. Corrigir uma coisa por vez, com o teste rodando a cada passo. Se quebrou, volta. Se passou, guarda.
6. Só depois, decidir o que muda de lugar. Sair da plataforma, trocar o banco, simplificar. Com o app travado e versionado, essa decisão fica barata. Antes, é um salto no escuro.

Refazer do zero é a tentação quando o diagnóstico assusta. Na nossa experiência, costuma ser um erro: joga fora o que já está certo, repete os mesmos problemas com a mesma ferramenta e não deixa nada aprendido. A exceção é quando o diagnóstico mostra que a solução inteira era maior do que o problema, e uma planilha ou um formulário resolvem. Isso acontece, e é bom quando acontece.

O que isto não resolve

Nada acima torna o app bom. Torna o app conhecido, versionado e testado, que é o que permite melhorá-lo sem medo. Também não substitui alguém que leia o código: a IA que gerou os problemas não vai achar todos eles sozinha.

Como verificamos

Este post é um levantamento de fontes públicas, não uma medição nossa. As fontes foram consultadas em 16 de outubro de 2026: a metodologia da Escape de outubro de 2025, o comunicado da Veracode de 30 de julho de 2025, a pesquisa do Stack Overflow de 2025, o estudo da METR de 10 de julho de 2025, o registro CVE-2025-48757 no NVD, a cobertura do The Hacker News sobre a Base44 e o registro de incidentes da OCDE sobre a Replit. Números que só encontramos em páginas de empresas que vendem serviços de correção ficaram de fora. Os casos apresentados como vistos de perto, o dos recibos e o do app em Firebase, são de trabalhos nossos. Não medimos nenhum app de terceiros para este texto. A VirtuaIRES não tem vínculo com nenhuma das plataformas ou empresas citadas.

Um exemplo do que uma IA pode fazer com segurança quando o acesso aos dados é desenhado antes está no post sobre perguntar ao ChatGPT sobre os dados do sistema. Organizar e completar um sistema que começou com IA é parte do que fazemos em soluções com IA.

Este texto registra o que cerca de 380 builds válidos, em 24 lotes, mostraram entre 10 e 12 de setembro de 2026. Cada número abaixo é a mediana de pelo menos 2 amostras, e cada afirmação traz o grau de confiança que o registro de evidências dá a ela. O app é pequeno, com um frontend trivial, e isso limita o que os números dizem.

Resumo

• Runner de 4 núcleos, sem cache, app pequeno: 3 a 5,5 minutos. O cargo é quase tudo.
• Um cache do target/ corta 55 a 65% de um commit comum. rust-cache e actions/cache empatam.
• No Linux, não gerar AppImage e rpm economiza 1m14s, mais que qualquer flag.
• codegen-units = 1 é a opção cara do perfil de release. LTO fat custa bem menos.
• panic = "abort" corta o binário do Windows pela metade.
• sccache, troca de linker e corte de dependências não ajudaram.
• A variação entre runners é de 5 a 30%, até 40% no macOS. Diferença abaixo de 10% é ruído.

Onde o tempo vai

Um build frio, sem cache, num runner de 4 núcleos, estágio por estágio:

Confiança alta. O apt, que muita gente aponta como o vilão do Linux, custa 33 segundos. O cargo custa de 3 a 5 minutos, e dentro dele o piso é a crate do app, que carrega o runtime do Tauri monomorfizado: de 40 a 55 segundos no Linux e de 70 a 110 no Windows, mesmo com tudo o mais em cache.

O tamanho do runner decide os números absolutos. Repositórios públicos ganham 4 núcleos no Linux e no Windows, e privados, 2. O mesmo build frio levou 8m57s contra 5m03s no Linux e 9m41s contra 5m25s no Windows. Confiança média, porque o lado de 2 núcleos é uma amostra só. As proporções entre opções transferem melhor que os tempos.

A variação entre runners idênticos é de 5 a 30%. Builds frios iguais no Linux repetiram com 4 segundos de diferença, mas o Windows espalhou de 4m30s a 5m54s, e dois jobs idênticos no macOS no mesmo run levaram 3m33s e 5m02s. Uma diferença de uma amostra só, abaixo de 20% no Windows ou 40% no macOS, não quer dizer nada.

Cache: o que mais corta

Build quente, depois de uma mudança de uma função na crate do app, mediana de 2:

Confiança média. O rust-cache e o actions/cache simples diferem menos que a variação em todos os runners. A escolha entre eles é de tamanho e higiene: o rust-cache poda o que não foi usado e sempre recompila a crate do workspace; o actions/cache guarda tudo e chega antes ao limite de 10 GB por repositório.

Encher o cache não custa nada: o build frio com rust-cache levou 4m31s contra 5m03s sem cache. Uma dependência nova custa o mesmo que uma mudança no app: adicionar chrono custou 3 segundos no Linux e 15 no Windows.

Num monorepo de 16 plugins e 434 crates, a opção cache-workspace-crates do rust-cache economizou de 15 a 30 segundos, e o cargo quente ficou em 57 segundos no Linux contra 5m35s sem cache.

Não gere instaladores no pull request

Build frio no Linux, mediana de 2, contra a linha de base com todos os bundlers:

Confiança alta para o estágio de empacotamento, que ficou entre 1m07s e 1m20s em todo job Linux de quatro lotes, e média para o tempo total. É a maior economia individual no Linux, maior que qualquer flag de compilador.

No Windows, o empacotamento vai de 17 segundos com NSIS e MSI para 11 só com NSIS e 6 sem bundle. No macOS, de 12 segundos com .app e DMG para 2 só com .app. Nenhum vale tirar pelo tempo. O DMG vale tirar dos builds de pull request porque é o passo que falha: 1 de 24 jobs macOS morreu no hdiutil.

O perfil de release

Tempo do cargo no app maior, mediana das amostras agrupadas de dois lotes, com o binário em Linux, Windows e macOS:

Confiança alta para codegen-units = 1 e para o perfil fast, média para o LTO fat.

Uma unidade de codegen serializa a crate do app, a que carrega o runtime do Tauri, num núcleo só. O binário fica de 15 a 20% menor. Subir para 256 unidades foi na direção contrária do esperado, mais lento no Linux e no Windows, porque com 4 núcleos não há paralelismo para comprar além das 16 unidades padrão.

O LTO fat teve um dia ruim de +44% no macOS que o rerun não repetiu. O LTO thin não muda nada, nem em tempo nem em tamanho. O opt-level sozinho quase não move o tempo: um build Tauri gasta nas dependências, na monomorfização e no link, não no otimizador.

O perfil fast, com opt-level = 1, 256 unidades e LTO desligado, vale cerca de 20% do tempo do cargo, por um binário de 40 a 60% maior no Linux e no macOS. Cache e bundlers valem de 50 a 70%. Ele vem depois deles, e só em pull request.

panic = "abort" é a economia de tamanho mais barata da lista: o binário foi de 10,4 para 4,9 MB no Windows, de 10,3 para 7,6 no Linux e de 7,2 para 5,0 no macOS, com o tempo dentro da variação. Confiança alta para o tamanho, baixa para o tempo. Só serve se o app não captura panics.

O que não ajudou

sccache. Sozinho é a pior opção com cache, porque sem o target/ restaurado toda crate ainda precisa ser linkada e a crate final compilada. Em cima do rust-cache, não ajuda num commit comum: a crate do app recompila de qualquer jeito, e os uploads por objeto às vezes deixam a combinação atrás do rust-cache sozinho. O piloto mostrou um ganho de 3 vezes, mas só porque nada tinha mudado entre os runs.

Pior: o backend do GitHub Actions do sccache grava um item de cache por objeto compilado, e a API de cache limita a taxa por repositório. Matrizes de 24, 30 e 42 jobs perderam de 34 a 100% das escritas, e 4 jobs com sccache entre 10 ainda perderam a metade e derrubaram um save do rust-cache junto. O sccache só avisa como “Cache write errors” nas estatísticas, e o job termina verde com o cache pela metade. Confiança alta, com os contadores nos logs de 24 jobs.

Trocar o linker. O Rust 1.90 em diante já usa rust-lld no Linux, então lld e mold caem no mesmo tempo. No Windows, rust-lld.exe não foi mais rápido.

Cortar dependências. Tirar reqwest e tokio, 29 crates, não teve efeito mensurável, nem frio nem quente, em 4 núcleos.

Compilação incremental. Custa de 7 a 8% num build frio e só paga quando o target/ sobrevive entre builds, cortando um rebuild para 3 a 8 segundos no melhor caso.

Configuração recomendada

Para o pull request: rust-cache, sem bundlers, perfil rápido. Medido junto, o tauri build levou 3m05s, 4m22s e 2m23s frio e 39 segundos, 1m42s e 39 segundos quente, no Linux, no Windows e no macOS. O job inteiro quente, com checkout, toolchain e apt, ficou entre 1m16s e 1m38s no Linux. Confiança média.

- uses: Swatinem/rust-cache@v2
  with:
    workspaces: src-tauri -> target
- run: pnpm tauri build --no-bundle -- --profile fast

Para a release: o mesmo cache e o perfil como ele é entregue, com todos os bundlers. Um preset de release com sccache, lld e LTO thin por cima foi medido e saiu de 15 a 40 segundos mais lento quente que o cache sozinho. Não há o que acrescentar.

Como verificamos

Foram 24 lotes de resultados entre 10 e 12 de setembro de 2026, em ubuntu-24.04 e windows-2022 com 4 núcleos, num repositório público, e macos-14 com 3. Os três primeiros lotes rodaram com 2 núcleos, num repositório privado, e valem só como verificação do pipeline. Rust 1.98.1. Cada lote tem o seu relatório e um registro de tempo por job.

Cada célula é a mediana de 2 a 6 amostras, com chaves de cache separadas por experimento e por lote, depois que um lote piloto contaminou o seguinte com caches ainda válidos. O tempo de parede é o do tauri build, o do cargo vem do --timings, e o empacotamento é o resto, incluindo a sobrecarga da CLI do Tauri.

O que não medimos: toolchain nightly e frontend paralelo, runners maiores, contêineres prontos, compilação cruzada, e onde começa o limite de taxa do sccache com 1 ou 2 jobs. O app de teste é pequeno e o frontend é trivial; um SPA grande põe minutos na linha do frontend.

O repositório com os workflows, os registros e o livro de evidências é o tauri-build. Uma versão em inglês desse material está em rascunho para a documentação do Tauri, à qual já contribuímos com tutoriais executáveis.

O mesmo cuidado em medir antes de decidir aparece no post sobre as capas do blog, geradas no build, e o GitHub Actions sem servidor nenhum é também o que publica as filas da ANVISA como feeds. Se a sua empresa mantém um app desktop em Tauri, é esse o trabalho que fazemos em código aberto.

Este texto registra como esse sistema ligou o ChatGPT aos dados de cada cliente, por um servidor MCP, o Model Context Protocol. É um relato do que foi construído e do que a equipe aprendeu, não uma medição. O cliente não é citado, e os exemplos de perguntas são reais, com autorização.

Resumo

• Os usuários perguntam ao ChatGPT que já têm, pelo navegador, com o login do próprio sistema.
• O servidor MCP é uma aplicação separada, só de leitura, em Python com FastMCP.
• Ele lê uma cópia limitada dos dados, num bucket, e monta visões semânticas em cima dela.
• O isolamento entre clientes é o mesmo da aplicação multi-tenant.
• O SQL aberto é restrito a lacunas, porque a IA erra quando escreve SQL livre.
• O que deu trabalho: respostas grandes demais e o corte de resposta do conector, sem limite documentado.
• O que falta: cruzar tabelas, que hoje depende da IA.

O problema de sempre

Gerar relatórios. Ninguém olhava os dados. A lista de pedidos de relatório crescia e a maioria era uma pergunta de uma linha: quanto consumimos disso no fim de semana, quantos pacientes ficaram mais de 30 dias, onde o dinheiro de materiais está indo.

Cada uma dessas perguntas é uma consulta pequena sobre dados que o sistema já tem. O que faltava era um jeito de o usuário fazer a pergunta em português e receber a resposta sem esperar ninguém.

Como ficou

O usuário abre o ChatGPT no navegador, adiciona o sistema como conector, e entra com o login do próprio sistema, por OAuth. A partir daí, ele pergunta.

Por trás, um servidor MCP responde. Ele é uma aplicação separada da principal, em Python com FastMCP, e só lê. Poderia editar, mas a necessidade era consumir dados específicos, não o banco inteiro.

Os dados que ele lê não são os do banco da aplicação. Um bucket guarda um espelho só de leitura dos dados crus, e o MCP cria visões semânticas em cima desse espelho: consumo por período, internações, gastos mensais, histórico. Essa cópia limitada já é uma camada de segurança por si só. Se o servidor MCP fosse comprometido, o que ele alcança é uma cópia parcial e só de leitura.

O isolamento entre clientes não foi reinventado. A aplicação é multi-tenant, cada cliente acessa o próprio banco dentro dela, e o controle de acesso é o da própria aplicação. O MCP herda as duas coisas do login.

O que a IA pode fazer

As ferramentas são muitas: consultas específicas, agregações, dados históricos, análises. Entre elas há uma de SQL, e é a que merece explicação.

Na primeira versão, a IA podia escrever SQL. Ela errava. Não sempre, mas o bastante para a resposta não ser confiável, e um relatório errado é pior que nenhum. A ferramenta de SQL virou outra coisa: um preencher de lacunas, com a estrutura da consulta fixa e sem todas as palavras-chave disponíveis. A IA escolhe o que vai em cada lacuna, não a forma da consulta.

O sistema também tem um painel para gerenciar prompts, onde os usuários guardam prompts grandes, elaborados para as análises que repetem. O MCP tem acesso a esses prompts, então uma análise que levou tempo para ser escrita uma vez vira uma pergunta curta nas vezes seguintes.

Três perguntas reais de usuários:

• “Historicamente, quantos pacientes internados tiveram alta depois de 30 dias de internação?”
• “Qual material tem mais consumo nos fins de semana?”
• “Consulte os gastos mensais de materiais, relacione com o consumo e veja onde o dinheiro vai e possíveis otimizações.”

A terceira é o tipo de pergunta que antes virava um projeto. Aqui ela vira uma conversa, com a ressalva da seção sobre limites.

O que deu trabalho

Mostrar muitos dados. A primeira tentação é devolver linhas. Uma resposta com centenas de linhas não cabe bem na conversa, e o conector do ChatGPT corta respostas grandes para caber no que ele chama de orçamento de resposta da ferramenta. Esse limite não está documentado. Desenvolvedores relatam o corte no fórum da OpenAI, com a mensagem de erro e sem o número. A saída foi devolver menos: agregados em vez de linhas, campos a menos, visões já resumidas. É por isso que as ferramentas são visões semânticas, e não acesso à tabela.

SQL livre. Já contado acima. A IA tende a errar no SQL aberto, e a resposta foi fechar o SQL em vez de tentar ensinar a IA a acertar.

O de sempre com IA generativa. Respostas confiantes sobre dados que não vieram, formatação que muda de uma chamada para outra, e a necessidade de descrever cada ferramenta como se fosse para alguém que nunca viu o sistema. Nada disso é específico deste caso, e tudo isso tomou tempo.

O que surpreendeu

Não foi uma resposta da IA. Foi o fato de o cliente poder fazer tudo isso com a IA que já pagava, sem um plano novo, sem um produto de BI e sem uma ferramenta a mais para os usuários aprenderem. O ChatGPT que a pessoa já abria todo dia passou a saber responder sobre o sistema dela.

O que falta

Cruzar tabelas. Como o SQL é limitado a lacunas, nem sempre é possível rodar um join, e hoje é a IA que tem de combinar os resultados de duas ferramentas. Às vezes ela faz bem. Às vezes não dá. O uso está sendo rastreado para ver quais cruzamentos as pessoas pedem, e esses viram ferramentas próprias, com o join feito do lado do servidor.

Há outras limitações do mesmo SQL restrito, e a regra para todas é a mesma: ver o que as pessoas perguntam de verdade antes de abrir a ferramenta.

Como sabemos

Este post é um relato da equipe que construiu e opera o servidor, revisado antes de publicar. Não há medições publicadas: nem tempo de resposta, nem número de usuários, nem taxa de acerto da IA. O que está aqui é o desenho, as decisões e os problemas encontrados. O corte de resposta do conector vem do relato da equipe e do fórum da OpenAI, e o limite em si não é documentado. O cliente não é citado, e o setor é dito de forma genérica.

A parte técnica de um servidor MCP escrito do zero, com as duas gerações do protocolo e OAuth para o ChatGPT, está no post sobre um servidor MCP num Worker, de um caso menor. Uma busca que roda inteira no navegador, sem servidor, é outra forma de falar com os dados.

Se os usuários do seu aplicativo querem perguntar ao ChatGPT ou ao Claude sobre os próprios dados, é esse o trabalho que fazemos em falar com o seu banco de dados. Quando a resposta precisa de revisão humana, ou de uma ferramenta nova em vez de SQL, entra o que fazemos em soluções com IA.

Este texto registra como mantemos esses contornos, as gambiarras, num documento com id, fonte do limite, data da leitura, custo e condição de saída, e o que medimos em cada um. Os limites foram lidos na documentação da Cloudflare em setembro de 2026 e conferidos de novo em 9 de outubro.

Resumo

• São 8 contornos ativos hoje. Eram 13 em setembro. Quatro sumiram quando os relatórios saíram do KV e foram para o D1, e um quando o SDK ganhou o que o app pedia.
• D1: 100 parâmetros por consulta, 50 consultas por requisição, sem transação interativa.
• Worker: 10 ms de CPU. Sete de nove chamadas medidas passaram disso, e nenhuma foi encerrada.
• KV: 1.000 escritas por dia, protegidas por uma política de oito uploads aceitos por hora.
• Uma página do ERP, de até 500 registros, por chamada de sincronização.
• Cada contorno tem id, fonte, data, custo e condição de saída.
• Um teste de 20 linhas falha quando código e documento discordam.

Por que um registro de gambiarras

A regra é simples: entra no registro todo contorno que existe por causa de um limite externo. Plano grátis, falta de recurso numa plataforma, restrição da máquina. Não entra dívida técnica em geral.

Os contornos só podem morar nos adaptadores, no Worker ou na borda do navegador. Nunca no núcleo do domínio. Quando um limite muda o desenho de uma interface do domínio, o item explica por quê. E como limites mudam, cada item diz a fonte e a data em que o número foi lido.

O plano grátis foi uma decisão com alternativas descartadas por motivo. A Vercel proíbe uso comercial no plano grátis. O Supabase pausa projetos parados. O Render dorme em 15 minutos e leva cerca de um minuto para acordar, o que seria toda visita. Neon trocaria o dialeto para Postgres, e Turso acrescentaria conta, segredo e dependência para tirar só os contornos do D1, que moram num arquivo.

A saída está decidida também. O Workers pago custa 5 dólares por mês e remove quase todos os contornos. É a primeira opção quando o limite de CPU atrapalhar de novo. A segunda é uma VPS, e o código já está pronto para ela: nada da Cloudflare fora dos adaptadores, SQL que roda em SQLite comum, migrações em .sql puro e um adaptador Node testado a cada commit.

D1: 100 parâmetros e 50 consultas

O D1 aceita no máximo 100 parâmetros por consulta, nos dois planos, e 50 consultas por invocação do Worker no plano grátis, 1.000 no pago. Os dois números estão na página de limites do D1.

A motivação é gravar uma página do ERP, de até 500 registros, com poucas consultas. Um INSERT por registro gastaria 500 consultas e estouraria o segundo limite. Então o adaptador faz INSERT de várias linhas, fatiado: cada fatia leva floor(100 / colunas) registros, 14 nas tabelas de 7 colunas e 16 na de 6. Uma página de 500 registros vira 36 consultas. O número de colunas vem do SQL da tabela, então acrescentar uma coluna reduz a fatia sozinho. Uma busca por muitos códigos vai em fatias de 80 valores, e os resultados são juntados e ordenados como uma consulta só devolveria.

Para o limite de 50, o adaptador anuncia quanto aceita por gravação: 14 vezes 48, ou 672 registros. São 48 comandos de registros, 1 de estado e 1 leitura. A sincronização para na primeira fronteira de página depois do teto, e uma página do ERP sempre cabe. Se alguém passar mais que o anunciado, a gravação falha antes de tocar no banco, com uma mensagem que cita o id da gambiarra.

Contamos cada comando de um batch como uma consulta. A documentação não diz o contrário, e é a leitura conservadora.

O D1 falso dos testes, em cima do SQLite do Node, impõe os dois limites. Tirar um contorno quebra um teste.

Uma alternativa não usada: mandar a página inteira como um parâmetro JSON e expandir com json_each. Seria uma consulta e um parâmetro. Não foi testada no D1, e o valor tem teto de 2 MB, perto do tamanho de uma página de clientes, cerca de 1,1 MB.

Sem transação: a porta em forma de lote

O D1 não mantém transação aberta entre chamadas. Não existe BEGIN, lógica em código, COMMIT. A única unidade atômica é batch(), uma lista de comandos já prontos.

Isso importa porque registros e cursor precisam gravar juntos. Um cursor à frente dos dados é perda silenciosa: a próxima leitura parte de um ponto que não foi salvo. Então a interface do domínio não oferece transação. Oferece gravar(recurso, registros, estado), e cada adaptador torna isso atômico do seu jeito: batch no D1, BEGIN e COMMIT no SQLite.

O custo é que toda operação atômica tem de caber num lote decidido antes de executar. Ler, decidir e gravar na mesma transação não existe. Onde isso fazia falta, a solução foi um token de revisão: o UPDATE do cabeçalho só casa com a revisão que a pessoa leu, e troca a revisão por um token único, que os comandos seguintes do lote exigem. Um contador não serviria, porque dois escritores chegariam ao mesmo número.

Essa gambiarra some com o D1, mas a porta em forma de lote pode ficar. É um desenho bom em qualquer banco.

CPU do Worker: o limite que não matou ninguém

O Workers grátis dá 10 ms de CPU por requisição. Espera de rede e de banco não conta. JSON.parse, laços e JSON.stringify contam.

Medimos antes de desenhar. Em 19 de setembro de 2026, em Node 24, uma página sintética de 500 clientes de 2,3 KB cada, 1,1 MB no total, passando por parse, mapeamento e serialização: 11,8 ms na primeira execução, fria; mediana de 6,3 ms aquecida; melhor caso 5,2 ms. Uma sincronização esporádica pega o isolate frio, então uma página cheia pode estourar os 10 ms sozinha. Por isso a sincronização processa uma página por chamada e devolve completo: false para quem chamou repetir.

Depois medimos no Worker de verdade, no mesmo dia, em produção no plano grátis, com wrangler tail. Uma amostra por rota:

Todas terminaram com outcome: ok. Nenhuma com exceededCpu.

O que a medição diz: sete de nove chamadas passaram de 10 ms e nenhuma foi encerrada, então o limite não é aplicado chamada a chamada com rigor. E o número não acompanha o volume: um registro custou 16 ms e 500 custaram 8 ms. O custo dominante parece ser fixo, do isolate frio e da primeira conexão de saída, e não o nosso parse. O que a medição não diz: é uma amostra por rota, a Cloudflare não documenta a tolerância, e uma página cheia de clientes de produção continua sem medição.

O corte é só entre páginas, porque dentro de uma página a ordem não é garantida. Cada corte desperdiça uma requisição ao ERP: para ver que a página acabou é preciso puxar o primeiro registro da seguinte, que é descartado e relido na próxima chamada.

Duas outras coisas saíram do Worker pelo mesmo limite. O parse da planilha de estoque mede de 25 a 55 ms em Node, então roda no navegador, e o servidor só valida o JSON e guarda a planilha original para reprocessar. E a primeira versão do cache do catálogo, um JSON único no KV mesclado por id, foi descartada no mesmo dia: a mescla media 6 ms com 600 registros e de 23 a 35 ms com 2.000.

KV: mil escritas por dia, e quatro gambiarras que sumiram

O KV grátis aceita 1.000 escritas por dia. Um upload aceito gravava quatro chaves, e a conta era 8 uploads por hora, vezes 24, vezes 4: 768 escritas, com folga de 232. A política de oito uploads aceitos por hora ficou, agora decidida na mesma transação que publica a versão, no D1.

Em 26 de setembro, o histórico de relatórios saiu do KV e foi para o D1. Quatro gambiarras sumiram com isso: a chave separada para a versão atual, por causa da consistência eventual do KV, que podia devolver um índice de até 60 segundos atrás; a releitura do índice logo antes de gravar, porque o KV não tem transação nem escrita condicional; a verificação de que uma versão “não encontrada” existia de fato; e a espera de 1,1 e 2,2 segundos depois de um 429, porque o KV aceita uma escrita por segundo na mesma chave.

Ficou um custo aceito: tentativas simultâneas podem gravar arquivos antes de disputar a última vaga, e uma publicação que falha pode deixar um arquivo sem referência. A cota de uploads não é um teto absoluto de escritas no KV.

As que ainda não precisaram existir

O D1 cobra linha lida, não linha devolvida, e o plano grátis dá 5 milhões de linhas por dia. Uma busca com LIKE '%texto%' não usa índice e lê a tabela inteira. Com 2.000 clientes e 500 buscas por dia seriam 1 milhão de linhas, um quinto da cota. É uma projeção, não uso medido, e por isso o contorno ainda não existe. Quando a tabela passar de alguns milhares de linhas, as opções são espera entre teclas, busca por prefixo com índice, ou FTS5.

Uma gambiarra que já saiu era do nosso próprio SDK, não da Cloudflare. O list() do mercos-sdk devolvia um fluxo de registros e escondia onde uma página termina, e o corte por página precisa dessa fronteira. O app contava as requisições para descobrir. O SDK ganhou um listPages() na versão 0.4.0, o app migrou em 9 de outubro, e o contador, a seção no documento e o desperdício de uma requisição por corte saíram juntos. Como esse app moldou o SDK está no post sobre o SDK e o seu primeiro app.

O teste que cobra a marca

Cada contorno leva no código o comentário GAMBIARRA(id). Um teste percorre src, web, scripts e a extensão, coleta os ids e os compara com as seções do documento e com a tabela de mapa no topo dele. Ele falha em três casos: id no código sem seção, seção sem id no código, ou tabela e seções diferentes.

Hoje são 8 ids no código e 8 seções. Ao remover uma gambiarra, a seção e o comentário saem juntos, senão o teste avisa.

Como verificamos

Os limites foram lidos na documentação da Cloudflare em 19 de setembro de 2026 para o D1 e em 26 de setembro para o KV, e conferidos de novo em 9 de outubro. A CPU foi medida em 19 de setembro com wrangler tail --format json, no Worker em produção no plano grátis, contra o ambiente de testes do ERP, uma amostra por rota. A medição em Node foi no mesmo dia, com uma página sintética de 1,1 MB.

O que não medimos: uma página cheia de produção no Worker, a tolerância do limite de CPU, e o uso da cota de leituras do D1.

O app é de um cliente e não é público. O ERP é o Mercos, e o que a API dele faz está no post sobre a API do Mercos. O mesmo Worker serve o servidor MCP do app.

Se a sua empresa precisa ligar um ERP a um sistema próprio, com sincronização que retoma de onde parou, é esse o trabalho que fazemos em integrações. O SDK que o app usa é código aberto.

Este texto registra como o servidor foi escrito sem biblioteca, o que foi medido com curl e com testes, e o que ainda não foi testado com um cliente de verdade. O código é de 25 de setembro a 5 de outubro de 2026.

Resumo

• Sem SDK: 216 linhas de transporte e 493 de ferramentas, que rodam iguais no Worker e em Node.
• As duas gerações do protocolo no mesmo POST, com a geração lida de cada mensagem.
• Sete ferramentas: quatro de leitura, uma prévia, uma gravação e um histórico de envios.
• A gravação em dois passos, presa por um código derivado da prévia.
• Um resultado incerto não convida a repetir, porque repetir uma escrita é o que o fluxo recusa.
• OAuth só para o ChatGPT, com uma biblioteca da Cloudflare de 367 KiB empacotados.
• Testado com curl e 14 testes automatizados. ChatGPT e Claude.ai de verdade, não.

Por que sem biblioteca

O MCP por HTTP é JSON-RPC 2.0 num POST. Para servir ferramentas bastam seis métodos: initialize, a notificação initialized, ping, server/discover, tools/list e tools/call. Sem sessão e sem SSE, o servidor é uma função que recebe uma mensagem e devolve outra.

A SDK oficial traz o transporte para Node e Express e a dependência do Zod. O pacote agents da Cloudflare prende o código ao Workers. Nenhum dos dois cabia num app cujo roteador precisa rodar igual no Worker e em Node, com SQLite, porque a saída para uma VPS está decidida de antemão. Então o transporte foi escrito à mão: 216 linhas, mais 493 das ferramentas. Se um cliente real não conversar, a troca pela SDK mantém as ferramentas.

Duas gerações do protocolo no mesmo endpoint

Em setembro de 2026 não dava para saber qual geração do protocolo os clientes mandam. A de 2025 começa por initialize e segue com tools/*, com lotes JSON-RPC só na versão 2025-03-26. A de 2026-07-28 não tem initialize: tem server/discover, um _meta com versão e capacidades em toda requisição, e os cabeçalhos Mcp-Method e Mcp-Name, que precisam bater com o corpo.

O servidor aceita as quatro versões, 2026-07-28, 2025-11-25, 2025-06-18 e 2025-03-26, e lê a geração da própria mensagem. initialize é sempre legada. Um _meta com versão, ou o cabeçalho MCP-Protocol-Version com 2026-07-28, é moderna. Na moderna, cabeçalho e corpo diferentes dão o erro -32020, versão desconhecida dá -32022, e método desconhecido dá 404. Na legada, os erros de aplicação vão em 200, porque o cliente antigo trata outro status como falha de transporte.

Dois desvios de propósito. O initialize responde 2025-06-18, a versão que mais clientes conhecem, em vez da última legada. E um lote aceita no máximo 10 mensagens e uma única chamada de ferramenta, para que uma escrita não divida com outra o orçamento de 50 consultas do D1 por requisição.

Uma coisa medida com um cliente real: um Claude Code na geração 2026-07-28 recusou o tools/list sem dois campos que a especificação lista como opcionais, por quanto tempo a lista pode ficar em cache e que ela é igual para todos. O servidor passou a enviar os dois.

Só Bearer, e o porquê

A rota só abre com a chave de acesso como Bearer, ou com um token OAuth que o Worker já validou. O cookie de sessão do app não vale nessa rota: uma página aberta no navegador poderia chamar ferramentas por CSRF. Um Origin presente e diferente da própria origem dá 403. Sem Bearer, 401 com www-authenticate. Corpo que não é JSON, 415. Corpo acima de 256 KiB, 413. Qualquer método que não seja POST, 405.

Ferramentas: o que o modelo pode fazer

São sete: consultar o estoque, buscar produto, buscar cliente, listar tabelas de preço, conferir itens, gravar itens e listar os envios de itens. A busca de estoque usa a mesma função e os mesmos filtros da tela do app, que desceram para o núcleo do domínio para isso.

Cada ferramenta devolve um resumo em português, uma linha por item, e o JSON completo em structuredContent. Os limites são 50 produtos, 200 tabelas e 100 itens por chamada, pelo teto de saída de 25 mil tokens do Claude Code. Um argumento inválido volta como resultado com isError, e não como erro de protocolo -32602, para o modelo corrigir e chamar de novo.

Escrita em dois passos, presa por um código

A única ferramenta que escreve é a que grava itens num orçamento do ERP. Ela nunca é o primeiro passo.

1. conferir_itens resolve cada item contra o catálogo e contra o orçamento lido do ERP, sem gravar nada, e devolve o que iria, item por item, mais um código de 16 caracteres hexadecimais: o SHA-256 do id do orçamento, do ambiente e do corpo que seria enviado.
2. A descrição da ferramenta manda o modelo mostrar a prévia e esperar a confirmação da pessoa.
3. gravar_itens exige o código. Ele recalcula o SHA-256 sobre o que iria agora e, se a lista mudou, responde 409 antes de qualquer requisição ao ERP.

O que o código prova é que a lista não mudou entre a prévia e a gravação. Ele não prova que uma pessoa leu a prévia. Isso depende do cliente de IA seguir a instrução.

Um resultado incerto, quando o envio saiu e a resposta não chegou, volta como texto que diz “os itens podem ter entrado, confira na tela e não chame de novo”, sem a marca de erro, porque isError convida o modelo a repetir. A prévia seguinte do mesmo orçamento avisa que há um envio anterior sem confirmação.

OAuth para quem não manda cabeçalho

O ChatGPT não manda cabeçalho fixo. Ele só conecta um servidor MCP por OAuth. A escolha foi a biblioteca workers-oauth-provider da Cloudflare, na versão 1.2.1, com a própria chave de acesso como login, em vez de um provedor externo com lista de e-mails.

O fluxo tem os metadados da RFC 9728 em /.well-known/oauth-protected-resource, registro de cliente por CIMD, que o ChatGPT prefere, e por DCR para quem não tem CIMD, e um escopo só. A página de autorização mostra o nome do cliente e o domínio verificado, não tem script, tem CSP própria, e uma chave errada responde 401 sem gastar a página.

Três limites assumidos. A biblioteca só roda no Worker, então em Node vale só o Bearer, e a saída para uma VPS é o servidor de autorização da SDK oficial ou perder o ChatGPT. O hash da chave vai dentro do token, então trocar a chave derruba todo token. E todos entram com a mesma chave, então não há como tirar uma pessoa só.

O pacote implantado ficou em 367 KiB, 89 KiB com gzip.

Como verificamos

Em 25 de setembro de 2026, com curl contra o servidor local e os tokens do ambiente de testes do ERP: initialize, 202 na notificação, tools/list com as sete ferramentas, server/discover e conferir_itens na geração moderna, com a prévia de um rascunho em 0,6 segundo, e os erros 405, 401, 403 e 400 para versão desconhecida e Mcp-Name errado.

Oito testes cobrem o transporte, as duas gerações, cada ferramenta e a escrita em dois passos, com dublês do ERP. Seis testes percorrem o OAuth inteiro em Node, com um KV em memória: o desafio 401, os dois metadados, o registro, a tela, a chave errada, o PKCE errado recusado, o refresh e a chave trocada derrubando o token. Duas mutações conferidas: tirar a checagem da chave ou a autorização do token faz testes falharem.

O que não verificamos: o Claude.ai e o ChatGPT de verdade, inclusive se o plano do usuário tem conector personalizado e qual registro de cliente ele usa; o CIMD em si, que em Node fica desligado; e a CPU do Worker na validação do token e no uso real.

O app é de um cliente e não é público. O ERP é o Mercos, e o mesmo app rendeu o post sobre as gambiarras do plano grátis da Cloudflare.

Se os usuários do seu aplicativo querem perguntar ao ChatGPT ou ao Claude sobre os próprios dados, é esse o trabalho que fazemos em falar com o seu banco de dados. Quando a resposta precisa de revisão humana antes de uma escrita, como aqui, entra o que fazemos em soluções com IA.

Este texto registra como o plano de ler só o pedaço necessário de cada arquivo, por HTTP Range, falhou no GitHub Pages, e o que fizemos no lugar. As medições são de 6 de outubro de 2026, com a versão 1.33.1-dev57.0 do DuckDB-WASM.

Resumo

• Site estático no GitHub Pages. O DuckDB-WASM consulta Parquet dentro do navegador.
• O plano era ler por HTTP Range, e isso falhou de três jeitos no Pages.
• Uma busca por texto via Range transferiu 5,3 MB de um arquivo de 3,25 MB.
• No Chrome, um fetch com Range deixou o fetch seguinte com um corpo de 1 byte.
• A solução: baixar cada arquivo inteiro, conferir o tamanho e a assinatura, e registrar como buffer.
• Reordenar a tabela de detalhe fez a busca de um produto tocar um grupo de linhas. O arquivo foi de 1,57 para 1,74 MB.
• A primeira visita baixa cerca de 5 MB de motor mais as tabelas. Depois, zero rede.

De onde vêm os dados

Os arquivos vêm do pipeline descrito no post sobre os dados abertos da ANVISA: um processo diário converte os CSVs da ANVISA em Parquet e publica um manifest.json com o caminho, as linhas, os bytes e o SHA-256 de cada tabela.

O site só conhece o manifesto. Os caminhos mudam a cada build e são imutáveis, então um 404 num caminho de dados quer dizer que houve deploy no meio da sessão. Nesse caso o site relê o manifesto sem cache e tenta uma vez com o caminho novo.

Ele usa quatro tabelas: alimentos, o detalhe das apresentações de alimentos, saneantes e produtos irregulares. Cosméticos, com 24 MB, ficou de fora por enquanto.

O plano: ler só o pedaço necessário

O Parquet é feito para isso. O arquivo termina num rodapé que diz onde cada grupo de linhas está e o mínimo e o máximo de cada coluna no grupo. Um leitor que suporta HTTP Range lê o rodapé, descobre quais grupos interessam e baixa só esses bytes. Com os arquivos ordenados por CNPJ em grupos de 8.192 linhas, uma busca por CNPJ leria o rodapé e um grupo.

Num teste direto contra o GitHub Pages, um pedido com Range respondeu 206, com Content-Range, Access-Control-Allow-Origin: * e cache de 10 minutos. Parecia resolvido.

Três jeitos de falhar no GitHub Pages

Em produção, o leitor HTTP do DuckDB-WASM quebrou de formas que o servidor local não reproduzia.

O HEAD com Range responde 200. O DuckDB-WASM tem um modo reliableHeadRequests que pergunta o tamanho do arquivo com um HEAD. O Pages responde esse HEAD com 200 e o tamanho inteiro, em vez de 206, e o modo falha ao abrir o arquivo.

O Firefox falha no GET com Range. O leitor HTTP do worker é um XHR síncrono. Contra o Pages, no Firefox, o GET com Range termina em “NetworkError: A network error occurred”. No Chrome 154, o mesmo pedido funciona.

Uma busca por texto lê mais que o arquivo. Uma busca por nome toca todos os grupos de linhas, e as respostas parciais do XHR não entram no cache. A cada carregamento, a busca transferiu 5,3 MB para um arquivo de 3,25 MB.

E mais quatro detalhes que medimos no caminho:

• Nessa versão, o leitor só faz Range com forceFullHTTPReads: false definido de forma explícita. Sem isso, ele baixa o arquivo inteiro a cada abertura.
• A resposta inteira vem comprimida com gzip, 3.218.370 bytes no fio para um arquivo de 3.254.645. A resposta com Range vem sem compressão.
• No Chrome, depois de um fetch com Range: bytes=0-0, o fetch simples seguinte da mesma URL devolve 200 com um corpo de 1 byte. Só o terceiro vem inteiro. Um visitante de uma página que lê por Range pode receber um arquivo truncado numa leitura posterior.
• Um parâmetro preparado num BETWEEN de inteiros impediu o descarte de grupos: a consulta de detalhe leu 1,5 MB com ? e cerca de 1 MB com literais. E mesmo quando o descarte funciona, o leitor lê adiante até o fim do arquivo.

A solução: baixar o arquivo inteiro e conferir

Os arquivos são pequenos de propósito, então o download inteiro é mais simples e mais barato que o Range. O worker do DuckDB não faz HTTP nenhum.

1. A página faz fetch() de cada tabela na primeira vez que a seção abre. O progresso usa o total do manifesto, porque o Content-Length é o do corpo comprimido.
2. O tamanho recebido tem que ser igual ao campo bytes do manifesto, e os últimos quatro bytes têm que ser PAR1. Um Parquet truncado não passa.
3. Se não bater, o site baixa de novo com cache: "reload", ignorando o cache HTTP.
4. O buffer é registrado no DuckDB com registerFileBuffer, com o id do build no nome, e vira uma VIEW. Um build novo não sobrescreve o que uma consulta em andamento está lendo.

Depois disso, toda consulta é local. O caminho é imutável, então o cache HTTP do navegador guarda o arquivo até o próximo build.

Dois detalhes de compatibilidade: o site usa os bundles mvp e eh do DuckDB-WASM, porque o coi, com threads, exige cabeçalhos COOP e COEP que o Pages não envia. E as datas voltam como texto, via strftime no SQL, porque o tipo temporal do Arrow muda conforme a versão da biblioteca.

Ordenar o arquivo para quem lê por HTTP

O Range ainda importa para quem lê os mesmos arquivos com o DuckDB nativo, direto da URL. Ali medimos duas coisas.

Só a primeira chave de ordenação descarta grupos. A tabela de alimentos é ordenada por CNPJ e depois por processo, então uma busca por CNPJ lê um grupo e uma busca por processo lê o arquivo todo.

A tabela de detalhe tinha grupos desiguais, de 92 a 411 KB, porque os produtos recentes trazem a tabela nutricional em texto longo. A única consulta do site nessa tabela é “todas as apresentações de um produto”. Reordenada por produto, em grupos de 2.048 linhas, ela ficou com 33 grupos, mediana de 25 KB e máximo de 117 KB. Uma busca de produto toca um grupo, no máximo dois entre 50 mil produtos. O arquivo cresceu de 1,57 para 1,74 MB.

Primeira visita e atualização

A primeira visita baixa cerca de 5 MB do motor, servido pelo jsDelivr, mais a tabela da seção aberta. Depois, os arquivos ficam no cache.

O site se refaz à noite, três vezes, às 22:30, 01:30 e 04:30 UTC. Ele compara o id do build no manifesto com o que o site usou e só publica quando mudou. O cron existe só para o dicionário de dados e a página “sobre”, gerados no build. A busca lê o manifesto ao vivo e não depende de republicar.

Como verificamos

As medições são de 6 de outubro de 2026, com @duckdb/duckdb-wasm 1.33.1-dev57.0, no Chrome 154 e no Firefox, contra o GitHub Pages e contra um build local dos dados. Os dados foram conferidos de novo no build publicado naquele dia. Para reproduzir o caminho do Pages em desenvolvimento, usamos um servidor Node de 61 linhas que responde CORS, HEAD e Range. O http.server do Python não faz nenhum dos três.

O que não medimos: a versão do Firefox não foi anotada. O envenenamento do cache foi reproduzido só no Chrome. Não testamos Range num servidor que não fosse o Pages, e não medimos tempos de carregamento.

O site não tem vínculo com a ANVISA. O código está em anvisa-dash, com licença MIT.

Uma consulta no navegador, sem servidor e sem enviar dado nenhum, é uma das formas de falar com os seus dados que entregamos. E manter um site assim, aberto e com dados públicos, é parte do nosso trabalho em código aberto.

Este texto registra o que esse primeiro uso mudou no desenho do SDK, o que recusamos e por quê, e o que o app adotou ou não. O que a API do Mercos faz está no post sobre a API do Mercos. Aqui o assunto é o processo.

Resumo

• 10 versões em cerca de dois dias, da 0.1.0 à 0.4.3, com 34 commits.
• O app anotou 10 achados, todos medidos no sandbox, cada um com uma sugestão.
• A 0.4.0 respondeu a 6: gancho de observação, listagem por página, busca por id, criar e ler, intervalo mínimo, máscara de token e cliente congelado.
• Dissemos não a duas partes dos pedidos: espaçamento adaptativo, e leitura por id no sandbox com listagem em produção.
• O app não adotou tudo: criar e ler, e intervalo mínimo, ficaram de fora. A listagem por página só entrou 19 dias depois.
• No npm, publicação confiável com fila de staging. A latest segue a ordem de aprovação, não o semver.
• A 0.4.2 e a 0.4.3 ficaram 19 dias na fila de staging antes de serem aprovadas.

O ponto de partida: uma requisição por vez

A 0.1.0 tinha o que a documentação do Mercos e os nossos testes no sandbox pediam: fetch nativo sem dependências, uma fila única de requisições por cliente, repetição automática no 429 com teto de espera, paginação por alterado_apos com o cursor recuado para não perder registros do mesmo segundo, até duas repetições de leitura em falha de rede e nunca de escrita, um tipo de erro que normaliza os quatro formatos do campo erros, e tipos para as 169 operações documentadas.

A fila existe porque o limite de requisições do Mercos é global. Disparar em paralelo só disputa o mesmo limite. No 429, o SDK espera o tempo que a resposta pede, mais meio segundo.

O primeiro commit é de 19 de setembro à 1h07.

Os dez achados do app

Em 20 de setembro, o app sincronizou seis cadastros e enviou um pedido no sandbox, com a 0.1.0 e depois com a 0.3.0, e anotou o que viu:

Os achados 1, 2, 3 e 10 são comportamento da API, e ficaram como documentação. Dois dos outros merecem detalhe.

O achado 7 veio de um teste com o token "a". O SDK trocava o texto do token por *** em tudo que devolvia, e o campo total do pedido voltou como tot***l. Com tokens reais, longos e aleatórios, a colisão é improvável. Mesmo assim, a máscara reescrevia um JSON que a aplicação ia usar como dado.

O achado 9 foi erro do app, e por isso virou mudança no SDK. O app fez Object.assign sobre o cliente para embrulhar um recurso, o recurso novo chamava o antigo, e depois do assign a chamada apontava para ele mesmo. Recursão infinita, que só apareceu no envio real. Um cliente congelado falha na hora da escrita, com a causa ao lado.

O que entrou na 0.4.0, e o que mudou no caminho

A 0.4.0 saiu às 20h36 do mesmo dia e respondeu aos achados 4 a 9: createAndRead em pedidos, find em todo recurso, a opção minIntervalMs, a máscara só no que alimenta um erro, a opção onAttempt com listPages, e o cliente congelado.

Três pedidos mudaram de forma no caminho.

onRequest virou onAttempt. O app pediu um gancho onRequest ou onResponse. O nome ficou onAttempt porque um timeout não tem resposta, e o gancho dispara em toda tentativa, com método, rota modelo, status, duração, número da tentativa e a espera aplicada. O evento não carrega corpo, query nem cabeçalho, então um log dele não vaza token nem dado. E uma exceção dentro do gancho é engolida: um observador não pode quebrar uma requisição.

find lista sempre. O app sugeriu leitura por id no sandbox e listagem em produção, escondendo a diferença de ambiente. O SDK lista nos dois. Com um caminho só, o que o sandbox e a homologação exercitam é o que produção roda. O since é obrigatório, porque sem ele uma busca sem resultado percorreria o histórico inteiro da conta.

minIntervalMs não é adaptativo. O app sugeriu que o SDK aprendesse o intervalo a partir do retry-after do 429. Recusamos. O limite de produção pode ser outro, e um intervalo aprendido de um único 429 poderia deixar um cliente lento para sempre. Um número explícito é previsível. A medição no sandbox, seis leituras seguidas com cinco 429 contra zero com 5,5 segundos de intervalo, está no post sobre a API.

O que o app adotou, e o que não

A recusa do createAndRead tinha razão, e virou a segunda rodada.

Segunda rodada: 0.4.1 a 0.4.3

Com o onAttempt ligado, o app mediu mais quatro coisas no mesmo dia. O sandbox pede 5,5 segundos depois de cada requisição, e quatro leituras seguidas viraram sete requisições. O onAttempt não dizia por que não houve resposta, se timeout ou falha de rede. O since do find exigia o formato e o fuso de ultima_alteracao, que o app montava à mão. E o createAndRead não dizia o que acontece quando a leitura falha depois de o pedido existir.

A 0.4.1, às 21h19, respondeu a três dos quatro: o erro de createAndRead passou a carregar o id criado em createdId, o since passou a aceitar um Date convertido para o horário do Brasil, e o evento de onAttempt ganhou um campo error com "network" ou "timeout". O espaçamento adaptativo continuou recusado.

A 0.4.2, às 23h38, veio de um teste nosso: o cursor das listagens passou a sair com espaço em vez de T, porque a rota de divisões respondia 422 ao formato da documentação e todas aceitam o espaço. A 0.4.3, às 23h50, corrigiu o tipo de alteração de pedido: um item sem id era incluído de novo em vez de alterado, e o tipo não tinha o campo.

A tabela inteira, com a hora do commit no horário de Brasília e a publicação no npm em UTC:

Publicar no npm sem token

O pacote usa a publicação confiável do npm: nenhum token guardado, e o workflow de release prova a origem com OIDC. A primeira tentativa, a 0.1.1, recebeu 403 com “OIDC permission denied”. O publicador confiável tinha permissão só para mandar a versão para a fila de staging, não para publicar direto. A 0.1.1 ficou com tag e sem npm, e desde a 0.1.2 o fluxo é: a tag dispara o workflow, o workflow faz npm stage publish com atestado de procedência, e alguém aprova no site do npm, com 2FA. A publicação em staging existe desde maio de 2026. O staging exige npm 11.15, mais novo que o npm do Node 24.

Desde a 0.4.2, a release é um comando, pnpm release patch, que ajusta a versão, data o changelog, roda a verificação, commita, cria a tag assinada e envia branch e tag juntos.

A pegadinha é a latest. Ela vai para a última versão aprovada, sem olhar o semver. Em 20 de setembro, a 0.3.0 foi aprovada às 21:28:39 e a 0.2.0 seis segundos depois, então a latest ficou na 0.2.0 até a aprovação da 0.3.1, duas horas mais tarde. A regra ficou escrita no README: com duas versões na fila, aprovar na ordem das versões.

A fila também guarda o que ninguém aprova. A 0.4.2 e a 0.4.3 tiveram tag, Release no GitHub e workflow concluído em 20 de setembro, e ficaram em staging até 9 de outubro, quando foram aprovadas com 16 segundos de intervalo, na ordem certa. Durante 19 dias a latest foi a 0.4.1, e ninguém percebeu, porque o app que motivou tudo isso estava fixado na 0.4.0. No mesmo 9 de outubro ele passou para a 0.4.3 e adotou o listPages: o contador de requisições saiu, e com ele a requisição desperdiçada a cada corte de página.

Como verificamos

As horas dos commits vêm do git log do repositório, e as de publicação, do registro do npm, consultado em 9 de outubro de 2026, depois da aprovação das duas últimas versões. Os achados do app foram medidos no sandbox do Mercos em 20 de setembro, com o SDK 0.1.0, 0.3.0 e 0.4.0, e estão num documento do app com a marca de medido ou inferência em cada item.

O que não medimos: o limite de requisições em produção, o código de erro da leitura por id bloqueada em produção, e se o cursor com espaço teria aparecido no app.

O SDK tem licença MIT e não tem vínculo com a Mercos. O app é de um cliente e não é público; o que ele contornou para caber no plano grátis da Cloudflare está no post sobre as gambiarras.

Se a sua empresa precisa de um cliente para uma API que a documentação descreve pela metade, é esse o trabalho que fazemos em código aberto e em integrações.

Este texto registra como transformamos essa consulta em um feed Atom por subfila, publicado todo dia sem nenhum servidor, e o que 32 dias de coleta mostraram. Os números são das coletas entre 6 de setembro e 8 de outubro de 2026.

Resumo

• São 319 subfilas, uma requisição cada, cerca de cinco minutos por dia.
• 32 snapshots diários entre 6 de setembro e 8 de outubro. Falta o dia 8 de setembro.
• Um feed Atom por subfila, com o que entrou, saiu ou mudou de posição em cada dia.
• Coleta, build e deploy são três jobs separados. Uma coleta que falha não apaga o site.
• O agendamento das 06:00 começou entre 09:36 e 14:51.
• 15 subfilas receberam 429 em três dias, mesmo com o cliente respeitando o limite.
• Nenhum servidor: o Git é o histórico e o GitHub Pages é a hospedagem.

O problema: a fila só existe hoje

A API Consultas Externas devolve a subfila inteira em uma chamada, sem paginação e sem histórico. O que ela mostra é o estado de agora. Para saber se um processo andou, é preciso ter guardado a fila de ontem.

Esse é o único pedaço do problema que uma API resolve. O resto, guardar, comparar e avisar, é o que o projeto faz. O comportamento da API está no post sobre a API da ANVISA.

Como a coleta funciona

Um GitHub Action roda uma vez por dia. Ele faz uma consulta por subfila, no ritmo que o gateway aceita, uma requisição por segundo. Às segundas-feiras, antes disso, ele percorre de novo o catálogo de áreas, grupos e subfilas, para notar uma subfila nova dentro de uma semana.

A coleta de 8 de outubro de 2026:

Nos dias de releitura do catálogo, são 383 requisições. Em 5 de outubro foram 393, porque o catálogo cresceu de 314 para 319 subfilas. A primeira coleta, em 6 de setembro, levou 413 segundos para 314 subfilas e 10.392 processos. Nos dias comuns, a duração ficou entre 292 e 476 segundos.

Cada coleta grava um arquivo JSON Lines comprimido, com uma linha por subfila, mais um arquivo de metadados com contagens, horários e as subfilas que falharam. O catálogo de nomes vai junto. Tudo isso é commitado no repositório.

Subfila vazia é um 404 sem corpo

Quando não há nada na fila, a API responde 404 com corpo vazio. A coleta grava a subfila como vazia, e isso não é erro. Em 6 de setembro, 88 das 314 subfilas estavam vazias. Em 8 de outubro, 87 das 319.

Uma subfila que falhou na coleta não produz evento nenhum naquele dia. Falta de dado não é mudança.

Do snapshot ao feed

O build compara cada subfila com o dia anterior. Um processo é identificado por número de processo mais expediente, porque um mesmo processo pode estar duas vezes na fila com duas petições. Daí saem três eventos: entrou, saiu e mudou de posição.

De 7 para 8 de outubro, nas 319 subfilas: 258 processos entraram, 269 saíram e 3.540 mudaram de posição. Quase toda saída empurra os processos atrás dela, então “mudou de posição” é o evento mais comum.

Cada subfila ganha um feed Atom com uma entrada por dia, com os eventos do dia e a fila como ficou. O feed guarda 30 dias. Ele carrega uma folha de estilo XSL, então o navegador mostra uma página legível em vez do XML. Cada subfila também tem uma página HTML e um JSON com a fila e os eventos, para quem prefere dados.

O site inteiro tem um feeds.opml para assinar todas as subfilas de uma vez, um sitemap, um bloco Dataset do schema.org e as tags de descoberta de feed, para o leitor achar o feed a partir da página.

O que a fila mostrou em 32 dias

O total em fila caiu de 10.392 processos, em 6 de setembro, para 9.364, em 8 de outubro. Por área, em 8 de outubro:

A maior subfila é “Genéricos, Novos e Similares - Administrativo”, com 600 processos. A entrada mais antiga na fila é de 3 de setembro de 2009, e 103 processos entraram antes de 2020.

Sem servidor: três jobs e o que acontece quando falha

O workflow tem três jobs: coleta, build e deploy. A separação é de propósito. Uma falha ao gerar o site ou ao publicar nunca perde uma coleta. O snapshot também fica guardado como artefato do workflow por 90 dias, caso o push falhe, e o push tenta de novo depois de um rebase.

Se a coleta falha, o build roda mesmo assim, com o último snapshot bom, e põe um aviso em todas as páginas. O site fica desatualizado de forma visível, em vez de silenciosa. Um botão “Run workflow” com a opção build_only refaz o site sem gastar nenhuma requisição.

O CI separado, que roda lint, testes e build a cada push, ignora os commits de snapshot. Os testes rodam só com respostas gravadas, sem rede.

O que deu errado

Três coisas, em 32 dias.

O agendamento atrasa horas. O cron está marcado para 06:00 de Brasília. Os inícios registrados foram de 09:36 a 14:51, um atraso de 3,6 a 8,9 horas. O GitHub não garante o horário de um cron, e nos dias de maior carga o atraso cresce. Por isso cada página mostra a hora da última coleta, e não “hoje”.

Um timeout derrubou a coleta inteira. Em 8 de setembro, a leitura de uma resposta estourou o tempo e a exceção abortou o job. Não há snapshot desse dia. No mesmo dia, a coleta passou a tentar de novo cada subfila que falha por erro de transporte, três vezes, com esperas de 5 e 10 segundos, em vez de abortar.

O 429 apareceu mesmo com o limite respeitado. O cliente envia uma requisição por segundo, o ritmo que o gateway repõe. Ainda assim, uma subfila recebeu 429 em 14 de setembro, sete em 15 de setembro e sete em 20 de setembro. Nenhuma desde então. O limite é contado por endereço de origem, e os runners do GitHub Actions dividem endereços entre si. É a nossa hipótese, e não dá para confirmar pelos dados.

Como verificamos

Os números vêm dos 32 arquivos de metadados commitados, de 6 de setembro a 8 de outubro de 2026, e do histórico de execuções do workflow. As contagens por área, de subfilas vazias e de eventos foram feitas por nós em 9 de outubro, sobre os snapshots commitados. A coleta usa o cliente anvisa 0.5 em Python 3.12, no GitHub Actions.

O que não medimos: uma coleta por dia não vê um processo que entra e sai no mesmo dia. A posição é a que a API devolve, e não comparamos os dados com o portal da ANVISA. Em 9 de outubro o site mudou de domínio, e o identificador dos feeds mudou junto, então um leitor que já assinava pode ver entradas antigas de novo uma vez.

O projeto não tem vínculo com a ANVISA.

Onde assinar

Os feeds estão em anvisa.feeds.abelhaninja.de, e o código, em anvisa-feeds, com licença MIT. Para rodar a coleta na sua conta, bastam as credenciais do Portal de APIs da ANVISA:

uv sync
export ANVISA_CLIENT_ID=... ANVISA_CLIENT_SECRET=...
uv run anvisa-feeds crawl
uv run anvisa-feeds build

Os cadastros que a API não cobre, como alimentos e cosméticos, saem em CSV, e o post sobre os dados abertos da ANVISA mostra o que esses arquivos escondem. Se a sua empresa precisa acompanhar uma fonte pública e ser avisada quando algo muda, é esse o trabalho que fazemos em integrações.

Este texto registra o que mais tentamos pela API, o que o suporte respondeu, como a tela do Mercos cria um orçamento, e o caminho híbrido que funcionou: o rascunho nasce na tela e a API oficial o preenche. Tudo foi medido no sandbox do Mercos, em 22 e 25 de setembro de 2026.

Resumo

• Testamos 39 nomes de campo no POST e 15 no PUT, nas versões 1 e 2. Todos recusados.
• 9 rotas inventadas deram 404, igual a uma rota inexistente. O PATCH deu 405, e parâmetros na URL foram ignorados.
• Um truque com uma chave inventada mostra quais campos a API aceita sem criar nada.
• O suporte confirmou que é limitação do sistema, não bug. Chamado 561366, 22 de setembro.
• A tela cria o orçamento num GET e o converte em pedido num POST sem corpo. As duas rotas exigem login.
• Caminho híbrido: a tela cria o rascunho, o PUT da API oficial preenche. O status continua 1.
• Riscos: a rota não tem documentação, cada abertura cria um rascunho, e a conversão por código não foi testada.

O que mais tentamos pela API

A hipótese era um campo ou uma rota não documentada. Em 25 de setembro, numa rodada de scripts com 6 segundos entre as chamadas:

Os 39 nomes eram os campos que o GET devolve, como status_b2b e pedido_origem_id, mais palpites, como orcamento, rascunho, gerar_pedido, draft e quote. A rota de status, POST /v1/pedidos/{id}/status, só troca o status personalizado, que é outro campo. E um tipo de pedido chamado “Orçamento”, testado em 21 de setembro, também produziu um pedido com status 2.

Um detalhe que a listagem mostrou: a conta tinha 5 orçamentos com status 1, 4 deles sem itens. A explicação está mais abaixo.

Como achar campo não documentado sem criar nada

Mande os candidatos junto com uma chave que com certeza não existe. Essa chave garante um 422, então nada é criado. A v2 lista todos os atributos inválidos numa mensagem só, e a v1 dá um erro por chave. Qualquer candidato que não apareça na lista de inválidos é um campo aceito.

Foi assim que os 39 nomes foram testados em duas requisições. De brinde, a v1 mostrou que os itens exigem preco_bruto e recusam preco_tabela.

O que o suporte respondeu

Perguntamos pelo chat em 21 de setembro, fora do horário. Em 22 de setembro, de manhã, a primeira resposta explicou os status padrão, Orçamento, Concluído e Cancelado, e que um status personalizado só entra depois de o pedido ser concluído. Pedimos para confirmar se era bug ou limite. À tarde, a resposta: “essa é uma limitação atual do sistema e não se trata de um bug”. O time de integração estava em cópia e não tinha respondido até 25 de setembro.

O “Concluído” do suporte é o status 2 da API, que a documentação chama de Gerado. O suporte respondeu nos termos da tela.

Como a tela cria o orçamento

Capturamos as chamadas da tela do Mercos em 25 de setembro, com uma extensão do Chrome, porque o leitor de rede do navegador não mostra as requisições do próprio Mercos. A sequência:

1. Abrir “Criar pedido / orçamento” faz um GET que já cria o orçamento no servidor e redireciona para a página dele, com o id no endereço.
2. Cliente, itens e condição de pagamento vão em formulários comuns do Django, um POST cada.
3. “Gerar pedido” é um POST sem corpo, que responde com o endereço de redirecionamento. O botão fica desabilitado até o orçamento ter condição de pagamento.

Como o GET cria o registro, cada abertura da tela deixa um rascunho. É por isso que a conta tinha orçamentos sem cliente e sem itens.

Com só os dois tokens da integração, as três rotas da tela que testamos responderam 302 para a página de login. Elas exigem a sessão de um usuário. O formulário de login tem só usuário e senha, e o HTML não cita captcha, o que não descarta verificação em duas etapas nem bloqueio depois de erros.

O caminho híbrido

Se a tela cria com status 1 e a API cria com status 2, e o PUT não mexe no status, basta trocar quem cria.

Testado em 25 de setembro, num rascunho recém-criado na tela, sem cliente, sem itens e sem condição de pagamento:

Uma segunda rodada, no mesmo dia e noutro rascunho, mediu o que o app precisava saber:

• Um PUT sem condição de pagamento é aceito num rascunho, ao contrário do POST.
• Um PUT com um item num rascunho que já tem quatro acrescenta o quinto. Os quatro ficam intactos, com os mesmos ids.
• O PUT move ultima_alteracao, então a listagem por data encontra o rascunho antes e depois.
• Desconto com 7 casas decimais dá 422. Com 4 casas é aceito, e o preço líquido volta com 5 casas, sem arredondar ao centavo.
• O Mercos grava o preço que mandamos sem conferir pelo cadastro: 138 num produto de 137 ficou 138. Catálogo velho vira preço errado no orçamento.
• A tela recarregada mostra os itens. Editar na tela sem recarregar não foi testado.
• Um PUT leva de 0,5 a 0,7 segundo. Ler, gravar e ler de novo levou 19 segundos no sandbox, por causa dos 429 entre as chamadas.

No app, a escolha foi deixar a criação com a pessoa. Ela abre o orçamento na tela do Mercos, como já fazia, uma extensão lê o id no endereço da página e manda a lista de itens ao nosso servidor, e o servidor preenche o rascunho pelo PUT da API, com os tokens da integração e o mercos-sdk. Quando o preenchimento vem de um assistente de IA, o mesmo PUT passa pelo servidor MCP do app, com uma prévia obrigatória antes de gravar. Nenhuma senha guardada, o orçamento fica no nome de quem o abriu, e a escrita passa só pela API oficial. A alternativa, um usuário só para a integração fazendo login por código, ficou guardada para o dia em que o orçamento precisar nascer sem ninguém com o Mercos aberto.

Riscos e o que não medimos

A rota que cria o rascunho não tem documentação e pode mudar em qualquer deploy do Mercos. Os termos de uso não foram lidos com esse uso em mente. Por isso o app não a chama: quem a chama é a pessoa, pela tela.

O GET de criação não é idempotente. Uma chamada repetida por engano deixou um rascunho vazio na conta. Se o preenchimento falhar, o rascunho precisa ser cancelado.

Não testamos: se criador_id no PUT troca o vendedor; gerar o pedido por código, que provavelmente exige o token CSRF; quanto dura a sessão e se a conta pode exigir verificação em duas etapas; um PUT num rascunho de outra representada, que o sandbox não permite medir; e nada disso em produção, onde a leitura por id é bloqueada e o app encontra o pedido pela listagem.

Como verificamos

Sandbox do Mercos, uma conta, 22 e 25 de setembro de 2026. Cinco rodadas de scripts, com 6 segundos entre as chamadas: leitura dos status e dos orçamentos existentes; a sonda de campos no POST, sem criar nada; dois pedidos criados e cancelados para a sonda no PUT, as rotas, o PATCH e os parâmetros na URL; as rotas da tela só com os tokens; e o PUT no rascunho. Os pedidos de teste ficaram cancelados na conta. O cliente usado nos testes é fictício.

O que não medimos está na seção anterior. O projeto não tem vínculo com a Mercos.

Se a sua empresa precisa que um sistema converse com um ERP que a API não cobre inteiro, é esse o trabalho que fazemos em integrações e em engenharia reversa.

Este texto registra o que encontramos ao integrar com ela. A maior parte foi medida no sandbox; onde não foi, o texto diz. O sandbox pode se comportar diferente da produção, e a API pode mudar depois disso.

Resumo

• A API não funciona no navegador: recusa o preflight de CORS, e os tokens dão acesso total à conta.
• O limite de requisições vale para todas as rotas juntas. No sandbox, uma requisição a cada 5,5 segundos evitou o erro 429.
• A paginação é por data de alteração, com resolução de um segundo, o que exige cuidado no corte das páginas.
• As datas vêm no horário de Brasília.
• A API não cria orçamento. O pedido nasce com o status Gerado.
• O Mercos soma o IPI do cadastro a cada item do pedido, mesmo que você não mande.
• Em produção, não dá para ler um pedido pelo ID, segundo a documentação do Mercos.

Só do servidor

A API recusa o preflight de CORS, então uma chamada feita pelo navegador falha. Mesmo que funcionasse, não seria uma boa ideia: os dois tokens, o da aplicação e o da empresa, dão acesso total à conta.

As chamadas precisam sair do seu servidor, que expõe ao navegador só aquilo de que a sua aplicação precisa.

Limite de requisições

O limite é global: vale para todas as rotas somadas, e não por rota. Ao passar dele, a API responde 429 e informa no campo tempo_ate_permitir_novamente quanto esperar.

A consequência prática é que disparar várias requisições em paralelo não adianta. Elas disputam o mesmo limite.

No sandbox, medimos:

A rodada espaçada terminou antes e precisou de metade das requisições, porque não precisou repetir nada. O limite de uma conta de produção pode ser outro, então vale medir na sua.

Outro cuidado: uma escrita que não teve resposta não deve ser reenviada às cegas. O pedido pode ter sido criado mesmo sem a resposta chegar.

Paginação por data de alteração

As listagens são incrementais. O cursor é o parâmetro alterado_apos, e o cabeçalho MEUSPEDIDOS_LIMITOU_REGISTROS com valor 1 avisa que há mais páginas.

O problema é a resolução. O campo ultima_alteracao tem precisão de um segundo, e o corte de uma página pode cair no meio de um segundo. Se a próxima página começar exatamente depois do último registro recebido, os registros restantes daquele segundo podem ficar de fora.

O que fizemos:

• Usar como próximo cursor a penúltima ultima_alteracao distinta da página, relendo o último segundo inteiro. Se a página termina em 10:00:01, 10:00:02 e 10:00:02, o próximo cursor é 10:00:01, e os registros de 10:00:02 vêm de novo.
• Descartar os registros que voltam repetidos por causa desse recuo.
• Tratar como erro o caso em que o cabeçalho avisa que há mais páginas e a página inteira tem a mesma ultima_alteracao, porque aí não há para onde recuar. Em pedidos, pedir mais registros por página costuma resolver.

Para sincronizar de forma incremental entre uma execução e outra, guarde a maior ultima_alteracao recebida e use esse valor na próxima, relendo o último segundo e descartando os repetidos.

Datas no horário de Brasília

O Mercos grava ultima_alteracao no horário de Brasília. Uma alteração feita às 00:12 UTC voltou marcada como 21:12 do dia anterior. Quem trabalha em UTC precisa converter antes de usar a data como cursor.

O formato também tem uma pegadinha. A documentação escreve alterado_apos como 2024-04-10T15:45:00. A maioria das rotas aceita, mas /v1/divisoes responde 422 e exige um espaço no lugar do T: 2024-04-10 15:45:00. Todas as rotas do sandbox aceitaram o espaço, então é o formato mais seguro.

Pedidos

A maior parte das surpresas está aqui.

• Não existe orçamento pela API. O pedido criado pela API nasce com o status Gerado ("2"). As rotas /v2/pedidos e /v1/pedidos respondem 422 a um campo status, na criação e na alteração. Orçamento, o status "1", só sai pelas telas do Mercos.
• A condição de pagamento é obrigatória, como condicao_pagamento_id ou como texto livre em condicao_pagamento. Sem nenhuma das duas, a resposta é 422, embora a documentação não marque nenhuma como obrigatória.
• O ID do pedido criado vem no cabeçalho MeusPedidosID.
• Em produção, não dá para ler um pedido pelo ID. Este ponto não vem dos nossos testes, e sim da página da rota: a leitura por ID existe só no sandbox, e depois da homologação ela não é permitida em produção, por desempenho. A documentação não diz qual erro a API devolve, e nós não medimos. A saída é procurar o pedido na listagem, filtrando por data de alteração. Quem precisar mesmo da leitura por ID pode pedir a liberação ao suporte do Mercos, com uma justificativa técnica.
• A alteração é parcial. Um item com id altera aquele item. Um item sem id é incluído, mesmo que o produto já esteja no pedido. Um item com excluido: true é excluído, mas continua vindo na leitura, marcado como excluído. Os itens que o corpo não cita ficam como estão.

O IPI que você não mandou

O Mercos soma ao pedido o IPI do cadastro do produto, mesmo quando o item não manda ipi. Um exemplo medido no sandbox:

Duas conclusões da tabela:

• O IPI percentual incide depois do desconto.
• O IPI em valor fixo é por unidade, e o desconto não o reduz.

Além disso, o arredondamento para centavos acontece no subtotal de cada item.

Uma tela que soma só preço, quantidade e desconto vai mostrar um total menor que o real. Depois de criar o pedido, consulte-o de novo para ter o valor que o Mercos gravou.

Já a substituição tributária (st) do cadastro não entrou no pedido: os itens voltaram com st: 0. Não sabemos o motivo.

Estoque

Aqui medimos pouco. A conta de sandbox está com o controle de estoque desligado, e o Mercos recusa qualquer ajuste nessa condição com 422 e uma mensagem que diz isso. Foi o único comportamento de estoque que vimos acontecer.

As regras abaixo vêm da documentação, e o SDK as trata, mas não as confirmamos no sandbox:

• O ajuste define o saldo, não soma nem subtrai. Você envia o saldo novo.
• Cada requisição aceita no máximo 300 ajustes. Se um deles der erro, o lote inteiro é cancelado e nenhum saldo muda.
• O ajuste vale para produtos simples e para os filhos de uma grade. No produto agregador, o pai da grade, a documentação diz que a API devolve erro.

Outras coisas que vale saber

• Valores ausentes vêm como 0 ou "", não como null: tabela_preco_id: 0, transportadora_id: 0, observacoes: "". Um 0 num campo de ID quer dizer “sem valor”.
• Os erros vêm em quatro formatos diferentes, conforme a rota.
• A data de um campo extra vai como yyyy-mm-dd. A documentação mostra yyyy-dd-mm, que é erro de digitação: a API recusa e informa o formato certo.
• Não há rota para os dados da própria empresa, como logotipo ou CNPJ.
• Quantidade fracionada, como 1,5, é aceita.

Como verificamos

Os testes rodaram contra o sandbox do Mercos. Parte veio de uma suíte automatizada, que cria um pedido e o cancela no fim. O resto veio de uma aplicação nossa que usa o SDK no dia a dia, também apontada para o sandbox.

A documentação do Mercos traz trechos de OpenAPI embutidos em cada página. Juntamos esses trechos em um único arquivo, com 169 operações, e registramos as correções num arquivo à parte, cada uma com o motivo. Dois defeitos se repetem nas páginas: um objeto declarado quando o exemplo mostra uma lista, ou o contrário, e a mesma rota documentada com corpos diferentes em páginas diferentes.

Um SDK que já trata isso

Publicamos o mercos-sdk, um SDK em TypeScript com licença MIT. Ele usa o fetch nativo, sem dependências, e roda em Node 22 ou mais recente, Deno, Bun e Cloudflare Workers.

Ele envia uma requisição por vez e espera o tempo indicado na resposta 429, faz a paginação com o recuo descrito acima, nunca reenvia uma escrita, converte um Date para o horário de Brasília e junta os quatro formatos de erro em um só. Também se recusa a iniciar no navegador, para os tokens não vazarem. Por padrão ele não espaça as requisições; o intervalo de 5,5 segundos se configura com a opção minIntervalMs.

npm install mercos-sdk

import { createMercos } from "mercos-sdk";

const mercos = createMercos({
  applicationToken: process.env.MERCOS_APPLICATION_TOKEN!,
  companyToken: process.env.MERCOS_COMPANY_TOKEN!,
  environment: "sandbox",
});

for await (const cliente of mercos.clientes.list({ changedAfter: "2024-01-01 00:00:00" })) {
  console.log(cliente.id, cliente.razao_social);
}

O projeto não tem vínculo com a Mercos. Como o primeiro app que o usou mudou o desenho do SDK está no post sobre o SDK e o seu primeiro app, e o que fizemos para criar orçamento, que a API não faz, está no post sobre o caminho híbrido. Fizemos o mesmo tipo de levantamento com a API da ANVISA.

Se a sua empresa precisa ligar o Mercos a um ERP, a uma planilha ou a outro sistema, esse é o trabalho que fazemos em integrações.

Este texto registra o que encontramos ao converter sete desses arquivos para Parquet, todos os dias, num processo automático. Cada comportamento foi medido nos arquivos de outubro de 2026, com a data indicada. A ANVISA pode mudar o formato depois disso.

Resumo

• A codificação é Windows-1252, não Latin-1. Nossa primeira anotação errou isso.
• Aspas dentro de um valor não são escapadas, e há quebras de linha dentro de valores. Nenhum leitor pronto leu os arquivos inteiros.
• As datas vêm em dia/mês ou mês/dia, conforme o arquivo, sem aviso.
• O número de processo tem 13, 14 ou 17 dígitos, e 14 é o tamanho de um CNPJ.
• Em produtos irregulares, a coluna nu_cnpj não é a empresa autuada.
• Cosméticos tem 1.204.980 linhas, e 11.144 processos aparecem duas vezes.
• O navegador não lê os arquivos direto, porque o servidor não envia CORS.

Onde estão os dados e por que o navegador não lê

Os cadastros de alimentos, saneantes e cosméticos ficam em CONSULTAS/PRODUTOS/, no mesmo servidor. As medidas de fiscalização, de todas as áreas, ficam em CONSULTAS/EMPRESA_FISCALIZACAO_PRODUTO/. O ciclo de análise das petições de alimentos fica na raiz.

O servidor envia ETag e Last-Modified, e responde 304 a um If-None-Match. Um dia sem mudança custa uma resposta vazia por arquivo. Ele não envia cabeçalhos de CORS, então uma página no navegador não consegue ler os arquivos. Quem quer uma busca no navegador precisa hospedar uma cópia.

Os tamanhos, medidos em outubro de 2026:

As contagens são do dia em que cada arquivo entrou na conversão. O manifesto publicado tem as de hoje.

Codificação: Windows-1252, não Latin-1

Nossa primeira anotação dizia Latin-1. O dicionário de alimentos diz o certo, “1252 (padrão ANSI)”, mas só no passo a passo de importação do Excel, onde quem lê por programa não procura. Os dois são quase iguais, e a diferença está nos bytes de 0x80 a 0x9F. No Latin-1 eles são caracteres de controle. No Windows-1252 eles são o travessão (0x96), o apóstrofo curvo (0x92), as aspas curvas (0x93 e 0x94) e o símbolo de marca registrada (0x99). Os arquivos usam todos esses.

No arquivo de cosméticos, o byte 0x96 aparece 21.282 vezes e o 0x92, 5.590 vezes. Lidos como Latin-1, esses nomes ganhariam caracteres invisíveis no lugar de um travessão.

Dois defeitos já vêm de origem e ficam como estão: 11 nomes de produto foram gravados como UTF-8 e lidos como Windows-1252 antes de a ANVISA exportar, então aparecem como LOÇÃO, e 260 razões sociais começam com os caracteres de controle \x17\x10\x16\x18.

Aspas que não fecham e linhas que não terminam

O separador é ;, e os textos vêm entre aspas. Até aí, CSV comum. O problema é que uma aspa dentro de um valor não é escapada: biscoito tipo "cookies" vem assim mesmo, e um valor que termina em aspa vem como ...brilhante. "". Além disso, há valores com quebra de linha, tanto LF quanto CRLF.

Testamos três leitores. O leitor estrito do DuckDB recusa o arquivo. O leitor tolerante junta dois registros em um. O módulo csv do Python divide um registro em dois.

A regra que funcionou tem duas partes. Uma aspa só fecha um campo quando vem antes de ; ou de uma quebra de linha. E uma quebra de linha só fecha o registro quando o campo é o último, porque o leitor sabe quantos campos o cabeçalho tem. O caso que forçou a segunda parte está em saneantes: um nome de produto contém AMBIENTE "AS MENINAS", depois duas quebras de linha, depois SPRAY. Lido assim, todo registro de todos os arquivos sai com o número de campos do cabeçalho.

Os textos também trazem entidades HTML, como L'ANA MED e ". Em cosméticos, & vem em maiúsculas. Já &KISS; não é uma entidade e fica como está. Alguns valores terminam em espaço duro e quebra de linha, então todo valor é aparado.

Datas: dia ou mês primeiro, conforme o arquivo

Os arquivos de alimentos, o das petições em andamento e o de cosméticos escrevem dd/mm/yyyy HH:MM:SS. Os de saneantes, das petições finalizadas e de produtos irregulares escrevem mm/dd/yyyy HH:MM:SS. Nenhum deles avisa.

Nós fixamos um formato por arquivo, e nunca os dois. Com os dois ativos, 12/08/2026 entraria pelo primeiro que aceitasse, sem erro. Com um só, o formato errado deixa sem leitura toda data com dia acima de 12, e a trava de 20% de valores nulos por coluna derruba a conversão. É o jeito de o erro aparecer no build, e não meses depois.

Mais três detalhes:

• O vencimento do registro em alimentos vem como MMYYYY, por exemplo 122029. Toda notificação traz 122029, um valor de preenchimento. Os registros vencem 5, 10, 15 ou 20 anos depois da regularização.
• Em saneantes, há validades no ano 3033.
• Os booleanos são S e N em alimentos, com um X solto, e 1 e 0 em saneantes. Cosméticos tem uma coluna de cada tipo.

Número de processo: 13, 14 ou 17 dígitos

O dicionário dá a entender que o processo tem 17 dígitos. O arquivo de alimentos, medido em 6 de outubro de 2026:

Uma regra de 17 dígitos deixa de fora 44% das linhas, quase todas histórico inativo. E os 400 processos de 14 dígitos têm o tamanho de um CNPJ, então “14 dígitos é CNPJ” é ambíguo. A nossa busca tenta CNPJ primeiro e depois processo.

Em cosméticos, medido em 7 de outubro: 17 dígitos em 1.126.326 linhas, 15 em 69.822, 13 em 8.826 e 14 em 6.

O dicionário avisa que o Excel converte campos com zeros à esquerda em número. O CNPJ vem com zeros à esquerda, como 00000000055417, então processo, CNPJ e registro são texto, nunca número.

Os números de registro têm a própria pegadinha. Nas notificações, o número de registro é o próprio processo. Nos registros, são 9 dígitos. E nu_registro, por apresentação, é o registro mais um sufixo de 4 dígitos: 13 dígitos, o mesmo tamanho de um processo antigo.

Produtos irregulares: o CNPJ que não é da empresa autuada

O arquivo de produtos irregulares tem uma linha por produto, ação e atividade de cada dossiê de fiscalização: suspensão, proibição, recolhimento, apreensão, interdição ou inutilização. Ele tem duas colunas de CNPJ, e a primeira engana.

nu_cnpj é de quem abriu o dossiê. Em 1.698 de 4.916 dossiês, é a própria ANVISA. Em alguns, é um marketplace. Em outros, é a própria empresa. A empresa autuada está em nu_cnpj_empresa_investigada, e essa coluna nem sempre traz um CNPJ: são 14 dígitos em 35.029 linhas, um CPF de 11 dígitos em 2.334, vazio em 31.658 e texto no resto, como DESCONHECIDO, Não se aplica e NA.

Cruzar com os cadastros ajuda menos do que parece. Das 8.693 linhas de alimentos que nomeiam uma empresa, só 1.667 encontram um CNPJ no cadastro de alimentos. E só 8 de 1.580 nomes de produto batem com um produto regularizado. A maior parte das medidas em alimentos é contra produtos e empresas sem registro.

Dois cuidados a mais: produtos_concatenados é cortado em 4.000 caracteres, então use produto, e 38 linhas são iguais a outra depois de aparar um espaço no fim do nome.

Cosméticos: 1,2 milhão de linhas e processos em dobro

O arquivo de cosméticos tem 1.204.980 linhas e 10 campos, sem quebra de linha dentro de valor. É o maior dos sete, e o mais regular na forma.

A pegadinha é outra: 11.144 processos aparecem duas vezes, com o mesmo CNPJ e o mesmo número de registro. Uma linha vem com st_registrado falso e o tipo de petição preenchido, e a outra com st_registrado verdadeiro e o tipo vazio. No arquivo original, as duas podem estar a um milhão de registros de distância, porque as linhas registradas vêm todas depois do registro 1.089.484. Para contar produtos, conte processos distintos.

Convertido, o arquivo vira 24,2 MB de Parquet. O nosso leitor processa o CSV em 31 segundos usando 68 MiB, e a conversão inteira leva de 30 a 40 segundos com pico de cerca de 700 MiB. Os bytes estão no nome do produto, 12,9 MB, e no número do processo, 7,1 MB, então tirar colunas não ajuda. Dividir pelo tipo de petição ajuda: 10,5 MB, 11,9 MB e 2,0 MB.

Petições de alimentos: dois arquivos sem empresa

O ciclo de análise das petições de alimentos vem em dois arquivos: as finalizadas pelo menos uma vez, e as que nunca foram. Os dois não se sobrepõem, e nenhum nomeia a empresa.

Para saber de quem é a petição, é preciso cruzar o número do processo com o cadastro de alimentos. Isso encontra 72% dos processos do arquivo de finalizadas, 163 das 172 petições abertas do tipo Petição, e nenhuma das 164 abertas do tipo Processo. Faz sentido: essas são pedidos de registro novo, e o produto ainda não existe no cadastro.

Como verificamos

Os arquivos de alimentos, saneantes e produtos irregulares são de 5 de outubro de 2026. Os de petições são de 6 de outubro, e o de cosméticos, de 7 de outubro. A conversão roda todo dia às 21:00 UTC, com DuckDB, e publica Parquet com compressão zstd em grupos de 8.192 linhas. Uma coluna que perde mais de 20% dos valores na conversão derruba o build.

Conferimos à mão, em 6 de outubro, a página de produto e a página de apresentação do painel de consultas da ANVISA contra as tabelas de alimentos. Nada que o painel mostra faltava. As outras tabelas não foram comparadas com nada.

Depois das mudanças no leitor, o Parquet dos seis arquivos menores saiu byte a byte igual ao anterior, conferido por SHA-256, com as fontes baixadas de novo em 8 de outubro.

O que não medimos: a variação dos arquivos ao longo do tempo, e se os defeitos de codificação são corrigidos na origem.

Um conversor que já trata isso

O leitor e a conversão estão no cliente anvisa-api, em Python com licença MIT. O resultado é publicado todo dia no GitHub Pages, com um manifest.json que lista cada tabela, as linhas, os bytes, o SHA-256, as colunas e a ordenação.

pip install 'anvisa[dados]'
anvisa dados list
anvisa dados build --out dist

O mesmo Parquet pode ser lido de qualquer lugar com DuckDB:

SELECT no_produto, marcas, situacao_registro
FROM 'https://vasfvitor.github.io/anvisa-api/data/<build_id>/alimentos.parquet'
WHERE nu_cnpj_empresa = '00000000000000';

O projeto não tem vínculo com a ANVISA. A busca no navegador que usa esses arquivos é o contém., e como ela funciona sem servidor está no post sobre a busca com DuckDB-WASM. As filas de análise saem todo dia em feeds Atom.

O post sobre a API da ANVISA mostra o mesmo tipo de levantamento para a parte que tem API. Se a sua empresa depende de um arquivo ou de um sistema que não se comporta como a documentação diz, é esse o trabalho que fazemos em engenharia reversa. Ligar esses dados ao seu sistema, com atualização diária e aviso quando a fonte muda, é o que fazemos em integrações.

O Bulário Eletrônico da ANVISA lista as versões de cada bula, mas publica só o PDF de cada uma. Não há um resumo do que mudou. Para descobrir, é preciso abrir os dois arquivos e comparar à mão, página por página.

Fizemos o buladiff para isso. Ele baixa as versões de um medicamento e mostra o que mudou entre duas delas, seção por seção.

Resumo

• O Bulário publica cada versão em PDF, sem indicar o que mudou.
• O buladiff compara duas versões seção por seção, usando as seções definidas pela RDC 47/2009.
• Cada versão traz duas bulas: a do paciente (VP) e a do profissional (VPS). As duas são comparadas.
• O resultado foi conferido, como indício, contra a tabela de histórico que a própria empresa coloca no fim da bula.
• O código é aberto, com licença MIT, e o site é atualizado a partir do arquivo de versões.

Por que comparar seção por seção

As bulas seguem uma estrutura definida pela RDC 47/2009. Na bula do profissional, as seções são títulos como “4. Contraindicações” e “5. Advertências e precauções”. Na do paciente, são perguntas, como “4. O que devo saber antes de usar este medicamento?”. Comparar o texto inteiro de uma vez mistura mudanças de seções diferentes, e fica difícil saber onde cada uma aconteceu.

Por isso o buladiff primeiro divide cada bula nas suas seções e depois compara cada seção com a mesma seção da outra versão. O resultado diz, por exemplo: mudou a seção de reações adversas, e só ela. Dentro da seção, a diferença é marcada palavra por palavra, com os parágrafos preservados.

O que dá trabalho num PDF de bula

Um PDF é feito para ser impresso, não para ser lido por um programa. Vários detalhes atrapalham a comparação, e cada um pediu um ajuste próprio:

• Cabeçalho e rodapé com código de versão em toda página. Se não forem removidos, toda página parece ter mudado.
• Várias bulas no mesmo PDF, uma por apresentação do medicamento, e em ordem diferente de uma versão para outra. O buladiff pareia as bulas pela semelhança do texto, não pela posição no arquivo.
• Títulos fora do padrão, sem o numeral romano (I, II, III) ou sem a linha “Identificação do medicamento”.
• Tabelas. O editor de texto grava uma tabela inteira como uma única linha alta e a parte onde a página quebra. Lida célula por célula, ela enche a comparação de ruído. As tabelas são lidas linha a linha, como aparecem na página, e o resultado não muda de uma versão para outra.
• Palavras partidas. O editor de texto às vezes grava uma palavra em dois pedaços. O buladiff junta os pedaços de novo.

Muitos PDFs de bula vêm com uma marcação de estrutura que diz o que é parágrafo, título e linha de tabela. Quando ela existe, a leitura é bem mais limpa. Em 9 dos 11 PDFs que validamos, ela existia. Sem a marcação, o texto chega linha a linha, e o buladiff remove cabeçalho e rodapé repetidos antes de comparar.

Como conferimos o resultado

A maioria das empresas inclui no fim da bula uma tabela chamada “Histórico de Alteração da Bula”, com os itens que mudaram em cada versão. Ela serviu de gabarito.

Testamos 11 registros de 9 empresas: genéricos, medicamentos de referência e um biológico com várias apresentações. As seções que o buladiff apontou como alteradas bateram com a tabela de histórico.

A conferência é indicativa, não uma prova. A coluna de itens alterados mistura a bula do paciente e a do profissional, algumas empresas deixam a coluna vazia ou genérica, e uma das empresas testadas não inclui a tabela.

O que ainda não funciona bem

• PDFs sem marcação de estrutura, comuns nas versões mais antigas. O texto vem linha a linha, sem parágrafos, e as tabelas viram texto corrido, o que gera ruído na comparação.
• Tabelas no site. Mesmo nos PDFs com marcação, o site mostra as tabelas como linhas de texto, não como tabela.
• Medicamentos notificados usam outra consulta da ANVISA e não têm histórico de versões. Ficam de fora.
• Avisos. O buladiff não manda email quando uma bula muda. A ANVISA oferece um monitoramento oficial por email, que não mostra a diferença entre versões.

Um cuidado com a fonte

A consulta que o buladiff usa é a mesma que a página do Bulário usa no navegador. Ela não é documentada: pode mudar ou deixar de funcionar sem aviso. Os links dos PDFs também expiram em poucos minutos, então o download precisa acontecer logo depois da consulta. E a lista de versões do Bulário às vezes muda de um dia para o outro: versões somem da listagem e voltam depois.

Por isso o projeto guarda o próprio arquivo. Ele salva o texto extraído de cada versão, com uma assinatura (hash) do PDF original, e só busca o que é novo.

Atualização de 28/10/2026. O aviso acima se cumpriu. A consulta do Bulário passou a exigir um token do Cloudflare Turnstile, um CAPTCHA que só um navegador com uma pessoa gera. Medimos em 28/10/2026: a consulta respondeu 403, com o código turnstile_invalido, tanto do servidor de automação do GitHub quanto do nosso intermediário na Cloudflare e de uma conexão doméstica. Por isso a coleta está pausada, e o arquivo publicado vai até 16/09/2026. O site e os dados já arquivados continuam no ar.

Como usar

O site do buladiff mostra, para cada medicamento acompanhado, a linha do tempo de versões e a comparação entre versões consecutivas, com busca por nome e por princípio ativo. Ele também lista o catálogo do Bulário, com link para a ANVISA nos medicamentos que ainda não são acompanhados.

Para quem programa, o projeto é uma ferramenta de linha de comando em Python, no repositório buladiff:

uv sync                                        # instala as dependências
uv run bulario search dipirona                 # registros, empresa e data da última bula
uv run bulario fetch 118190404 --all           # baixa todas as versões de um registro
uv run bulario diff --registro 118190404 --tipo vps --html diff.html   # compara as duas versões mais recentes
uv run bulario diff antiga.pdf nova.pdf        # ou compara dois PDFs quaisquer

Se você já trabalhou com a API oficial da ANVISA, o post sobre o que a documentação da API não conta mostra o mesmo tipo de levantamento em outra fonte do órgão.

Se a sua empresa precisa acompanhar documentos que só existem em PDF, num portal sem API, esse é o trabalho que fazemos em engenharia reversa e em integrações.

Este texto explica como isso funciona na prática e por que às vezes uma nota que você esperava não aparece. Ele se baseia no que aprendemos desenvolvendo o Nanci, um aplicativo de desktop para Windows, gratuito e de código aberto, que baixa essas notas. Ele tem interface visual, com telas e botões, e também linha de comando para quem quer automatizar.

Resumo

• Com o certificado digital da empresa, dá para baixar NFS-e, NF-e e CT-e sem entrar em portal.
• As notas chegam em sequência. Depois da primeira vez, cada consulta traz só o que é novo.
• Na NF-e, a empresa destinatária recebe primeiro um resumo. O XML completo vem depois da Ciência da Operação.
• As notas que a própria empresa emitiu não aparecem na NF-e e no CT-e, e podem não aparecer na NFS-e.
• A fila de distribuição da SEFAZ guarda as NF-e e os CT-e por cerca de 90 dias.
• Quem consulta demais é bloqueado pela SEFAZ por um tempo.

O que você precisa

• O certificado digital de cada empresa e a senha dele. O mesmo certificado serve para NFS-e, NF-e e CT-e. O Nanci trabalha com o tipo A1, em arquivo .pfx ou .p12.
• Para NF-e e CT-e, a UF da empresa.

Na NF-e e no CT-e, o certificado da matriz serve para as filiais, porque a SEFAZ confere a raiz do CNPJ (os 8 primeiros caracteres).

Se aparecer “MAC verification failed” ao abrir o certificado, a senha está errada.

Como as notas chegam

O governo mantém, para cada CNPJ, uma fila com os documentos em que a empresa aparece. Cada documento recebe um número de sequência, o NSU. O programa guarda o último número que já leu e, na consulta seguinte, pede só o que veio depois.

A fila de distribuição da SEFAZ guarda as NF-e e os CT-e por cerca de 90 dias. O primeiro download traz o que ainda estiver lá; o que for mais antigo precisa vir de outra fonte.

Na prática, a primeira consulta pode demorar, conforme o volume. As seguintes são rápidas e trazem só as novidades.

NF-e: primeiro o resumo, depois o XML

O que chega depende do papel da empresa na nota:

O caso do destinatário é o que mais confunde. O resumo traz chave, emitente, valor e situação, mas não é o documento fiscal. Para receber o XML completo é preciso registrar a Ciência da Operação, ou uma manifestação conclusiva. Depois disso, o XML chega em uma consulta seguinte.

As outras manifestações são diferentes. Confirmação, Desconhecimento e Operação não Realizada são definitivas na SEFAZ e não podem ser desfeitas. Por isso o Nanci sempre mostra antes o que seria enviado e só envia com a sua confirmação.

A Ciência não é definitiva, mas também não para o relógio. Se nenhuma manifestação conclusiva for registrada em 90 dias da autorização, a operação é considerada confirmada, com os mesmos efeitos da Confirmação. A regra está na cláusula 15ª-C do Ajuste SINIEF 07/05; as notas técnicas ficam no Portal Nacional da NF-e.

CT-e: mais simples

O CT-e não tem resumo nem Ciência: o XML completo chega direto.

A empresa recebe os CT-e em que é tomadora, remetente, destinatária, expedidora, recebedora ou autorizada. Como na NF-e, o emitente não recebe o CT-e que ele mesmo emitiu.

Um detalhe útil: o Nanci guarda as chaves das NF-e transportadas em cada CT-e. A partir de uma nota, dá para achar o CT-e do frete.

NFS-e: por que a nota emitida não aparece

É a dúvida mais comum: “emito NFS-e todo mês e a consulta não trouxe nada”.

A consulta do ADN não deve ser tratada como lista completa das notas emitidas pela própria empresa. Dependendo da regra de distribuição e de quanto o município já está integrado ao padrão nacional da NFS-e, notas em que o seu CNPJ é o prestador podem não aparecer.

Para saber se está tudo funcionando, teste com uma nota em que o seu CNPJ seja tomador.

A mensagem “Nenhum documento localizado para o NSU informado” (código E2220) não é necessariamente um erro: quer dizer que a conexão funcionou e que não há nota nova.

Cuidado com o limite de consultas

A SEFAZ bloqueia por um tempo o CNPJ que consulta demais, com a rejeição 656 (consumo indevido). O Nanci reduz esse risco por conta própria:

• Faz no máximo 20 consultas por hora por empresa na NF-e, e outras 20 no CT-e.
• Quando não há nada novo, espera 1 hora antes de consultar de novo.
• Se receber o bloqueio, espera 1 hora.

Para o CT-e, a SEFAZ não publica um limite por hora; o Nanci usa o da NF-e por prudência.

Onde ficam o certificado e as notas

Um certificado digital dá acesso às notas da empresa. Vale perguntar por onde ele passa antes de entregá-lo a qualquer serviço.

No Nanci a escolha foi deixar tudo no computador de quem usa:

• A conexão sai direto da máquina para os servidores do governo.
• O certificado e o banco de dados ficam no seu computador.
• Nada é enviado para um servidor nosso ou de terceiros.

O backup é copiar a pasta de dados, como descrito na página de privacidade. O código é aberto e pode ser conferido por quem quiser.

Várias empresas no Nanci

O Nanci é um aplicativo de desktop para Windows, com interface visual. Na primeira vez, ele guia o cadastro do certificado e da primeira empresa. Depois é só cadastrar as outras empresas e clicar em sincronizar. As NFS-e podem ser exportadas em Excel, CSV, ZIP de XMLs e PDF (DANFSE), e as NF-e e os CT-e, em ZIP de XMLs. Para quem quer automatizar, ele também funciona pela linha de comando.

O que ele não faz:

• Não usa portal de prefeitura nem simula navegação.
• Não baixa NFC-e, MDF-e, NFCom, NF3e nem CF-e SAT.
• Não recupera as notas emitidas pela própria empresa.
• Não aceita certificado A3.
• Não substitui a conferência contábil e fiscal.

Dúvidas comuns estão na FAQ e na página de solução de problemas.

Para quem programa a integração, o post sobre a API da ANVISA mostra o mesmo tipo de levantamento em outra API do governo.

Se a sua empresa precisa dessas notas dentro de um sistema próprio, como um ERP ou um painel, esse é o tipo de trabalho que fazemos em integrações.

Este texto explica as quatro manifestações, os prazos e os cuidados. Ele se baseia na documentação que escrevemos para o Nanci, um aplicativo de desktop para Windows, de código aberto, que baixa e manifesta NF-e direto do Ambiente Nacional da SEFAZ. Ele tem interface visual e também linha de comando. Não substitui a orientação do seu contador.

Resumo

• Só a empresa destinatária de uma NF-e autorizada pode manifestar.
• A Ciência da Operação libera o XML completo, mas não é conclusiva.
• Confirmação, Desconhecimento e Operação não Realizada são conclusivas e definitivas.
• As conclusivas podem ser registradas em até 90 dias da autorização.
• Sem manifestação conclusiva em 90 dias, vale a confirmação tácita: a operação é considerada ocorrida.

As quatro manifestações

Ciência da Operação: o que ela faz e o que não faz

Quando uma NF-e é emitida contra o seu CNPJ, a SEFAZ entrega primeiro um resumo: chave, emitente, valor e situação. O resumo não é o documento fiscal.

O XML completo só é distribuído depois de uma manifestação. A Ciência da Operação é a mais leve: ela só registra que a empresa tomou conhecimento da nota. Depois dela, o XML completo chega na próxima consulta.

Por isso muita empresa registra a Ciência de todas as notas recebidas, em lote, só para ter os XMLs. Funciona para ter os XMLs, mas tem um limite importante: a Ciência não conta como resposta definitiva e não interrompe o prazo da confirmação tácita.

Prazos e confirmação tácita

• Manifestações conclusivas: podem ser registradas em até 90 dias da autorização da NF-e. Fora desse prazo, a SEFAZ rejeita o evento com o código 596.
• Confirmação tácita: passados os 90 dias sem nenhuma manifestação conclusiva, a operação é considerada ocorrida, com os mesmos efeitos da Confirmação da Operação. A Ciência registrada antes não muda isso.

Na prática, se uma nota foi emitida contra a sua empresa por engano ou por fraude e ninguém registrar o Desconhecimento em 90 dias, ela passa a valer como confirmada.

A regra está na cláusula 15ª-C do Ajuste SINIEF 07/05, na redação dos Ajustes SINIEF 11/22 e 14/26. As notas técnicas ficam no Portal Nacional da NF-e.

Uma manifestação conclusiva não volta atrás

Confirmação, Desconhecimento e Operação não Realizada são definitivas na SEFAZ. O Nanci também não aceita uma segunda conclusiva para a mesma nota.

Um caso que confunde: tentar registrar a Ciência numa nota que já tem manifestação conclusiva. A SEFAZ rejeita com o código 655, e nada é registrado.

Como não dá para voltar atrás, o Nanci sempre mostra o que vai enviar e só envia com uma confirmação explícita.

Códigos de resposta que aparecem

O 656 vem das consultas de download, não do envio de eventos. Para evitá-lo, o Nanci faz no máximo 20 consultas por hora por empresa e espera uma hora quando não há nada novo.

Quem recebe o quê

A manifestação é do destinatário. O CNPJ também aparece em notas como transportador, como autorizado a obter o XML ou como emitente, e cada papel recebe uma coisa diferente. O post sobre como baixar NFS-e, NF-e e CT-e de várias empresas mostra o que chega em cada caso e explica a consulta.

Ciência em lote, com cuidado

Registrar a Ciência nota por nota não faz sentido para quem recebe muitas NF-e. O Nanci envia a Ciência em lote: até 20 eventos por envio, assinados com o certificado da empresa, pedindo a senha uma vez só para a operação inteira.

Alguns cuidados que aprendemos:

• Simular antes. Ver quais notas vão receber a Ciência e quais ficam de fora, e por quê.
• Tratar o lote sem resposta. Se um lote não teve resposta, ele é reenviado uma vez. Se o lote já tinha chegado à SEFAZ, ela responde 573 e a nota conta como já registrada. Se continuar sem resposta, os lotes seguintes não são enviados, e as notas podem ser enviadas de novo depois.
• Acompanhar os prazos. O Nanci marca a nota como “ciência atrasada” 10 dias após a autorização, se ela ainda não tiver nenhuma manifestação. Esses 10 dias são um aviso do Nanci, não um prazo da SEFAZ. Ele também alerta a partir de 30 dias antes do fim do prazo das conclusivas. São só avisos: nenhuma manifestação é bloqueada por prazo.

No Nanci

O Nanci é um aplicativo de desktop para Windows, com interface visual. A tela de NF-e tem duas abas. Em Notas, dá para selecionar notas e registrar a Ciência: um diálogo mostra as notas elegíveis e as que ficam de fora, com o motivo, antes do envio. Em Pendências ficam as notas sem manifestação conclusiva e os prazos. As conclusivas são feitas nota a nota, num diálogo que pede o tipo, a justificativa quando exigida e uma revisão final.

Quem prefere automatizar pode usar a linha de comando:

# Ciência da Operação: primeiro a simulação, depois o envio
nanci.exe nfe ciencia --cnpj 12345678000199 --todos-resumos
nanci.exe nfe ciencia --cnpj 12345678000199 --todos-resumos --confirmar

# Operação não Realizada de uma nota, com justificativa
nanci.exe nfe manifestar --cnpj 12345678000199 --chave <CHAVE> --tipo nao_realizada \
  --justificativa "Mercadoria recusada no recebimento" --confirmar

# Notas sem manifestação conclusiva que vencem em até 30 dias
nanci.exe nfe pendentes --cnpj 12345678000199 --vencendo-em 30

Sem --confirmar, nada é enviado: o comando só mostra a simulação.

Se a sua empresa precisa que isso aconteça dentro do próprio ERP, é o trabalho que fazemos em integrações.

Este texto registra o que a API faz de verdade. Os comportamentos descritos foram verificados em chamadas reais, e a API pode mudar depois disso.

Resumo

• O User-Agent padrão do curl recebe 403.
• O token dura 1740 segundos, e o tutorial do portal diz 300. Não há refresh token.
• O limite é uma rajada de 25 requisições, com reposição de 1 por segundo, contado por endereço de origem.
• Erros de validação voltam como HTTP 500.
• A paginação começa em 1 no pedido e em 0 na resposta.
• Quase todo download responde 500 a Accept: application/json. Com Accept: */* o arquivo vem.
• O portal documenta 35 rotas a mais. As sete que testamos responderam 404.

O comportamento real, ponto a ponto

User-Agent: o primeiro 403

A API fica atrás do Cloudflare. Ele responde 403 ao User-Agent padrão do curl, até para a URL do próprio documento OpenAPI. A saída é enviar um User-Agent que descreva o seu programa.

É o primeiro obstáculo e o mais confuso, porque parece erro de credencial e não é.

Autenticação

A autenticação é OAuth 2.0 no fluxo client credentials. O servidor é um Keycloak, no realm externo. As credenciais saem do Portal de APIs da ANVISA, com login Gov.br: um Client ID e um Client Secret.

Três detalhes que encontramos:

• O token dura 1740 segundos (29 minutos). O tutorial do portal diz 300.
• Não há refresh token. Quando o token vence, o programa pede outro.
• O token traz um único papel, CONSULTASEXTERNAS_LEITURA.

Vale guardar o token e renovar um pouco antes do vencimento, em vez de pedir um novo a cada chamada.

Limite de requisições

O gateway usa um token bucket: aceita uma rajada de 25 requisições e repõe 1 por segundo. O limite aparece só nos cabeçalhos X-RateLimit-* das respostas.

O saldo é contado por endereço de origem, não por Client ID. As rotas públicas do portal, que nem pedem autenticação, passam pelo mesmo gateway e gastam o mesmo saldo. Programas que saem pelo mesmo endereço dividem o limite, mesmo com credenciais diferentes.

Paginação

No pedido, as páginas começam em 1. Enviar page: 0 devolve erro. As respostas são objetos Page do Spring, que começam em 0. A página que você pede como 1 volta identificada como 0.

Filtros obrigatórios

• POST /udi exige pelo menos uma chave em filter.
• POST /fila/consulta e POST /lista/consulta exigem filter.subfila. Isso mesmo: a de lista também pede subfila.

Chaves de filtro que verificamos:

• udi: nomeComercial (trecho do nome), udiDi (valor exato), cnpjDetentora, codigoGmdn e nuRegistro.
• nomeTecnico: nomeTecnico (trecho do nome) e categoriaProduto.
• termoGmdn: conteudo.

POST /assunto/ estava quebrado nos nossos testes: respondia 500 e não lia o corpo enviado.

Erros

Falhas de validação voltam como HTTP 500. O corpo traz os campos status, mensagem, data_hora e mensagem_detalhada.

Isso muda o tratamento de erro. Um 500 aqui muitas vezes quer dizer “o pedido está errado”, e tentar de novo não resolve. É preciso ler a mensagem.

Fila e lista

fila/consulta e lista/consulta devolvem a subfila ou sublista inteira em um array. Vimos respostas com 40, 35, 71 e 555 linhas. Os parâmetros page e size são ignorados.

Uma subfila vazia responde 404 com corpo vazio. Um código de subfila que não existe recebe a mesma resposta, então não dá para distinguir os dois casos.

Datas

As datas vêm como inteiros, em milissegundos desde 1º de janeiro de 1970.

Downloads

Aqui o documento OpenAPI descreve uma resposta 200 OK sem conteúdo e não fala do cabeçalho Accept. Na prática, é outra história.

• Com Accept: application/json, quase todo download responde 500, com a mensagem “Could not find acceptable representation”. As exceções que vimos foram GET /udi/{id}/download e o arquivo semanal de GET /udi/historico/{id}/download. Com Accept: */* o arquivo vem.
• Quando a resposta informa o Content-Type, ele é application/vnd.ms-excel, mesmo que o arquivo seja um .xlsx ou um zip.
• POST /assunto/downloadAssuntoFormulario recebe como corpo JSON só um número inteiro, em vez do objeto que o documento declara. A resposta vem sem Content-Type e sem Content-Disposition.
• No download da fila (POST /fila/downloadfila), uma subfila vazia responde 500. Na consulta, uma subfila vazia responde 404.

O que está documentado e ainda não existe

O documento OpenAPI tem 32 rotas. As páginas do portal descrevem mais 35, no mesmo endereço base: certificados, empresa nacional e internacional, dossiê, alimentos e produtos de saúde.

Testamos sete delas. Todas responderam o 404 padrão do Spring. Pelo que vimos, estão documentadas e ainda não estão no ar.

Os mesmos conjuntos de dados existem em CSV no portal de dados abertos da ANVISA. O arquivo que conferimos, o de produtos irregulares, era atualizado nos dias úteis.

Como verificamos

Fizemos chamadas reais à API e gravamos as respostas. Elas estão no repositório anvisa-api, na pasta fixtures, com um manifesto. Os testes do cliente rodam sobre essas respostas gravadas.

As correções ao documento da ANVISA estão em um arquivo à parte, no formato OpenAPI Overlay. O documento original fica como foi publicado, só reformatado, e dá para ver exatamente o que mudamos.

Um processo automático baixa de novo, duas vezes por mês, as páginas do portal sobre as rotas que ainda não estão no ar. Se a ANVISA mudar essas páginas, isso aparece como um diff no repositório.

As filas de análise também saem todo dia como feeds Atom, no projeto anvisa-feeds.

O que não sabemos: se esses comportamentos são intencionais e por quanto tempo vão continuar assim.

Um cliente que já trata isso

Publicamos um cliente em Python com licença MIT. Ele envia o User-Agent, guarda o token e renova antes do vencimento, respeita o limite do gateway para não receber 429 (requisições demais), usa Accept: */* nos downloads e transforma a maior parte dos erros 500 em exceções específicas.

uv tool install anvisa      # ou: pipx install anvisa

As credenciais vêm das variáveis ANVISA_CLIENT_ID e ANVISA_CLIENT_SECRET. O número 167 no exemplo é o código de uma subfila.

from anvisa import Client

with Client.from_env() as anvisa:
    for row in anvisa.fila.consulta(167):
        print(row.nuOrdem, row.numeroProcessoFormatado, row.dsAssunto)

    for device in anvisa.udi.iter_search(nomeComercial="cateter"):
        print(device.udiDi, device.nomeComercial)

Ele cobre as 32 rotas do documento publicado. O projeto não tem vínculo com a ANVISA.

Quem integra com serviços da Receita e da SEFAZ encontra o mesmo tipo de surpresa; o post sobre baixar NFS-e, NF-e e CT-e trata disso.

Se a sua empresa depende de um sistema ou de uma API que não se comporta como a documentação diz, é esse o trabalho que fazemos em engenharia reversa e em integrações.

O caminho fácil é um banco de fotos. Só que a foto não diz nada sobre o post nem sobre quem escreveu, e a mesma imagem aparece em centenas de outros sites. Fizemos diferente, e o processo foi parecido com o que fazemos nos projetos de clientes.

O que a imagem precisava ter

• Ser única por post, sem ninguém desenhar uma a uma.
• Sair sempre igual para o mesmo post, a cada vez que o site é publicado.
• Ter a cara do site: fundo claro, traço fino, um único acento rosa.
• Ser gerada automaticamente, sem depender de nenhum serviço externo.

Como trabalhamos

Cada ideia virou uma página de testes, com as capas de três posts lado a lado: o da API da ANVISA, o de notas fiscais e o da API do Mercos. Assim dava para comparar de verdade, com os títulos reais, em vez de imaginar.

As variações foram geradas por um agente de IA de programação. A cada rodada, ele escrevia o código de várias ideias e montava a página de testes a partir dos nossos comentários. Gerar uma rodada inteira levava minutos. A parte que exigia gente era olhar e decidir.

O critério de decisão foi olhar. Uma ideia que parecia ótima no papel podia sair sem graça, e o contrário também aconteceu. Foram sete rodadas.

Rodada 1: desenhar os dados do projeto

A primeira ideia foi usar informações do próprio código de cada projeto: a lista de arquivos como uma planta baixa, o histórico de alterações como uma régua, os horários de trabalho como uma grade.

A planta baixa foi considerada interessante. O histórico, não. Na revisão, o comentário foi:

“Histórico de commit é ruim, pois alguns desses têm pouco e fica vazio, e vai ficar vazio com o tempo.”

Um projeto pequeno gera uma imagem pobre, e continua assim. Também testamos o céu do Recife no dia da publicação, que ficou bonito, mas “não é característico o suficiente”.

Rodada 2: arte a partir de um código único

Trocamos os dados por algo que nunca falta: o código de identificação da primeira versão do projeto, uma sequência de 40 letras e números. A partir dele, um programa pode gerar qualquer desenho, e o mesmo código gera sempre o mesmo desenho.

Testamos oito estilos: ladrilhos, curvas de nível, linhas de fluxo, uma cordilheira, uma fita métrica, peças de um molde de costura, cores e um harmonógrafo, que simula a caneta presa a dois pêndulos.

O veredito: “o fluxo e as curvas não são tão distintos”, “o molde parece legal, mas meh, e a fita também é meio sem graça”. E o harmonógrafo “tá ganhando”.

Rodada 3: imagens quase iguais

Para ter mais variedade, montamos uma família de máquinas de desenho parecidas com o harmonógrafo. Foi aí que apareceu o problema mais interessante do processo.

Esses dois desenhos vieram de códigos diferentes e saíram quase iguais. A pergunta na hora foi: “pode ter várias colisões visuais, concorda?” Concordamos. Um código único não garante um desenho único. Se a regra do desenho só sabe fazer algumas dezenas de formas, dois posts vão acabar com a mesma.

Isso mudou o critério: além de bonito, o estilo precisa ter muitas formas possíveis. E mudou a direção. O pedido seguinte foi “máquina de desenho não, outras coisas”, e o harmonógrafo, que estava ganhando, saiu da disputa.

Rodadas 4 e 5: outros caminhos

Tentamos de tudo um pouco. Desenho técnico de uma peça usinada, células pintadas como as da página inicial, um número grande que resume o post, uma palavra do título medida.

Depois, fractais, caos matemático, mosaicos coloridos e até sistemas planetários.

Alguns eram bonitos. Da rodada 5, o veredito foi “não gostei de nenhum”. Na nossa leitura, fractais e mosaicos coloridos chamam atenção, mas brigam com o resto do site. Bonito não basta, precisa combinar.

Rodada 6: olhar referências

Em vez de criar mais variações, montamos uma lista de referências de arte gerada por computador e escolhemos as que valia a pena testar: plantas que crescem por regras, o crescimento de um mofo, o kolam (desenho tradicional indiano em volta de pontos) e outras.

As plantas quase convenceram. Faltava resolver a composição, porque o título cobria o desenho na imagem de compartilhamento. E veio a pergunta: dá para fazer em 3D?

Rodada 7: plantas em 3D

A primeira versão em 3D tinha piso em perspectiva e sombras. O comentário foi curto: “o 3D ficou estranho”.

Corrigimos troncos, câmera e sombras. Melhorou, mas ainda havia dois problemas: “o piso tá tosco” e “parece que tem uma árvore repetida em cada post, só mudando a escala dela”.

A resposta foi ter cinco espécies, cada uma com várias regras de crescimento, galhos podados ao acaso e nunca a mesma espécie duas vezes na mesma imagem. Por último, saíram o chão e as sombras, e o tracejado rosa que contornava só o título passou a contornar a imagem inteira.

O resultado não é perfeito. O cipreste às vezes sai fino como um palito, e o pinheiro pode ficar ralo. Mesmo assim, a versão foi considerada boa o bastante. Ela cumpre todos os requisitos, e cedo ou tarde é preciso decidir: uma capa que já funciona vale mais publicada do que em mais uma rodada de ajustes.

O resultado

Cada post ganha um pequeno jardim, desenhado a partir do código da primeira versão do projeto de que ele fala. Quando o post não fala de um projeto, o código usado é o endereço do próprio post, como neste. A capa do topo mostra só as plantas. A imagem de compartilhamento tem o título, duas plantas e a moldura tracejada do site.

Ninguém desenha as capas, e mesmo assim cada uma é só daquele post. Quando um post novo entrar, ele ganha o seu jardim sem que ninguém precise fazer nada.

O que isso diz sobre como trabalhamos

• Testar barato e olhar de verdade. Com o agente de IA gerando as variações, cada rodada levou pouco tempo e mostrou o resultado real, com o conteúdo real.
• Descartar sem dó. Mais de trinta ideias ficaram pelo caminho, várias delas bonitas.
• Decidir com critério. O critério mudou no meio do caminho, quando apareceram as imagens quase iguais, e isso foi bom.
• Saber parar. Quando a solução cumpre os requisitos, a próxima rodada de ajustes custa mais do que entrega.

É o mesmo jeito de trabalhar nos sistemas que fazemos para clientes. Quem quiser os detalhes técnicos, com código, encontra no post sobre como as capas são geradas.

Resumo

• A semente é o hash do primeiro commit do repositório de que o post fala, guardado num JSON. Sem repositório, é o SHA-1 do endereço do post.
• O desenho é um L-system em 3D: cinco espécies, regras com variantes, poda, gravidade e espessura pelo número de pontas.
• Tudo vira SVG, e o sharp transforma em WebP (capa) e PNG (compartilhamento).
• O título no PNG é escrito pelo próprio sharp. Ele não leu a fonte em WOFF2; com o TTF funcionou.
• Duas rotas estáticas do Astro geram os arquivos: /blog/<post>/capa.webp e /blog/<post>/og.png.

Os requisitos

1. Uma imagem diferente por post, sem desenhar à mão.
2. A mesma imagem a cada build.
3. Nada de rede no build. O site já tem um build de teste que roda sem acesso à internet.
4. Nenhuma dependência nova, se possível.
5. A identidade do site: fundo claro, traço em azul-escuro, um único acento rosa.

A semente

A primeira tentativa usou dados vivos do repositório: árvore de arquivos, datas dos commits. Repositório com poucos commits gera uma imagem vazia, e continua vazia. Por isso a semente passou a ser algo fixo: o hash do primeiro commit.

import firstCommits from "./first-commits.json";

export function seedFor(post: Post): Seed {
    const repo = post.data.projects.find((name) => name in firstCommits) as keyof typeof firstCommits | undefined;
    if (repo) return { hash: firstCommits[repo], source: repo };
    return { hash: createHash("sha1").update(post.id).digest("hex"), source: "" };
}

O JSON foi preenchido uma vez, com a API do GitHub. O primeiro commit não muda, então não há o que atualizar.

Do hash sai um gerador de números pseudoaleatórios de 32 bits. Cada decisão do desenho consome o próximo número, sempre na mesma ordem.

function random(hash: string) {
    let a = (parseInt(hash.slice(0, 8), 16) ^ parseInt(hash.slice(8, 16), 16)) | 0;
    return () => {
        a = (a + 0x6d2b79f5) | 0;
        let t = Math.imul(a ^ (a >>> 15), 1 | a);
        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
    };
}

Hash único não é desenho único

Uma das rodadas testou uma família de máquinas de desenho. Os dois espirógrafos abaixo vieram de hashes diferentes.

O espirógrafo depende de dois inteiros pequenos, os tamanhos das engrenagens. Do jeito que estava montado, havia só algumas dezenas de combinações, e várias davam a mesma estrela. O hash tem 160 bits, e mesmo os 32 que o gerador usa dão mais de 4 bilhões de sementes. Mas o desenho só sabia fazer poucas formas.

A regra que ficou: o desenho precisa de muitos parâmetros contínuos, e a avaliação de “parecido” é feita olhando as imagens, não comparando os números.

L-system em 3D

Um L-system é uma gramática que reescreve uma palavra várias vezes. Depois, uma tartaruga (como a da linguagem Logo) lê a palavra e desenha. Usamos os símbolos de The Algorithmic Beauty of Plants, de Prusinkiewicz e Lindenmayer:

A tartaruga guarda três vetores (direção, esquerda e cima), e cada giro é uma rotação em torno de um deles, pela fórmula de Rodrigues.

const turn = (v: V, k: V, a: number): V =>
    add(add(mul(v, Math.cos(a)), mul(cross(k, v), Math.sin(a))), mul(k, dot(k, v) * (1 - Math.cos(a))));

Uma versão com uma regra por espécie gerou o problema de sempre: a mesma árvore em todos os posts, só em escala diferente. O que resolveu:

• Cinco espécies, com silhuetas diferentes: copa larga, arbusto (o da figura 1.25 do livro), chorão, cipreste e pinheiro.
• Variantes por regra. As regras principais têm duas a quatro reescritas possíveis, e o gerador escolhe uma a cada passo.
• Faixas em vez de valores fixos para o ângulo, a altura do tronco e o quanto os galhos pendem.
• Poda. Ao abrir um ramo, há uma chance de pular o ramo inteiro, o que deixa as copas irregulares.
• Espécies diferentes no mesmo jardim.

Dois detalhes deram o ar natural:

• Gravidade. Depois de cada F, a direção gira um pouco em direção ao chão, proporcional ao quanto o galho está fora da vertical.
• Espessura. Percorrendo os galhos de trás para frente, cada um recebe a soma das pontas que sustenta. A largura do traço cresce com a raiz dessa soma, até um limite.

for (let i = segments.length - 1; i >= 0; i--) {
    const seg = segments[i];
    seg.load = tips.get(key(seg.b)) ?? 1;
    tips.set(key(seg.a), (tips.get(key(seg.a)) ?? 0) + seg.load);
}

Câmera e traço

A câmera olha quase de frente, girada até 8 graus para os lados, um pouco de cima, com perspectiva leve. Os galhos são desenhados do mais distante para o mais próximo, e os distantes ficam mais claros e mais finos.

A primeira versão usava transparência nos traços. Onde dois segmentos se encontram, as pontas arredondadas se sobrepunham e escureciam, e os troncos pareciam listrados. A solução foi usar cores sólidas, misturadas com a cor do fundo conforme a distância.

Para o SVG não ficar enorme, os segmentos com a mesma cor e a mesma largura vão para um único <path>.

Ficaram limitações conhecidas: o cipreste às vezes sai fino como um palito, e o pinheiro pode ficar ralo. Foram aceitas. O resultado cumpre os requisitos, e mais uma rodada de ajustes não mudaria isso.

O piso em perspectiva e as sombras ficaram de fora. Funcionavam tecnicamente, mas pareciam artificiais perto do traço fino do resto do site.

Do SVG ao arquivo

O sharp, que o Astro já usa para imagens, lê SVG e exporta qualquer formato.

export async function coverImage(seed: Seed) {
    return sharp(svg(garden(seed.hash, box)), { density: 144 }).webp({ quality: 82 }).toBuffer();
}

Com density: 144, o SVG de 1200 × 630 vira uma imagem de 2400 × 1260, para telas de alta densidade. Cada capa ficou com cerca de 100 KB.

A imagem de compartilhamento precisa do título escrito em PNG, porque as redes sociais não aceitam SVG. Aqui houve um tropeço.

O título e a fonte

O sharp aceita texto como entrada e o desenha com o Pango, passando o arquivo da fonte em fontfile. Com o WOFF2 que o site serve, o resultado saiu numa fonte monoespaçada genérica, sem erro nenhum.

A solução foi baixar o TTF variável da Anybody, a mesma família, do repositório oficial do Google Fonts (licença OFL). Com ele, o Pango aceita os eixos da fonte variável na própria descrição:

const heading = await sharp({
    text: {
        // The title goes into Pango markup, so & and < must be escaped.
        text: `<span foreground="#0e1a2b" letter_spacing="-820">${markup(title)}</span>`,
        font: "Anybody 46 @wght=650,wdth=115",
        fontfile: "src/assets/fonts/anybody-variable.ttf",
        width: 540,
        align: "centre",
        rgba: true,
        dpi: 72,
    },
}).png().toBuffer({ resolveWithObject: true });

Três detalhes:

• @wght=650,wdth=115 aplica peso e largura, os mesmos do título do site. Conferimos comparando com wdth=112.5: a largura do texto muda.
• letter_spacing é medido em 1/1024 de ponto. Com dpi: 72, um ponto vale um pixel, então -820 dá cerca de -0,8 px. O código usa 18 vezes o tamanho da fonte, para o espaço apertar junto com as letras.
• width faz o Pango quebrar as linhas. Para a última linha não ficar com uma palavra só, o código estreita a largura de 20 em 20 px enquanto o número de linhas não muda, e fica com a mais estreita.

Palavras com hífen, como NF-e, vão dentro de <span allow_breaks="false">. Sem isso, o Pango quebrava a linha no hífen e deixava “e” sozinho embaixo.

O título fica no centro, com uma planta de cada lado. Na prévia pequena, o WhatsApp recorta a imagem num quadrado do meio, e um título à esquerda saía cortado.

O título sob medida

O tamanho da fonte não é fixo. O código começa em 76 px e diminui de 2 em 2 até as letras caberem no quadrado do meio, em três linhas no máximo. Títulos curtos saem grandes, e os longos, menores.

Para saber o tamanho das letras, o código lê o canal de transparência da imagem do título e acha o primeiro e o último pixel pintados. A caixa que o Pango devolve não serve, porque inclui o espaço reservado acima e abaixo de cada linha.

Com essas medidas, a imagem ganha duas linhas de cota em rosa, como as do topo do site: uma em cima, com a largura das letras, e outra ao lado, com a altura. Os números são os pixels reais de cada título.

Atrás de tudo fica a mesma grade de desenho técnico do site, que some perto das bordas. Na moldura, quatro marcas curtas em rosa mostram onde fica o quadrado que o WhatsApp recorta.

O texto alternativo da imagem segue as mesmas medidas: diz o título, o tamanho das letras e de onde vieram as plantas.

O título vira uma imagem com fundo transparente e é colado sobre o desenho com composite. O nome do site, na moldura tracejada, segue o mesmo caminho.

O TTF tem 201 KB e é usado só no build. O navegador continua baixando o WOFF2.

As rotas no Astro

Cada arquivo é uma rota estática com getStaticPaths, ao lado da página do post:

// src/pages/blog/[slug]/og.png.ts
export const getStaticPaths = (async () => {
    const posts = await getPosts();
    return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
}) satisfies GetStaticPaths;

export const GET: APIRoute<{ post: Post }> = async ({ props }) => {
    const image = await shareImage(props.post.data.title, seedFor(props.post));
    return new Response(new Uint8Array(image), { headers: { "Content-Type": "image/png" } });
};

A página do post aponta og:image, twitter:image e o image dos dados estruturados para /blog/<post>/og.png, com um texto alternativo que explica de onde vem o desenho.

O que ficou de fora

Referências

• Prusinkiewicz e Lindenmayer, The Algorithmic Beauty of Plants.
• Documentação do sharp: entrada de texto e composite.
• Pango: descrição de fontes, incluindo os eixos de fontes variáveis.
• Astro: rotas de arquivos estáticos.
• A fonte Anybody, no repositório do Google Fonts.

Uma IA como o ChatGPT ou o Claude resume isso bem. O difícil é tirar as mensagens do WhatsApp de um jeito organizado, só das conversas certas e sem entregar tudo a um serviço de terceiros no caminho.

Fizemos o whatsapp-group-reader para isso. É um aplicativo local, de código aberto, que lê o texto das conversas que você escolher e exporta num formato pronto para colar numa IA.

Resumo

• Lê só as conversas marcadas por você. Nada é sincronizado sozinho.
• Só lê. Não envia mensagens, reações, presença nem confirmação de leitura, e não baixa mídia.
• Tudo fica no seu computador, num banco local. Não há servidor na nuvem nem integração direta com IA.
• Exporta em texto compacto, para colar numa IA, ou em JSONL, para quem programa.
• Usa um cliente não oficial do WhatsApp. Existe risco de bloqueio da conta, e não dá para eliminá-lo.

Como funciona

1. Você abre o aplicativo e vincula o celular pelo QR, como no WhatsApp Web.
2. Atualiza a lista de conversas, marca só as conversas autorizadas pelos participantes e salva.
3. Escolhe o período, por exemplo as últimas 24 horas e no máximo 500 mensagens por conversa.
4. Clica em Sincronizar agora.
5. Exporta em texto para IA, ou baixa o JSONL completo.

A exportação para IA tem um cabeçalho de contexto e marcadores separando cada conversa. É só colar e perguntar: “resuma o que foi decidido”, “liste as pendências por pessoa”, “quais prazos foram combinados”.

Tirar uma conversa da seleção interrompe as próximas coletas, mas não apaga o que já foi salvo. O banco, a sessão e as exportações ficam na pasta de dados do usuário, e o aplicativo mostra onde.

Por que não usar uma biblioteca que fala direto com o servidor

Existem bibliotecas que reimplementam o protocolo do WhatsApp e conversam com o servidor por conta própria. Escolhemos o caminho oposto: o whatsapp-web.js controla o próprio WhatsApp Web, dentro de um navegador de verdade. Do lado do WhatsApp, o que aparece é o WhatsApp Web.

A aposta é que isso reduz o risco de bloqueio. Não dá para provar, porque o WhatsApp não documenta como detecta automação. Mas é a escolha conservadora: não há protocolo reconstruído para manter, e o comportamento fica colado ao cliente oficial. O custo é precisar de um navegador. No Windows, o aplicativo usa o Edge que já vem instalado.

Devagar de propósito

O aplicativo não tenta ser rápido. Ele lê uma conversa por vez, em blocos de 50 mensagens, com intervalos aleatórios entre blocos e entre conversas, e pausas maiores depois de alguns lotes. Uma conversa consultada há pouco tempo entra em espera antes de poder ser lida de novo.

Há dois ritmos: Conservador, o padrão, e Balanceado. Falhas de leitura têm no máximo duas novas tentativas, com espera crescente. A fila pode ser pausada, retomada ou cancelada sem perder o que já foi coletado.

Isso espaça as leituras que o aplicativo pede. Não controla o que o WhatsApp Web faz por conta própria, não imita uma pessoa e não elimina o risco do cliente não oficial.

O que fica de fora

O foco é texto. Mídia sem legenda, chamadas, reações, enquetes, status, canais e mensagens de sistema são ignorados. De uma foto ou vídeo com legenda, sai só o texto da legenda.

O painel de diagnóstico guarda só os 200 eventos mais recentes, em memória, e nunca registra o texto das mensagens.

Antes de usar, três cuidados

• Combine com o grupo. As mensagens não são só suas. Ler e exportar a conversa de outras pessoas para uma IA pede que elas saibam e concordem, ainda mais em grupos com clientes e fornecedores. Quem entrar no grupo depois também precisa saber.
• Escolha a IA com cuidado. O aplicativo não envia nada a lugar nenhum, mas o texto colado numa IA segue as regras daquele serviço. Para conversas sensíveis, confira se o plano usado não aproveita os dados para treinamento.
• Conte com o risco de bloqueio. É um cliente não oficial, e o bloqueio atinge o número vinculado, que é o mesmo que está nos grupos. Avalie isso antes de usar o número principal da empresa.

Para quem quer instalar

No Windows 10 e 11, há um pacote portátil de cerca de 50 MB, com tudo embutido:

1. Nas propriedades do arquivo .zip, marque “Desbloquear”, se a opção aparecer.
2. Extraia numa pasta curta e fora do OneDrive, como C:\WhatsAppReader. São necessários cerca de 250 MB livres.
3. Abra o Iniciar.cmd. O navegador abre sozinho no aplicativo. A primeira abertura pode levar 1 a 2 minutos.
4. Deixe a janela preta aberta enquanto usa. Ela é o programa.

Para desenvolvedores, o projeto roda no Windows e no macOS, com Node.js 24 ou mais recente:

git clone https://github.com/vasfvitor/whatsapp-group-reader
cd whatsapp-group-reader
corepack enable
pnpm install
pnpm dev

O projeto é uma prova de conceito. Funciona com um telefone e uma sessão por máquina, sem nuvem e sem vários usuários.

Se a sua empresa quer usar IA em cima das próprias conversas, documentos ou sistemas, com os dados sob controle, esse é o trabalho que fazemos em soluções com IA. Quando a pergunta é sobre os dados de um aplicativo, e não sobre conversas, o caminho é falar com o seu banco de dados.