Exportar lista CSV de CNPJs

Resposta curta

Use export assíncrono quando o volume não cabe em paginação curta. O ganho é previsibilidade operacional: você dispara, acompanha o job e baixa o arquivo com contexto completo.

Quando migrar para export

• Quando a busca deixa de ser exploratória e vira rotina.
• Quando a lista será consumida por mais de um time.
• Quando você precisa de trilha de auditoria por ciclo.

Exemplo de fluxo

# 1) cria o job
curl -X POST "https://api.orbioapi.com.br/v1/exports" \
  -H "Authorization: Bearer $ORBIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"kind":"account_query","spec_version":"2.0","entity":"company","filters":{}}, "format":"csv"}'

# 2) consulta status
curl -H "Authorization: Bearer $ORBIO_API_KEY" \
  "https://api.orbioapi.com.br/v1/exports/exp_123"

# 3) download do arquivo
curl -L "https://download.orbioapi.com.br/exports/exp_123.csv" -o contas.csv

Boas práticas

• Reaproveite os filtros já validados no guia de CNAE.
• Registre export_id, data e snapshot da execução.
• Use retry com backoff em polling para não pressionar o endpoint.
• Mantenha o mesmo schema de colunas entre ciclos para análise comparável.

Limitações

• Polling muito frequente pode gerar ruído operacional sem ganho real.
• CSV grande sem saneamento de colunas pode travar integrações downstream.
• Export sem owner definido perde rastreabilidade no fechamento mensal.

Erros comuns

• Alterar filtros entre validação e export final.
• Baixar arquivo e não registrar evidência do ciclo.
• Misturar arquivos de ciclos diferentes no mesmo pipeline.