PNCP — Monitor de Documentos Selecionados

Acompanhe um pequeno conjunto de documentos oficiais de um processo PNCP já conhecido. Receba diferenças de texto PDF com páginas, trechos de evidência e IDs estáveis de eventos, sem substituir seu fluxo de pesquisa de licitações.

O que faz

• Lista os anexos retornados pelo PNCP para um processo.
• Observa de 1 a 4 PDFs públicos selecionados, com texto extraível.
• Separa baseline inicial, mudanças de conteúdo/metadados, ausência de diferença e aquisição incompleta.
• Salva um checkpoint privado vinculado ao usuário de execução, Actor, processo e watch, no armazenamento dedicado escolhido por ID.
• Recupera o último resultado confirmado por inspect se a saída falhar depois do commit.

É obrigatório um único gravador, serializado pelo chamador, por armazenamento. Chamadas, agendas, execuções manuais e retries sobrepostos não são suportados. Verificações de revisão detectam conflitos observados; não são uma trava distribuída atômica.

Primeiro uso

1. Execute prepare apenas com operation e pncpId.
2. Escolha IDs de documentos da lista oficial retornada.
3. Crie um key-value store novo, vazio e dedicado; autorize somente esse store e informe seu ID real em stateStoreId.
4. Execute observe com watchKey, documentIds, expectedRevision: 0, retentionPolicy: "keep_last_2_commits" e writerPolicy: "externally_serialized".
5. Use a revisão confirmada nas observações seguintes. Em resultado incerto, consulte o run/inspect antes de iniciar outro.

Uma observação unchanged não grava checkpoint nem consome revisão. O baseline registra a primeira observação bem-sucedida, não comprova alterações anteriores.

Retenção e recuperação

O consentimento de retenção autoriza substituir os slots gerenciados desse novo store e compactar histórico antigo de documentos/eventos. Três pares fixos de snapshot/recibo mantêm os checkpoints atual e anterior confirmados, mais preparação. Cada snapshot contém documentos atuais e evidência da última transição, não um histórico ilimitado.

inspect não consulta o PNCP. Retorna hashes e recibo confirmado. recoverable_events é replay, não novas notificações: deduplique por event_id e receipt_id. Exporte o que precisa conservar além da janela de dois checkpoints. Não há e-mail, garantia de entrega por webhook ou confirmação automática de consumo.

Não há migração, reset ou exclusão automática de stores 5A antigos. Checkpoint atual ausente/corrompido suspende a operação, sem apresentá-lo como estado antigo ou baseline novo. Saídas de runs e histórico da plataforma têm retenção e custos próprios da Apify.

Escopo e limites

Somente PDFs de texto: até quatro selecionados, 8 MiB de downloads combinados e 500 páginas por PDF. Também há limites de lista e bytes de checkpoint/recibo. Aquisição incompleta preserva o estado confirmado anterior; não significa unchanged nem exclusão.

Sem OCR, busca nacional, decisão de aplicabilidade jurídica, interpretação integral de tabelas, correspondência automática entre revisões, garantia de todo o histórico do órgão ou aconselhamento licitatório. IDs diferentes exigem correspondência confirmada pelo usuário. Mudanças substantivas precisam de revisão humana.

Preço e cobrança

US$ 0,05 por observação observe completa, incluindo baseline, mudança, ausência de diferença e mudança de configuração; cobre até quatro PDFs selecionados. prepare, inspect e aquisições incompletas não geram esse evento. Não há taxa de início nem por linha do Dataset. O preço do evento inclui o uso da plataforma durante o run (PPE + usage separado desativado). Armazenamento e acesso após o run podem ter custos normais do seu plano Apify. Zero eventos em prepare/inspect não garante que toda retenção ou acesso posterior seja gratuito. Configure um limite suficiente para um evento.

A cobrança só é solicitada depois da verificação de estado e da gravação de OUTPUT e Dataset. BILLING, no armazenamento padrão do run, registra a confirmação separadamente. Não há cobrança intencional por aquisição incompleta ou falha de negócio. Porém, uma falha da plataforma depois de uma cobrança aceita, ou timeout da resposta de cobrança, pode deixar o run FAILED com cobrança efetuada. pending/unknown exigem conferência manual: não repetimos a cobrança incerta. Estado e faturamento não formam uma transação atômica. Repetir a observação como um novo run é outra observação faturável; consulte inspect para recuperar resultados sem esse evento.

API e saídas

Fixe número/tag de build e confirme o build ID retornado. Guarde o run ID; não repita o POST de início às cegas após timeout. Baixe OUTPUT JSON e Dataset completo em JSON/CSV. Leia status e commit_status de negócio, não apenas SUCCEEDED da plataforma.

Saída: selected-private-5b-1; estado: selected-state-5b-1; recibo: selected-commit-receipt-5b-1. Exemplos e limites operacionais seguem abaixo. Não é serviço oficial do PNCP nem endosso de órgão público.

