# Comex Stat Brasil — Importação e Exportação por NCM (`kodama-data/comex-stat-brasil-importacao-exportacao`) Actor

Importações e exportações oficiais do Brasil (Comex Stat/MDIC) por NCM: país, UF, porto, US$ FOB/CIF, kg, preço médio e variação vs ano anterior.

- **URL**: https://apify.com/kodama-data/comex-stat-brasil-importacao-exportacao.md
- **Developed by:** [Guilherme Kodama](https://apify.com/kodama-data) (community)
- **Categories:** Business, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 linhas

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Comex Stat Brasil — Importação e Exportação por NCM, País, UF e Porto

> Desenvolvido e mantido por **Guilherme Kodama** · GitHub: [github.com/guilhermeKodama](https://github.com/guilhermeKodama)

**Quanto o Brasil importa ou exporta de um produto, de quais países, por quais estados e portos, a que preço — e
como isso mudou em relação ao ano passado?** Este actor consulta a base oficial do **Comex Stat (MDIC/SECEX)** e
entrega uma tabela pronta por **NCM / SH6 / SH4 / capítulo**, com **US$ FOB, US$ CIF, frete, seguro, kg líquido,
quantidade estatística, preço médio US$/kg e US$/unidade, participação por país e variação % contra o mesmo período
do ano anterior**.

### Para quem

- **Importadores e distribuidores**: de onde o Brasil compra o seu produto e a que preço médio CIF/FOB por unidade.
- **Exportadores e tradings**: quais países e UFs puxam as vendas, quem cresceu e quem caiu no ano.
- **Despachantes, comissárias e consultorias de comex**: relatório por NCM e porto (URF) em segundos.
- **Indústria e varejo**: monitorar a concorrência importada (volume e preço) do seu segmento.
- **Analistas e jornalistas**: séries mensais oficiais sem planilha manual.

### O que entrega

Uma linha por produto × quebra (país, bloco, UF, via, URF) × período:
`fluxo`, `periodo`, `codigoProduto`, `produto`, `pais`, `blocoEconomico`, `uf`, `via`, `urf`, `fobUsd`, `kgLiquido`,
`quantidadeEstatistica` + `unidadeEstatistica` (NCM), `freteUsd`, `seguroUsd`, `cifUsd` (importação),
`precoMedioUsdKg`, `precoMedioUsdUnidade`, `participacaoNoProdutoPct`, `fobUsdAnoAnterior`, `kgAnoAnterior`,
`precoMedioUsdKgAnoAnterior`, `variacaoFobPct`, `variacaoKgPct`, `variacaoPrecoKgPct`, `novoNoPeriodo`,
`ultimaCompetenciaDisponivel`.

No key-value store, a chave `RESUMO` traz totais por fluxo, variação anual, top produtos, top países/UFs/portos e avisos.

### Diferenciais

- **Períodos que cruzam o ano** (ex.: últimos 12 meses out→set): a API oficial devolve vazio; o actor divide e soma.
- **Comparação automática com o ano anterior** (valor, peso e preço médio).
- **Preço médio** por kg e por unidade estatística (ex.: US$ por smartphone importado).
- **Busca de NCM por palavra** (`productSearch`), sem precisar saber o código.
- **Modo alerta mensal** (`onlyIfNewMonth`): agende diário; só entrega dados quando o MDIC publica um mês novo.
- Respeita o limite da API pública (pausas e novas tentativas automáticas).

### Como usar

- `products`: códigos com 8 (NCM), 6 (SH6), 4 (SH4) ou 2 (capítulo) dígitos; pontos são ignorados.
- `productSearch`: termos com acento, ex.: `"café"`, `"máquinas automáticas de venda"`.
- `flows`: `import`, `export` ou os dois. `periodFrom`/`periodTo` (`AAAA-MM`; vazio = últimos 12 meses).
- `breakdownBy`: `country`, `economicBlock`, `state`, `via`, `urf`. `monthly`: série mês a mês.
- `countries` (nome PT/EN ou código), `ufs`, `minFobUsd`, `maxRows`, `language` (`pt`/`en`).

Exemplos:

- Smartphones importados por país, 12 meses, com variação anual: `{"products":["85171300"],"flows":["import"],"breakdownBy":["country"]}`
- Café exportado por país e UF em 2026: `{"products":["0901"],"flows":["export"],"breakdownBy":["country","state"],"periodFrom":"2026-01","minFobUsd":1000000}`
- Máquinas de venda automática, mês a mês por país e porto: `{"productSearch":["máquinas automáticas de venda"],"breakdownBy":["country","urf"],"monthly":true}`
- Alerta mensal (agende diário): `{"products":["8471"],"flows":["import","export"],"onlyIfNewMonth":true,"stateKey":"informatica"}`

### Observações honestas

- O Comex Stat publica por mês, em geral na primeira semana do mês seguinte; o mês corrente não existe ainda.
- Dados são agregados: **não há nomes de empresas importadoras/exportadoras** (o MDIC não divulga por NCM).
- Quantidade estatística e preço por unidade só existem no nível NCM (8 dígitos).
- A "UF do produto" é a UF de origem na exportação e a UF de destino/domicílio do importador na importação (regra do MDIC).

### Privacidade (LGPD)

Estatística oficial agregada. Nenhum dado pessoal ou de empresa identificada é coletado.

### Fonte

Ministério do Desenvolvimento, Indústria, Comércio e Serviços (MDIC) / SECEX — Comex Stat,
API pública https://api-comexstat.mdic.gov.br (site: https://comexstat.mdic.gov.br). Sem chave, sem login.

***

#### English summary

**Brazil official import & export statistics (Comex Stat / MDIC).** Query by NCM/HS code (8, 6, 4 or 2 digits) or
keyword and get US$ FOB, CIF, freight, insurance, net kg, statistical quantity, average price per kg and per unit,
broken down by country, trade bloc, Brazilian state, transport mode and port of clearance (URF), with automatic
year-over-year comparison, monthly series, rolling 12-month periods across calendar years, and a monthly alert mode.
Aggregated official data — no personal data.

# Actor input Schema

## `products` (type: `array`):

Códigos de produto: 8 dígitos = NCM, 6 = SH6, 4 = SH4 (posição), 2 = capítulo. Pontos são ignorados ("8517.13.00" = "85171300"). Ex.: 85171300 (smartphones), 0901 (café), 8476 (máquinas de venda automática). Vazio e sem busca = pauta completa por capítulo.

## `productSearch` (type: `array`):

Opcional: termos para achar NCMs pelo nome, com acentos (ex.: "café", "máquinas automáticas de venda", "pneus"). As NCMs encontradas entram na consulta.

## `maxSearchNcms` (type: `integer`):

Limite de NCMs usadas de cada termo de busca (a busca oficial pode trazer códigos antigos ou parecidos).

## `flows` (type: `array`):

Importação, exportação ou ambos.

## `periodFrom` (type: `string`):

Mês inicial. Vazio = últimos 12 meses publicados. Períodos que cruzam o ano são suportados (a API oficial não aceita; o actor junta).

## `periodTo` (type: `string`):

Mês final. Vazio = último mês publicado pelo MDIC.

## `monthly` (type: `boolean`):

Uma linha por mês (série histórica). Desligado = total do período.

## `breakdownBy` (type: `array`):

Dimensões de cada linha: país, bloco econômico, UF do produto (origem na exportação / destino na importação), via de transporte e URF (porto/aeroporto/recinto de despacho).

## `countries` (type: `array`):

Filtra por país (nome em português ou inglês, ou código do Comex Stat). Ex.: \["China","Estados Unidos"], \["Germany"], \["160"].

## `ufs` (type: `array`):

Siglas de UF. Ex.: \["SP","SC","PR"].

## `compareWithPreviousYear` (type: `boolean`):

Acrescenta valores do ano anterior e variação % de US$ FOB, kg e preço médio US$/kg.

## `minFobUsd` (type: `integer`):

Descarta linhas pequenas (ex.: 10000 tira remessas irrelevantes).

## `maxRows` (type: `integer`):

Teto de linhas no dataset (mantém as de maior valor). Controla o custo.

## `language` (type: `string`):

Idioma dos nomes de produtos, países e blocos.

## `onlyIfNewMonth` (type: `boolean`):

Agende diário/semanal: o actor só entrega dados quando o MDIC publicar uma nova competência (mensal). Nas outras execuções não grava linhas (custo mínimo).

## `stateKey` (type: `string`):

Identifica o alerta (guarda o último mês entregue). Use um nome por consulta agendada.

## Actor input object example

```json
{
  "products": [
    "85171300"
  ],
  "maxSearchNcms": 15,
  "flows": [
    "import"
  ],
  "monthly": false,
  "breakdownBy": [
    "country"
  ],
  "compareWithPreviousYear": true,
  "minFobUsd": 0,
  "maxRows": 5000,
  "language": "pt",
  "onlyIfNewMonth": false,
  "stateKey": "padrao"
}
```

# Actor output Schema

## `results` (type: `string`):

Uma linha por produto × quebra × período.

## `resumo` (type: `string`):

Totais por fluxo, top produtos/países/UFs, variação anual, avisos e contadores.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "products": [
        "85171300"
    ],
    "flows": [
        "import"
    ],
    "breakdownBy": [
        "country"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kodama-data/comex-stat-brasil-importacao-exportacao").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "products": ["85171300"],
    "flows": ["import"],
    "breakdownBy": ["country"],
}

# Run the Actor and wait for it to finish
run = client.actor("kodama-data/comex-stat-brasil-importacao-exportacao").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "products": [
    "85171300"
  ],
  "flows": [
    "import"
  ],
  "breakdownBy": [
    "country"
  ]
}' |
apify call kodama-data/comex-stat-brasil-importacao-exportacao --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kodama-data/comex-stat-brasil-importacao-exportacao"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ici3drkhiNDlFRoKm/builds/KYn6YKFQfsbUgsmgS/openapi.json