Portaldecompraspublicas APIportaldecompraspublicas.com.br ↗
Access Brazilian public procurement data via 5 endpoints. Search tenders by state, status, modality, date range, and retrieve full process details and timelines.
What is the Portaldecompraspublicas API?
This API exposes 5 endpoints covering public procurement processes listed on Portal de Compras Públicas, a Brazilian government tender platform. The search_processes endpoint returns paginated tender summaries filterable by state (UF), status, keyword, date range, and government entity. Companion endpoints deliver full process details, chronological event timelines, and the complete set of valid filter codes needed to query the system.
curl -X GET 'https://api.parse.bot/scraper/94fb6edf-2207-48b6-9256-33b865eb528c/search_processes?uf=100143&page=1&objeto=computadores&status=1&municipio=0&julgamento=1&modalidade=1&realizacao=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace portaldecompraspublicas-com-br-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Portal de Compras Públicas SDK — search procurement processes, drill into details and timelines."""
from parse_apis.portal_de_compras_públicas_api import PortalCompras, ProcessStatus, RealizationType, ProcessNotFound
client = PortalCompras()
# Search for electronic procurement processes currently receiving proposals
for process in client.processes.search(query="computadores", status=ProcessStatus.RECEBENDO_PROPOSTAS, limit=5):
print(process.resumo, process.razao_social, process.status.descricao)
# Drill into one process for full details
process = client.processes.search(query="equipamento", realizacao=RealizationType.ELETRONICO, limit=1).first()
if process:
detail = process.details()
print(detail.numero_processo, detail.tipo_licitacao, detail.tipo_julgamento, detail.legislacao_aplicavel)
# Walk the process timeline — document uploads, status changes
for event in process.timeline(limit=3):
print(event.data_hora_frase, event.apelido, event.frase[:80])
# Fetch available filter options for building search queries
filters = client.filters.get()
print(filters.modalidades[0].codigo, filters.modalidades[0].descricao)
# Typed error handling: catch a not-found when the slug is stale
try:
stale = client.processes.search(query="licitação", limit=1).first()
if stale:
_ = stale.details()
except ProcessNotFound as exc:
print(f"Process gone: {exc}")
print("exercised: processes.search / process.details / process.timeline / filters.get")
Search for procurement processes with various filters. Returns paginated results sorted by most recent publication date. Each result includes process identification, buyer info, status, modality, and a URL slug for fetching full details. Pagination via integer page counter; the response includes total pages and current page position.
| Param | Type | Description |
|---|---|---|
| uf | string | State (UF) code from get_search_parameters ufs array (e.g. '100143' for RS, '100135' for SP). |
| page | integer | Page number for pagination (1-based). |
| orgao | string | Government entity name to filter by. |
| objeto | string | Keyword/object search term to match against process summaries (e.g. 'computadores', 'equipamento'). |
| status | string | Status code: '1' for Recebendo Propostas, '2' for Em Andamento, '3' for Finalizado, '4' for Iminência de deserto, '25' for Em Republicação. |
| processo | string | Process number to search for. |
| tipoData | string | Date type filter: '1' for Publication date, '2' for Opening date. Must be provided when using dataInicial/dataFinal. |
| dataFinal | string | End date in YYYY-MM-DD format for date range filter. |
| municipio | string | Municipality code. Defaults to '0' (all municipalities). |
| julgamento | string | Judgment type code from get_search_parameters julgamentos array. |
| modalidade | string | Modality code from get_search_parameters modalidades array (e.g. '1' for Pregão, '3' for Dispensa). |
| realizacao | string | Realization type code: '1' for Eletrônico, '2' for Presencial, '3' for Simples informação. |
| dataInicial | string | Start date in YYYY-MM-DD format for date range filter. |
{
"type": "object",
"fields": {
"total": "integer total number of matching records",
"result": "array of procurement process summaries",
"nextPage": "integer or null next page number",
"pageCount": "integer total number of pages",
"currentPage": "integer current page number"
}
}About the Portaldecompraspublicas API
What the API Covers
Portal de Compras Públicas aggregates public procurement notices from Brazilian government entities at the municipal and state level. The API provides structured access to this data across five endpoints. search_processes is the primary search surface, accepting filters for uf (state code), orgao (entity name), objeto (keyword), status, processo (process number), and a date range via tipoData, dataFinal. Results include codigoLicitacao, identificacao, numero, resumo, razaoSocial, status, tipoLicitacao, and urlReferencia fields per record, plus quantidadePaginas and quantidadeRegistros for pagination.
Process Detail and Timeline
get_process_detail accepts a slug taken from the urlReferencia field in search results and returns the complete record: resumo, tipoLicitacao, numeroProcesso, statusProcesso (with codigo and descricao), codigoLicitacao, and razaoSocialComprador. get_process_timeline takes the codigoLicitacao integer and returns frasesChat, an ordered array of event objects each containing apelido, dataHoraFrase, and frase. Newly published processes may return an empty frasesChat array with codigoUltimaFrase set to 0.
Filter Codes and Benefit Card Search
Before querying search_processes, call get_search_parameters to retrieve the valid code lists: ufs, status, julgamentos, modalidades, and realizacoes. Each entry carries a codigo and descricao. A separate endpoint, search_benefit_card_processes, runs a preset set of benefit-related keyword queries (vale refeição, vale alimentação, vale transporte, cartão benefício) and returns deduplicated results with a total_found count — useful for vendors specifically tracking benefit card tenders without constructing individual searches.
The Portaldecompraspublicas API is a managed, monitored endpoint for portaldecompraspublicas.com.br — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when portaldecompraspublicas.com.br changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official portaldecompraspublicas.com.br API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor new procurement notices in a specific Brazilian state by polling
search_processeswith the relevantufcode and astatusof 'Recebendo Propostas'. - Build a tender alert service that surfaces benefit card contracts using
search_benefit_card_processesand notifies sales teams of matching opportunities. - Aggregate buyer entity activity by filtering
search_processesbyorgaoand collectingrazaoSocialandtipoLicitacaoacross results. - Audit process history by pulling the full event log from
get_process_timelinefor a givencodigoLicitacaoand tracking document uploads and status changes. - Populate a procurement dashboard with live tender counts and pagination metadata (
quantidadePaginas,quantidadeRegistros) fromsearch_processes. - Validate and translate UF and status codes for a localized UI by querying
get_search_parametersonce and caching theufsandstatusarrays. - Track a specific tender end-to-end by resolving its
urlReferenciathroughget_process_detailand then fetching itsfrasesChattimeline.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Portal de Compras Públicas offer an official developer API?+
What does `get_search_parameters` return and why should I call it first?+
get_search_parameters returns five arrays: ufs (state codes), status, julgamentos (judgment types), modalidades (procurement modalities), and realizacoes (realization types). Each entry has a codigo and descricao. The search_processes endpoint requires numeric codes — not plain text — for fields like uf and status, so calling get_search_parameters first ensures you pass valid values.Are process documents or official notice attachments accessible through the API?+
How does pagination work in `search_processes`?+
quantidadePaginas (total pages) and quantidadeRegistros (total matching records). Pass the page parameter as a string to step through pages. There is no cursor mechanism — page-number pagination only.Does `get_process_timeline` always return events for a process?+
frasesChat array. In that case codigoUltimaFrase is 0. Events are system-generated and appear as the process progresses through document uploads, republications, and status changes, so timeline data grows over a process's lifecycle.