# LicitacoesBR — Radar de Licitações PNCP (`joaosbp/licitacoes-pncp-br`) Actor

Radar de contratações públicas do Brasil via API oficial de dados abertos do PNCP (Lei 14.133/2021). 3 modos: novos editais, prazos encerrando e vencedores com CNPJ/valores. Filtros por UF, modalidade, valor e palavras-chave. Dedup para monitoramento diário. Output flat pronto para Sheets/CRM.

- **URL**: https://apify.com/joaosbp/licitacoes-pncp-br.md
- **Developed by:** [João Victor](https://apify.com/joaosbp) (community)
- **Categories:** Business, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## LicitacoesBR — Radar de Licitações PNCP 🇧🇷

Monitor de contratações públicas do Brasil direto da **API oficial de dados abertos do PNCP** (Portal Nacional de Contratações Públicas — Lei 14.133/2021). Sem scraping, sem login, sem risco de ToS.

**Três modos em um Actor:**

| Modo | O que faz | Endpoint oficial |
|---|---|---|
| `oportunidades` | Editais publicados num período (novos negócios) | `/v1/contratacoes/publicacao` |
| `encerrando` | Editais com propostas abertas fechando até uma data (radar de prazos) | `/v1/contratacoes/proposta` |
| `vencedores` | Contratos publicados com **CNPJ/nome do fornecedor e valores** (inteligência competitiva) | `/v1/contratos` |

### Por que este Actor?

Os scrapers de licitação do Apify Store fazem busca genérica. Este é diferente:

- **Modo vencedores**: descubra *quem está ganhando* contratos do governo no seu segmento, por quanto e de quais órgãos. Responde "meu concorrente ganhou o quê?".
- **Robustez embutida**: a API do PNCP é instável (HTTP 500 e latências de 30-60s são comuns). O Actor faz retry com backoff exponencial (até 5 tentativas), degrada para resultados parciais em vez de falhar, e reporta tudo no `OUTPUT`.
- **Dedup para monitoramento**: ligue `apenasNovos` e agende runs diários — só itens inéditos chegam ao seu pipeline (memória no Key-Value Store).
- **Filtros de verdade**: palavras-chave com/sem acento, exclusão de ruído, faixa de valor, UF, CNPJ do órgão.
- **Flat output**: uma linha por registro, CSV pronto para Sheets/CRM. `fornecedorCnpj` encadeia direto com enriquecimento de CNPJ e screening de sanções.

### Input

| Campo | Tipo | Default | Descrição |
|---|---|---|---|
| `modo` | select | `oportunidades` | Ver tabela acima |
| `dataInicial` / `dataFinal` | string | ontem (ou hoje→+7d no modo `encerrando`) | `YYYY-MM-DD`; vazio = default rápido. Períodos longos são quebrados em blocos mensais automaticamente |
| `modalidades` | array | `[6, 8]` | Códigos Lei 14.133: 6=Pregão Eletrônico, 8=Dispensa, 4=Concorrência Eletrônica, 9=Inexigibilidade… |
| `ufs` | array | todas | Filtra por estado (na API quando possível) |
| `palavrasChave` | array | — | OU lógico no objeto, ignora acentos |
| `palavrasChaveExcluir` | array | — | Remove ruído |
| `valorMin` / `valorMax` | number | — | Faixa de valor estimado (editais) ou global (contratos) |
| `cnpjOrgao` | string | — | Monitora um único órgão comprador |
| `apenasNovos` | boolean | `false` | Dedup contra runs anteriores |
| `maxResultados` | integer | `100` | Trava de dataset |
| `maxPaginas` | integer | `2` | Trava por consulta (a API é lenta: ~30-60s/página) |

### Output (dataset)

Uma linha por edital/contrato: `fonte`, `numeroControlePNCP`, `objeto`, `orgaoCnpj`, `orgaoNome`, `uf`, `municipio`, `codigoIbge`, `modalidadeNome`, `valor`, `dataPublicacaoPncp`, `dataAberturaProposta`, `dataEncerramentoProposta`, `dataAssinatura`, `vigenciaInicio/Fim`, `situacao`, `fornecedorCnpj`, `fornecedorNome`, `linkEdital` (link direto para o edital no portal PNCP), `keywordsMatched`.

Resumo do run (contagens, filtros, retries, consultas falhas) no Key-Value Store → `OUTPUT`.

### Exemplos

**Radar semanal de pregões de TI em SP/RJ:**

```json
{
  "modo": "encerrando",
  "modalidades": [6],
  "ufs": ["SP", "RJ"],
  "palavrasChave": ["informática", "notebook", "computador"],
  "palavrasChaveExcluir": ["locação"],
  "apenasNovos": true
}
```

**Quem ganhou contratos de medicamentos este mês:**

```json
{
  "modo": "vencedores",
  "dataInicial": "2026-07-01",
  "dataFinal": "2026-07-31",
  "palavrasChave": ["medicamento"]
}
```

**Monitorar um órgão específico:**

```json
{
  "modo": "oportunidades",
  "cnpjOrgao": "00.394.460/0058-45",
  "apenasNovos": true
}
```

### Pipeline sugerido

1. `licitacoes-pncp-br` (modo vencedores) → lista de `fornecedorCnpj`
2. Enriquecimento de CNPJ → razão social, sócios, contatos
3. Screening de sanções (CEIS/CNEP) → risco do concorrente/parceiro

### Fonte de dados & limites

- API pública oficial: `https://pncp.gov.br/api/consulta` (Serpro). Sem autenticação para consulta.
- A API é **instável e lenta** — o Actor mitiga com retry/backoff e resultados parciais, mas runs muito amplos (Brasil inteiro, meses, todas as modalidades) podem levar muitos minutos. Prefira escopo estreito + schedule frequente.
- Cobertura do PNCP cresce continuamente (obrigatoriedade por esfera desde 2023-2024); órgãos que ainda não publicam no portal não aparecem.

### Desenvolvimento local

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest -q          # testes unitários (sem rede)
python -m src.main           # run local (lê storage/key_value_stores/default/INPUT.json)
```

***

### 🇧🇷 Suite de Dados Públicos BR / BR Public Data Suite

Este Actor faz parte de uma suite brasileira de dados públicos e jurídicos. Combine-os em pipelines:

- **LicitacoesBR** — radar de licitações PNCP (editais e vencedores): https://apify.com/joaosbp/licitacoes-pncp-br
- **CNPJ Lookup BR** — consulta CNPJ em lote com dados da Receita Federal: https://apify.com/joaosbp/cnpj-enrichment-lookup-br
- **CnpjDeltaBR** — monitor de mudanças cadastrais de CNPJs: https://apify.com/joaosbp/cnpj-delta-monitor-br
- **ComplianceBR** — screening de sanções CEIS/CNEP/CEPIM: https://apify.com/joaosbp/cnpj-sanctions-screening-br
- **Contact Scraper BR** — emails, WhatsApp + enriquecimento CNPJ: https://apify.com/joaosbp/website-contact-finder-br
- **PrazoBR** — extrator de prazos e obrigações jurídicas: https://apify.com/joaosbp/legal-deadlines-extractor-br
- **AutosTimeline BR** — cronologia de autos e pendências: https://apify.com/joaosbp/case-timeline-builder-br
- **PublicaBR** — monitor de publicações processuais (DataJud/CNJ): https://apify.com/joaosbp/publicacoes-processuais-br
- **EditalBR** — extrator de editais de concurso em PDF: https://apify.com/joaosbp/edital-extractor-br
- **Pricing Monitor BR** — monitor de páginas de preço SaaS: https://apify.com/joaosbp/competitor-pricing-page-monitor

**Pipeline sugerido:** LicitacoesBR encontra editais → CNPJ Lookup enriquece o vencedor → ComplianceBR verifica sanções → CnpjDeltaBR monitora mudanças cadastrais.

# Actor input Schema

## `modo` (type: `string`):

oportunidades: editais publicados no período. encerrando: editais recebendo propostas com encerramento até dataFinal (radar de prazos). vencedores: contratos publicados no período, com CNPJ/nome do fornecedor e valores (inteligência competitiva).

## `dataInicial` (type: `string`):

Início do período de publicação. Vazio = padrão rápido (ontem, para oportunidades/vencedores; hoje, para encerrando).

## `dataFinal` (type: `string`):

Fim do período. No modo encerrando, é o limite do prazo de propostas (padrão: hoje + 7 dias). Períodos longos são quebrados automaticamente em blocos mensais.

## `modalidades` (type: `array`):

6 = Pregão Eletrônico, 8 = Dispensa de Licitação, 4 = Concorrência Eletrônica, 9 = Inexigibilidade etc. (códigos da Lei 14.133). Padrão: Pregão Eletrônico + Dispensa.

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

Filtra por estado da unidade compradora. Vazio = Brasil inteiro. No modo oportunidades o filtro é feito na API (mais rápido).

## `palavrasChave` (type: `array`):

Só entram registros cujo objeto contenha pelo menos uma destas palavras (ignora acentos e maiúsculas). Ex.: informática, medicamento, obra.

## `palavrasChaveExcluir` (type: `array`):

Registros cujo objeto contenha qualquer uma destas palavras são descartados (útil para limpar ruído, ex.: excluir 'locação' quando você vende compra).

## `valorMin` (type: `number`):

Valor estimado (editais) ou valor global (contratos) mínimo. Vazio = sem limite.

## `valorMax` (type: `number`):

Valor estimado/global máximo. Vazio = sem limite.

## `cnpjOrgao` (type: `string`):

Restringe a busca a um único órgão (14 dígitos, com ou sem pontuação). Útil para monitorar um cliente ou prefeitura específica.

## `apenasNovos` (type: `boolean`):

Ligado: retorna só itens nunca vistos em runs anteriores deste Actor (memória no Key-Value Store). Ideal para monitoramento agendado diário — sem duplicados no seu pipeline.

## `maxResultados` (type: `integer`):

Limite de registros no dataset (padrão 100).

## `maxPaginas` (type: `integer`):

Trava de segurança por combinação modalidade/UF/mês (padrão 2 = até 100 itens por consulta). Aumente para varreduras profundas — a API do PNCP é lenta (30-60s/página).

## Actor input object example

```json
{
  "modo": "oportunidades",
  "modalidades": [
    "6"
  ],
  "apenasNovos": false,
  "maxResultados": 100,
  "maxPaginas": 2
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

One record per item: objeto, órgão (CNPJ/nome/UF/município), modalidade, valor, datas, situação, fornecedor (modo vencedores) e link direto para o edital no PNCP.

## `resultsCsv` (type: `string`):

Spreadsheet-ready export — importe direto no Google Sheets/Excel para triagem comercial.

## `summary` (type: `string`):

Modo, período, filtros aplicados, contagens (buscados/filtrados/duplicados/publicados), páginas, retries e consultas que falharam.

# 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 = {
    "modo": "oportunidades",
    "modalidades": [
        "6"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("joaosbp/licitacoes-pncp-br").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 = {
    "modo": "oportunidades",
    "modalidades": ["6"],
}

# Run the Actor and wait for it to finish
run = client.actor("joaosbp/licitacoes-pncp-br").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "modo": "oportunidades",
  "modalidades": [
    "6"
  ]
}' |
apify call joaosbp/licitacoes-pncp-br --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=joaosbp/licitacoes-pncp-br",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/0cQLIf0CvCCEuFMq9/builds/wzMAfQM5d1G1OmZKy/openapi.json