---

English — PNCP Selected Documents Monitor

Monitor a small, selected set of official PNCP documents for a procurement you already know. Receive PDF text differences with page references, quoted evidence and stable event IDs—without rebuilding your tender-search workflow.

What it does

• Lists the attachments returned by PNCP for one procurement ID.
• Observes 1–4 selected public, text-based PDFs.
• Separates the initial baseline, content or metadata changes, unchanged observations and incomplete acquisition.
• Saves a private, runtime-user/Actor/procurement/watch-bound checkpoint in the dedicated store you explicitly select.
• Recovers the last committed result through inspect if output delivery fails after a state commit.

One externally serialized writer per store is required. Overlapping API calls, schedules, manual runs and retries are not supported. Revision checks detect observed conflicts; they are not an atomic distributed lock.

First use

1. Run prepare with only operation and pncpId.
2. Choose document IDs from the returned official list.
3. Create a new, empty, dedicated key-value store and authorize that store only. Pass its actual ID to stateStoreId.
4. Run observe with watchKey, documentIds, expectedRevision: 0, retentionPolicy: "keep_last_2_commits" and writerPolicy: "externally_serialized".
5. Use the confirmed revision for subsequent observations. If a run outcome is uncertain, inspect it before starting another.

Unchanged observations do not write a new checkpoint or consume a revision. A baseline records the first successful observation; it does not establish earlier changes.

Retention and recovery

Retention consent permits overwriting this new store’s managed slots and compacting older document/event history. Three fixed snapshot/receipt pairs retain the current and previous committed checkpoints plus staging. Each snapshot retains current documents and its latest transition evidence—not an unlimited history.

inspect makes no PNCP request. It returns current document hashes and a verified committed receipt. Its recoverable_events are a replay, not new notifications: deduplicate by event_id and receipt_id. Export results you need to retain beyond the two-checkpoint window. There is no email, webhook delivery guarantee or automatic acknowledgment.

The Actor does not automatically migrate, reset or delete legacy 5A stores. A missing or corrupt current checkpoint suspends the operation; it is not silently replaced with an older state or a new baseline. Separate run outputs and platform history have their own Apify retention and costs.

Scope and limits

Text PDFs only; up to four selected documents, 8 MiB combined downloads and 500 pages per PDF. Listing and checkpoint/receipt byte limits also apply. Incomplete acquisition preserves the prior committed state and does not mean “unchanged” or “deleted.”

No OCR, nationwide discovery, legal applicability decision, full table semantics, automatic revision correspondence, guaranteed full issuer history or procurement advice. Different document IDs require explicit user-confirmed correspondence. Every substantive difference still requires human review.

Price and billing

US$0.05 per fully completed observe, including initial baseline, changed, unchanged and configuration-changed observations; includes up to four selected PDFs. prepare, inspect and incomplete acquisition do not emit this billing event. No start fee or per-Dataset-row fee. The event price includes platform usage during the run (separate PPE + usage disabled). Post-run storage and access can incur standard charges under your Apify plan. Zero events for prepare/inspect does not guarantee free retention or later access. Set a sufficient run limit for one event.

The charge is requested only after verified state and saved OUTPUT and Dataset. The run-default BILLING record confirms billing separately. Incomplete acquisition and business failure are not intentionally charged. However, platform failure after an accepted charge, or a charging-response timeout, can leave a FAILED run that was charged. pending/unknown requires manual review: uncertain charges are not retried. State and billing are not an atomic transaction. Starting a new observation run is a separate billable observation; use inspect to recover stored results without this event.

API and outputs

Pin a build number/tag and verify the returned build ID. Persist the run ID; never blindly repeat a start request after a timeout. Retrieve the full OUTPUT JSON and Dataset JSON/CSV. Read business status and commit_status, not platform SUCCEEDED alone.

Output: selected-private-5b-1; state: selected-state-5b-1; receipt: selected-commit-receipt-5b-1. Exact examples and operational limits follow below. The implementation is not an official PNCP service or an endorsement by a public authority.

Exemplos / Examples

1. Prepare — funciona sem store ou token no INPUT / no store or token in INPUT

{"operation":"prepare","pncpId":"09509569000151-1-000010/2026"}

2. Observe — escolha seu próprio store / select your own store

Crie um armazenamento vazio dedicado em sua conta e selecione-o no campo stateStoreId; autorize apenas esse recurso. Os consentimentos de retenção e gravação serializada são explícitos, sem defaults silenciosos. Nunca use o ID de um store de demonstração ou de outro usuário.

Create an empty dedicated store in your account and select it in stateStoreId; grant access to that resource only. Retention and serialized-writer consent are explicit, with no silent defaults. Never use somebody else's or a demonstration store's ID.

