Importação por NCM — Comex Stat (Brasil)

Português

Dados oficiais, públicos e agregados de importação e exportação do Brasil, direto da API pública Comex Stat (MDIC). Uma linha por NCM × mês × país, UF ou via de transporte, com FOB (US$), peso líquido (kg), quantidade estatística, CIF, frete, seguro e FOB US$/kg. Não identifica importadores nem pessoas físicas.

Para que serve

• Acompanhar volume e preço médio (US$/kg) de importação de um produto (NCM).
• Ver de quais países o Brasil compra e por quais UFs ou vias a mercadoria entra.
• Montar séries mensais e tendências de 12 meses.

Input

{
  "flow": "import",
  "ncms": ["10019900", "27090010"],
  "periodoDe": "2025-01",
  "periodoAte": "2025-01",
  "paises": [],
  "ufs": [],
  "detalhar": "pais",
  "metricas": ["metricFOB", "metricKG", "metricStatistic", "metricFreight", "metricInsurance", "metricCIF"],
  "incremental": false,
  "maxItems": 1000,
  "timeoutSecs": 30
}

Campo	Descrição
flow	import ou export. Na exportação não há CIF, frete nem seguro.
ncms	NCMs de 8 dígitos ou prefixos de 2 a 7 dígitos (expandidos pela tabela oficial).
periodoDe, periodoAte	Mês no formato AAAA-MM, desde 1997 (até 120 meses por run).
paises	Códigos de país do MDIC (não ISO). Vazio = todos.
ufs	Siglas de UF, como SP. Vazio = todas.
detalhar	pais, uf ou via. NCM e mês sempre vêm.
metricas	Métricas oficiais; FOB e KG sempre incluídas.
maxItems	Máximo de linhas de dados (1 a 100.000).
incremental	Se true, só consulta de novo quando a fonte oficial for atualizada.
timeoutSecs	Tempo máximo por requisição (1 a 120 s).

O transporte usa conexão direta com a API oficial. O modo de proxy residencial foi removido desta versão pública; inputs antigos com proxyResidencialBR são rejeitados.

Saída

Cada linha traz source_url, source_request (corpo do POST para reproduzir a consulta), source_sha256, retrieved_at (ISO 8601, -03:00), source_name, warnings e status:

Status	Significado
ok	Linha completa: todo dado solicitado presente, sem warnings. Pode ter notas (métrica não solicitada, dimensão não detalhada, kg_liquido = 0 com usd_por_kg null); kg_liquido = 0 sai ok e é cobrada.
parcial	Falta dado solicitado (dimensão detalhada, descrição do NCM, métrica pedida ou usd_por_kg sem FOB/KG). Linhas parcial não são cobradas; só linhas ok geram o evento relatorio-ncm. Métricas não solicitadas e dimensões não detalhadas vão para notas e não mudam o status.
sem_resultado	Consulta sem linhas (diagnóstico gratuito).
fonte_indisponivel	A Comex Stat ficou fora do ar (HTTP 429/5xx, timeout ou falha de conexão) mesmo após as retentativas, com error_message (diagnóstico gratuito).
erro	Input inválido, layout da fonte mudou ou falha de processamento, com error_message (gratuito).

Os meses são consultados em lotes de 12. Um mês vazio dentro de um lote não gera linha sem_resultado; só um lote inteiro sem linhas gera essa linha, do primeiro ao último mês do lote.

RUN_SUMMARY.motivo pode ser tempo_limite_run (prazo do run), teto_gasto_atingido (teto de gasto), maxItems_atingido (limite de linhas) ou fonte_indisponivel (fonte caiu no meio da coleta). Com linhas já entregues, o status do run (RUN_SUMMARY.status) fica parcial — isso indica coleta interrompida e é diferente do parcial de linha (dado solicitado ausente, não cobrado); as linhas ok já entregues continuam cobradas. Se o prazo estoura antes de qualquer linha, o status fica erro e o motivo continua tempo_limite_run. Rodar de novo depois de um run parcial cobra outra vez as linhas já entregues.

Valores ausentes ficam null com aviso; nada é inventado. US$/kg agregado = soma FOB / soma kg. O resumo da execução (RUN_SUMMARY) traz rankings, série mensal e tendências de 12 meses. Quando a fonte limita requisições (HTTP 429) ou falha (5xx), o Actor espera e tenta de novo automaticamente, com no máximo 150 s de espera somados no run.

Quando a Comex Stat está fora do ar

