Atas para Carona — PNCP (Atas de Registro de Preço vigentes)

Encontra Atas de Registro de Preço (ARP) vigentes no PNCP que outros órgãos podem usar por adesão ("carona", Lei 14.133, art. 86) e devolve um ranking com itens, preços homologados, fornecedores (CNPJ), dias de vigência restantes e um score_oportunidade.

Para quem: equipes comerciais B2G (quem tem ata vende a carona; quem não tem quer saber quais existem, de quem e até quando), consultorias de licitação e órgãos que procuram ata para aderir.

Como funciona

1. Lista as atas do PNCP (API pública de consulta, sem chave): as incluídas ou atualizadas nos últimos dias_atualizacao dias, ou, com cnpj_orgao, todas as atas vigentes hoje desse órgão. (O PNCP tem mais de 500 mil atas vigentes; não dá para varrer tudo a cada run.)
2. Descarta sem gastar requisição: atas canceladas, sem adesão permitida (possibilidadeAdesao = false), com menos de vigencia_minima_dias de vigência ou sem as palavras-chave no objeto.
3. Lê o detalhe da ata (UF, município e esfera do órgão gerenciador; a listagem não traz UF) e aplica uf, municipios_ibge e esferas.
4. Lê os itens da compra vinculada e o resultado (fornecedor vencedor e preço homologado) de até max_itens_por_ata itens.
5. Calcula o score, ordena e grava.

Saída (uma linha por ata)

Campo	Conteúdo
status	ok (ata com pelo menos um item com fornecedor homologado; cobrada), parcial (sem resultado homologado; não cobrada) ou erro (falha da fonte ou do input; não cobrada)
ata_id, numero_ata, ano_ata, compra_id	Identificação no PNCP
orgao_gerenciador	{cnpj, nome, uf, municipio, codigo_ibge, esfera}
unidade, modalidade, objeto	Unidade gerenciadora, modalidade da compra e objeto
vigencia_inicio, vigencia_fim, dias_vigencia_restantes	Vigência da ata
possibilidade_adesao	true, false ou null (não informado na fonte: confirme no edital/ata)
cancelado, data_cancelamento	Cancelamento
itens[]	{numero_item, descricao, unidade, quantidade, valor_unitario, valor_total, valor_estimado, fornecedor_tipo, fornecedor_cnpj, fornecedor_razao}; uma linha por fornecedor homologado. Sem resultado: valor estimado da compra e fornecedor null
itens_total_na_compra, valor_total	Total de itens da compra e soma dos itens lidos
score_oportunidade	0 a 100 = vigência restante (até 1 ano) × valor (escala log; R$ 100 milhões = 1) × aderência às palavras-chave (0,5 a 1)
atas_da_mesma_compra	Outras atas da mesma compra (ver abaixo)
mudanca	Só no modo diff: nova, cancelada ou vencendo
link_pncp, source_url, source_name, retrieved_at, warnings, error_message	Link da página da ata, URL da API, fonte, data da coleta (Brasília), avisos e erro

Entrada

Campo	Padrão	Descrição
modo	busca	busca (ranking) ou diff_semanal (só atas novas, canceladas ou com até 30 dias de vigência desde o run anterior com os mesmos filtros)
palavras_chave	—	Qualquer uma no objeto da ata, sem diferença de acento ou maiúscula
uf	["SP"]	UF do órgão gerenciador. Vazio = todas
municipios_ibge	—	Códigos IBGE de 7 dígitos
esferas	—	federal, estadual, municipal, distrital
vigencia_minima_dias	60	Dias mínimos até o fim da vigência
valor_minimo	—	Soma mínima dos itens lidos (R$)
cnpj_fornecedor	—	Só atas em que esse CNPJ venceu algum item lido (atas de um concorrente). CPF não é aceito
cnpj_orgao	—	Todas as atas vigentes hoje do órgão
dias_atualizacao	7	Janela de atas incluídas/atualizadas no PNCP (sem cnpj_orgao)
agrupar_por_compra	true	Uma compra com várias atas vira um item só
maxItems	10	Máximo de atas no resultado
max_itens_por_ata	5	Itens lidos por ata (cada item com resultado = 1 requisição)

Run sem input: atas de SP atualizadas nos últimos 7 dias, com 60+ dias de vigência, até 10 atas com até 5 itens cada (cerca de 2 minutos).

Cobrança (pay-per-event)