Replace the placeholder with its actual 17-character ID. Choose document IDs returned by your current prepare. / Substitua o placeholder pelo ID real de 17 caracteres e escolha IDs do prepare atual.

{"operation":"observe","pncpId":"09509569000151-1-000010/2026","watchKey":"my-serial-watch","stateStoreId":"REPLACE_WITH_YOUR_STORE_ID","documentIds":[10,9],"expectedRevision":0,"retentionPolicy":"keep_last_2_commits","writerPolicy":"externally_serialized"}

For the next observation, use the last confirmed committed_revision. An unchanged run keeps that revision. / Na próxima observação, use a última committed_revision confirmada; unchanged mantém essa revisão.

3. Inspect — recuperar, não renotificar / recover, do not renotify

{"operation":"inspect","pncpId":"09509569000151-1-000010/2026","watchKey":"my-serial-watch","stateStoreId":"REPLACE_WITH_YOUR_STORE_ID"}

last_committed_receipt.status_at_commit describes the historical commit. recoverable_events may contain old baseline/change events while the current report has new_event_count: 0 and no alerts. / O recibo descreve o commit anterior; seus eventos recuperáveis não são eventos novos desta consulta.

Limites operacionais / Operational limits

• 1 procurement, 1–4 selected public text PDFs; total downloads 8 MiB; up to 500 pages per PDF, all with extractable text.
• Returned list: at most 1,000 records / 2 MiB. Checkpoint: 16,000,000 compressed bytes, 64,000,000 expanded bytes, 33 files. Receipt: 4,000,000 canonical JSON bytes. A large legitimate change can exceed these safety limits and suspend without advancing HEAD.
• Eight managed records per dedicated store; two committed snapshots plus staging. Each snapshot contains current documents and its last transition evidence, not all history. Apify run outputs/history have separate retention.
• Supported/default/minimum/maximum memory 512 MiB; recommended total run timeout 300 seconds, restart-on-error off and an explicit cost cap. HTTP socket timeout is 90 seconds, not an overall download deadline. No automatic acquisition retries or custom URLs.
• Missing/corrupt HEAD, receipt or archive: suspend; never silently reset or report the previous checkpoint as latest. First-publication failure after CONTROL may require explicit owner intervention or a newly authorized store. Never delete individual state records to force a baseline.
• Deleting a store removes originals, extracted text and receipts. Only the owner should explicitly perform such deletion. This Actor does not delete an existing legacy store or automatically migrate 5A.
• The wire-format identifiers retain their stable names: selected-private-5b-1, selected-state-5b-1, selected-commit-receipt-5b-1. They identify compatibility, not a promise of multiwriter support or unlimited history.

Verificação / Verification

The supported sequential workflow has been exercised through the authenticated API with two official PDFs: prepare, a successful fresh baseline, an unchanged independent run without checkpoint advancement, and inspect replay. Complete JSON/CSV and persisted hashes/receipt were compared. Offline synthetic tests additionally exercise repeated changes, bounded retention and output-failure recovery. These tests do not establish customer outcomes, general extraction accuracy or legal correctness.

O fluxo serializado foi verificado pela API autenticada com dois PDFs oficiais: prepare, baseline novo bem-sucedido, nova execução unchanged sem consumir revisão, e inspect. JSON/CSV e hashes/recibo persistidos foram comparados. Testes sintéticos locais cobrem mudanças repetidas, retenção e recuperação após falha de saída; não comprovam benefício comercial, precisão geral ou correção jurídica.

Paid-event acceptance / Aceitação da cobrança

Five private API runs on the same tested paid build covered prepare, insufficient-budget refusal before acquisition, fresh baseline, unchanged and inspect. Settled platform event counts were 0 / 0 / 1 / 1 / 0; both completed observations had a confirmed BILLING journal. Baseline and unchanged reports/complete JSON and CSV were saved, and unchanged/inspect preserved the same HEAD, archive and receipt. Initial terminal billing counters can lag (one observed 0 later settled to 1): compare refreshed run metadata with BILLING before deciding to retry. Owner-account tests establish event accounting, not payment by an external customer or willingness to pay. 91 offline tests plus 125 subtests covered persistence and billing boundaries; synthetic tests are distinct from official-PDF retrieval.

Cinco runs privados no mesmo build pago verificaram prepare, recusa por orçamento insuficiente antes da aquisição, baseline novo, unchanged e inspect. Contagens finais de eventos: 0 / 0 / 1 / 1 / 0, com BILLING confirmado nas duas observações completas. JSON/CSV e estado persistido foram comparados. Contadores logo após o término podem atrasar (0 passou para 1); confira metadados atualizados e BILLING antes de repetir. Testes do proprietário comprovam contabilização, não pagamento de cliente externo ou demanda comercial. 91 testes locais e 125 subtestes cobrem limites de persistência/cobrança; PDFs sintéticos não substituem a verificação com documentos oficiais.