APIs de dados governamentais: guia prático dados.gov.br

O portal dados.gov.br consolidou milhares de conjuntos de dados federais, mas nem todo dataset listado é API estável pronta para produção. Equipes de produto frequentemente descobrem isso tarde demais — quando o endpoint some após reforma ministerial ou quando metadados prometem atualização diária e o último arquivo tem seis meses.

Este guia oferece critérios práticos para avaliar APIs governamentais antes de acoplar seu sistema. Não substitui due diligence jurídica sobre licenças e reuso, mas evita surpresas técnicas nas primeiras semanas de integração.

Anatomia do catálogo

Cada recurso no dados.gov.br expõe metadados padronizados: título, órgão responsável, periodicidade, formato e link de acesso. A distinção crucial é entre recurso para download (CSV, JSON estático, shapefile) e API com endpoint recorrente. O portal nem sempre deixa isso explícito na listagem — abra a ficha completa e procure campo "URL de acesso" ou documentação vinculada.

Órgãos com governança madura publicam changelog e contato técnico. Ausência de ambos é sinal amarelo. Presença de "última atualização" há mais de noventa dias em dataset declarado como diário é sinal vermelho para dependência em tempo real.

Cinco critérios de avaliação

Antes de comprometer roadmap com um dataset federal, pontue cada critério de 1 a 3:

• Estabilidade de URL: o endpoint mudou nos últimos doze meses? Há redirecionamento documentado?
• Esquema de resposta: campos estão documentados? Tipos são consistentes entre páginas de paginação?
• Autenticação: API aberta, token gratuito ou credencial restrita a convênio institucional?
• Limites de uso: rate limit publicado? bloqueio por IP observado em testes?
• Licença e atribuição: Open Data Commons, restritiva ou silenciosa sobre reuso comercial?

Soma abaixo de 10 sugere cache local e plano B. Soma acima de 12 justifica integração direta com monitoramento leve.

Padrões técnicos que encontramos

APIs federais no Brasil não seguem um único estilo REST. Encontramos REST JSON paginado, GraphQL pontual, serviços SOAP legados e arquivos JSON gigantes atualizados por cron sem API intermediária.

Um produto de compliance em Brasília integrou API de sanções sem cache. O órgão retornou HTTP 503 durante três dias em manutenção não anunciada no catálogo. O produto ficou incompleto para clientes sem aviso prévio.

Para REST paginado, teste a última página e a primeira — inconsistências de total de registros são comuns. Para downloads bulk, verifique checksum ou data de geração no cabeçalho HTTP quando disponível.

Alguns órgãos expõem Swagger ou OpenAPI; outros apenas PDF com exemplos de curl. Trate documentação incompleta como custo de manutenção contínua na sua equipe.

Cache, espelhamento e fallback

Dados públicos permitem espelhamento local na maioria das licenças abertas — confirme na ficha. Pipeline recomendado: ingestão agendada, validação de esquema, armazenamento versionado e exposição interna para sua aplicação.

Defina SLA interno separado do SLA do governo. Se o dataset é crítico, mantenha pelo menos uma versão anterior consultável quando a ingestão falhar. Usuários finais preferem dado de ontem a tela em branco.

Notifique equipe de produto quando a ingestão detectar mudança de esquema — campos novos ou removidos são mais frequentes que indisponibilidade total.

Governança no seu time

Registre em planilha ou wiki interna: dataset ID, órgão, responsável no governo se conhecido, data da última verificação manual e decisão (produção, cache only, descartado). Revise trimestralmente.

Envolva jurídico quando o uso for comercial e a licença for ambígua. Dados pessoais anonimizados de forma insuficiente já geraram questionamentos — mesmo em fontes oficiais.

Contribua de volta quando encontrar erro de metadados: muitos órgãos respondem em canal de ouvidoria ou repositório público. Melhorar o catálogo beneficia todo o ecossistema.

Próximos passos

Comece pelo caso de uso, não pelo catálogo. Defina qual decisão de produto depende do dado e qual atraso é aceitável. Só então busque no dados.gov.br e aplique os critérios acima em no máximo três candidatos.

Para integrações piloto, reserve uma sprint de observação em produção com feature flag antes de expor ao usuário final. Métricas de falha de ingestão devem aparecer no mesmo dashboard de APIs pagas.

Consulta ao portal realizada em May 25, 2026. URLs e políticas de órgãos podem mudar sem atualização imediata do catálogo central. Correções: [email protected].