• rodada: US$ 0,01, cobrado uma única vez por run, no início da busca. Sem orçamento (ACTOR_MAX_TOTAL_CHARGE_USD) o run não busca e grava só um diagnóstico grátis. Atenção: a rodada é cobrada mesmo que a fonte (PNCP) esteja fora do ar nesse run.
• Prazo: o run para de coletar/entregar perto de ACTOR_TIMEOUT_AT (margem de 45 s) e, no diff_semanal, salva o estado a cada ata entregue, então um run interrompido não recobra atas já entregues.
• ata-enriquecida (evento por ata, nome mantido): US$ 0,03, cobrado por ata com status ok (com itens e fornecedor). Atas parcial e itens de erro não são cobrados.
• O teto de gasto do usuário é respeitado: ao atingi-lo, o Actor para de gravar.
• No diff_semanal, a última ata efetivamente cobrada também é salva quando a plataforma informa que o teto foi atingido. Uma tentativa rejeitada sem cobrança permanece pendente; o resumo conta somente atas entregues.

Limites conhecidos

• A API não liga cada item a uma ata. Os itens vêm da compra; quando a compra tem várias atas (uma por fornecedor, em geral), os itens e fornecedores são os da compra inteira, com aviso. Por isso, com agrupar_por_compra (padrão), a compra vira um item só, e as outras atas aparecem em atas_da_mesma_compra. Confira a ata no PNCP antes de oferecer ou pedir a carona.
• Só a primeira página de itens (até 50) é lida; com max_itens_por_ata menor, o aviso indica quantos itens a compra tem.
• possibilidade_adesao vem vazia em parte das atas; essas entram com aviso.
• A busca sem cnpj_orgao cobre só as atas incluídas ou atualizadas na janela de dias_atualizacao.

LGPD

• Fornecedor pessoa física: documento sai mascarado inteiro (***.***.***-**) e o nome é omitido, com aviso em warnings.
• MEI / empresário individual (razão social com nome de pessoa e/ou CPF): CPF removido e nome mascarado com as iniciais (ex.: 45.123.456 M*** A*** S***), com aviso.
• O campo usuario da fonte (quem publicou) não é copiado. Não há busca por pessoa (CPF é recusado no input).

---

Price Registration Minutes for "carona" — PNCP (English)

Finds active Price Registration Minutes (Atas de Registro de Preço) on Brazil's PNCP that other public bodies can join without a new tender ("carona", Law 14.133, art. 86) and returns a ranking with items, awarded prices, suppliers (CNPJ), days of validity left and an opportunity score.

How it works: lists minutes added or updated in the last dias_atualizacao days (or all active minutes of one agency with cnpj_orgao), drops cancelled ones, those closed to joining, those with less than vigencia_minima_dias left or without the keywords, reads each minute's detail (state, city, government level), then reads the linked purchase's items and awarded supplier for up to max_itens_por_ata items, scores and sorts.

Output: one row per minute: ata_id, managing agency (orgao_gerenciador: CNPJ, name, state, city, IBGE code, level), objeto, validity dates and dias_vigencia_restantes, possibilidade_adesao, cancelado, itens[] (description, unit, quantity, unit price, total, supplier type/CNPJ/name), valor_total, score_oportunidade (0–100 = remaining validity × value on a log scale × keyword match), atas_da_mesma_compra, mudanca (diff mode), link_pncp, source_url, retrieved_at, warnings, status.

Input: modo (busca = ranking, default; diff_semanal = only new, cancelled or ending-within-30-days minutes since the previous run with the same filters), palavras_chave, uf (default ["SP"]), municipios_ibge, esferas, vigencia_minima_dias (default 60), valor_minimo, cnpj_fornecedor (a competitor's minutes; CPF is not accepted), cnpj_orgao, dias_atualizacao (default 7), agrupar_por_compra (default true), maxItems (default 10), max_itens_por_ata (default 5). An empty input returns up to 10 São Paulo minutes updated in the last 7 days with 60+ days left (about 2 minutes).

Pricing: pay-per-event rodada (US$0.01, once per run) and ata-enriquecida (US$0.03), the latter charged only for ok rows (minutes with items and an awarded supplier). parcial and erro rows are free.

Known limits: the PNCP API does not link items to a specific minute; items come from the purchase, so when a purchase has several minutes the items/suppliers are those of the whole purchase (warned; grouped into one row by default). Only the first page of items (up to 50) is read. possibilidade_adesao is empty for part of the minutes (kept, with a warning).

Privacy (LGPD): individual suppliers have their CPF fully masked (***.***.***-**) and their name omitted; sole-proprietor (MEI) names are masked to initials and embedded CPFs removed; the source's usuario field is not copied; there is no search by person.