• Nenhuma linha entregue: o run termina com sucesso (código de saída 0), grava uma linha de diagnóstico gratuita com status fonte_indisponivel, o RUN_SUMMARY fica com status e motivo fonte_indisponivel, e a mensagem de status mostra Comex Stat indisponível (HTTP xxx); nada cobrado. Nada é cobrado. Antes, HTTP 429/5xx terminava o run com código de saída diferente de zero; isso mudou.
• Fonte cai no meio: o run termina com sucesso, RUN_SUMMARY.status = parcial e motivo = fonte_indisponivel; só as linhas já entregues são cobradas, e uma linha de diagnóstico gratuita marca os meses não coletados.
• Input inválido ou layout da fonte alterado continuam terminando com código de saída 1 (status = erro).
• O Actor encerra a coleta até 45 s antes do timeout do run; com timeout de até 300 s, encerra no máximo 180 s após o início.
• Em runs não incrementais cujo período termina há mais de 3 meses, a consulta de data de atualização da fonte é dispensada (RUN_SUMMARY.atualizacao_dispensada = true), o que evita uma pausa de 11 s.

Preço

US$ 1,50 por 1.000 linhas válidas (US$ 0,0015 por evento relatorio-ncm). Você paga só pelas linhas válidas: diagnósticos, erros e consultas sem resultado são gratuitos. O teto de gasto definido por você é respeitado. Sem custo de plataforma para o usuário.

English

Official, public, aggregated Brazilian import/export statistics from the Comex Stat public API (MDIC). One row per NCM code × month × country, state or transport mode, with FOB USD, net weight (kg), statistical quantity, CIF, freight, insurance and FOB USD/kg. No importer or personal data.

Input: flow (import/export), NCM codes or prefixes, period (YYYY-MM), optional MDIC country codes and state abbreviations, breakdown (pais, uf or via), metrics, maxItems, optional incremental mode and per-request timeout. See the example above.

Transport: direct connection to the official API. Residential proxy mode is removed; old inputs containing proxyResidencialBR are rejected.

Output: every row includes the official source URL, the replayable POST body, a SHA-256 of the response, timestamp, warnings and status (ok, parcial, sem_resultado, fonte_indisponivel, erro). Missing values are null with a warning, never invented. The run summary includes rankings, monthly series and 12-month trends. Rate limits (HTTP 429) and 5xx errors are retried automatically with backoff, capped at 150 s of total waiting per run.

When Comex Stat is down:

• No rows delivered: the run succeeds (exit code 0), writes one free diagnostic row with status fonte_indisponivel, sets RUN_SUMMARY.status and motivo to fonte_indisponivel, and the status message reads Comex Stat indisponível (HTTP xxx); nada cobrado ("Comex Stat unavailable; nothing charged"). Nothing is charged. Previously, HTTP 429/5xx ended the run with a non-zero exit code; that contract has changed.
• Source fails mid-run: the run succeeds with RUN_SUMMARY.status = parcial and motivo = fonte_indisponivel; only rows already delivered are charged, and a free diagnostic row marks the months not collected.
• Invalid input or a changed source layout still end with exit code 1 (status = erro).
• Collection stops at least 45 s before the run timeout; with a timeout of 300 s or less, it stops no later than 180 s after start.
• Non-incremental runs whose period ended more than 3 months ago skip the source's last-update lookup (RUN_SUMMARY.atualizacao_dispensada = true), avoiding an 11 s pause.

parcial rows (requested data missing) are never charged; only ok rows trigger relatorio-ncm. Unrequested metrics and non-detailed dimensions go to notas and do not change the status.

Months are queried in batches of 12. An empty month inside a batch does not emit a sem_resultado row; only a fully empty batch does, covering the first through the last month of that batch.

RUN_SUMMARY.motivo can be tempo_limite_run (run time limit), teto_gasto_atingido (spending cap), maxItems_atingido (row cap) or fonte_indisponivel (source went down mid-run). When rows were already delivered, the run status (RUN_SUMMARY.status) is parcial: the run was cut short. This is not the row-level parcial (requested data missing, not charged); ok rows already delivered remain charged. If the time limit hits before any row, status is erro and the motivo stays tempo_limite_run. Rerunning after a partial run charges again for rows already delivered.

Pricing: US$1.50 per 1,000 valid rows (US$0.0015 per relatorio-ncm event). You pay only for valid rows; diagnostics, errors and empty queries are free. Your spending limit is respected. No platform usage cost for users.

Data source: Comex Stat / MDIC. This Actor is independent and not affiliated with the Brazilian government.

Related Actors

More Actors from the same publisher:

• Brazil Diesel Fuel Prices ANP (Preço do Diesel): Weekly average, minimum and maximum diesel prices (S10/S500) from the ANP survey, by state or city.
• Brazil CNPJ Bulk Lookup - Receita Federal (CNPJ em Lote): Bulk lookup of Brazilian company CNPJs in Receita Federal open data. Companies only, no partners or contacts.
• Brazil Anatel Certified Products (Produtos Homologados): Search, new-entry tracking and bulk validation of Anatel certified products from open data.
• Brazil Public Tender Prices CATMAT/CATSER (Preço Público): Public purchase prices by CATMAT, CATSER or description from Compras.gov.br, cross-checked on PNCP.

Browse the full catalog: kman-br.github.io (Português).