# Buscar oportunidades no PNCP

`GET /v1/oportunidades` · requer o header `X-Api-Key`

Descoberta por palavras e filtros explícitos na janela PNCP publicada. O status deriva do código de situação da fonte e dos prazos de proposta avaliados no instante fixado em meta. Fornecedores aparecem somente quando um resultado coletado identifica uma PJ por CNPJ exato; a publicação do edital não identifica vencedor. Nenhum resultado quer dizer só que nada corresponde ao recorte publicado, não que a oportunidade não existe. O exemplo é uma resposta oficial observada em um recorte limitado (um dia, DF, uma modalidade).

## Requisição

```bash
curl -G https://api.fonteza.com.br/v1/oportunidades \
  -H "X-Api-Key: $FONTEZA_KEY" \
  --data-urlencode "q=mobiliário"
```

```python
import os
import requests

resposta = requests.get(
    "https://api.fonteza.com.br/v1/oportunidades",
    params={"q": "mobiliário"},
    headers={"X-Api-Key": os.environ["FONTEZA_KEY"]},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()
```

## Parâmetros

| Parâmetro | Tipo | Onde | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `q` | string | query | não | Palavras no objeto e nas descrições dos itens; não aplica CNAE. De 2 a 120 caracteres. |
| `uf` | string | query | não | UF explícita; deve pertencer ao manifesto da janela publicada. Formato: `^[A-Z]{2}$`. |
| `municipio_ibge` | string | query | não | Código IBGE de sete dígitos informado pelo PNCP. Formato: `^[0-9]{7}$`. |
| `modalidade` | integer | query | não | Código PNCP explícito; deve pertencer ao manifesto da janela publicada. Mínimo 1. |
| `status` | string | query | não | Valores: `futura`, `aberta`, `prazo_encerrado`, `prazo_indeterminado`, `revogada`, `anulada`, `suspensa`, `desconhecida`. |
| `prazo_de` | string (date) | query | não | Primeiro dia inclusivo do encerramento no calendário de Brasília. |
| `prazo_ate` | string (date) | query | não | Último dia inclusivo do encerramento no calendário de Brasília. |
| `limit` | integer | query | não | Entre 1 e 100. Padrão: `20`. |
| `cursor` | string | query | não | Cursor opaco vinculado à geração, aos filtros e a avaliado_em. |

## Resposta 200

Página vinculada à geração, aos filtros e ao instante de avaliação.

- `items` (array de objeto)
  - `numero_controle_pncp` (string)
  - `numero_compra` (string | null)
  - `ano_compra` (integer)
  - `objeto` (string)
  - `itens_resumo` (array de objeto)
    - `numero_item` (integer)
    - `descricao` (string)
    - `situacao_fonte` (string | null)
  - `itens_total` (integer)
  - `contratante` (objeto)
    - `cnpj` (string)
    - `nome` (string | null)
  - `localidade` (objeto)
    - `uf` (string)
    - `municipio_ibge` (string | null)
    - `municipio` (string | null)
  - `modalidade` (objeto)
    - `codigo` (integer)
    - `nome` (string | null)
  - `situacao_fonte` (objeto)
    - `codigo` (integer | null)
    - `nome` (string | null)
  - `status` (string): Valores: `futura`, `aberta`, `prazo_encerrado`, `prazo_indeterminado`, `revogada`, `anulada`, `suspensa`, `desconhecida`.
  - `data_abertura_proposta` (string | null (date-time))
  - `data_encerramento_proposta` (string | null (date-time))
  - `data_publicacao_pncp` (string (date-time))
  - `data_atualizacao` (string | null (date-time))
  - `valor_total_estimado` (string | null)
  - `url_fonte` (string (uri))
  - `fornecedores_identificados` (array de objeto)
    - `cnpj` (string)
    - `nome` (string | null)
    - `numero_item` (integer)
    - `situacao_resultado` (objeto)
      - `codigo` (integer | null)
      - `nome` (string | null)
    - `data_resultado` (string | null (date-time))
    - `data_cancelamento` (string | null (date-time))
    - `motivo_cancelamento` (string | null)
    - `url_fonte` (string (uri))
  - `fornecedores_total` (integer)
- `has_more` (boolean)
- `next_cursor` (string | null)
- `meta` (objeto)
  - `fonte` ("PNCP")
  - `conjunto` ("pncp-oportunidades")
  - `snapshot_id` (string)
  - `geracao` (integer)
  - `cobertura` ("janela_completa_recortada")
  - `criterio` ("data_publicacao_pncp")
  - `data_inicial` (string (date))
  - `data_final` (string (date))
  - `ufs` (array de string)
  - `modalidades` (array de integer)
  - `consultado_em` (string (date-time))
  - `avaliado_em` (string (date-time))
  - `evidencia` (string): Valores: `fixture_sintetica`, `live_nao_verificada`, `pncp_live_contrato_2026-09-25`.
  - `contrato_fonte` (string): Valores: `documentado_nao_verificado_live`, `openapi_oficial_capturado`.

Exemplo (Resposta oficial observada em 2026-09-25 para 2026-09-24, DF e modalidade 1 somente):

```json
{
  "items": [
    {
      "numero_controle_pncp": "00489828000902-1-000019/2026",
      "numero_compra": "SPU/DF 020",
      "ano_compra": 2026,
      "objeto": "Alienação, mediante venda, de imóvel(eis) sob gestão da Secretaria do Patrimônio da União",
      "itens_resumo": [
        {
          "numero_item": 1,
          "descricao": "Apartamento - AOS 4 BLOCO D, 4 - Apartamento 313 da AOS 04 Bloco D - AREA OCTOGONAL - CEP: 70660-044 - Brasília - DF",
          "situacao_fonte": "Em andamento"
        }
      ],
      "itens_total": 1,
      "contratante": {
        "cnpj": "00489828000902",
        "nome": "MINISTERIO DA GESTAO E DA INOVACAO EM SERVICOS PUBLICOS"
      },
      "localidade": {
        "uf": "DF",
        "municipio_ibge": "5300108",
        "municipio": "Brasília"
      },
      "modalidade": {
        "codigo": 1,
        "nome": "Leilão - Eletrônico"
      },
      "situacao_fonte": {
        "codigo": 1,
        "nome": "Divulgada no PNCP"
      },
      "status": "aberta",
      "data_abertura_proposta": "2026-09-24T20:00:00+02:00",
      "data_encerramento_proposta": "2026-11-05T13:59:00+01:00",
      "data_publicacao_pncp": "2026-09-24T16:50:31+02:00",
      "data_atualizacao": "2026-09-24T16:50:31+02:00",
      "valor_total_estimado": "633434.97",
      "url_fonte": "https://pncp.gov.br/api/consulta/v1/orgaos/00489828000902/compras/2026/19",
      "fornecedores_identificados": [],
      "fornecedores_total": 0
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "meta": {
    "fonte": "PNCP",
    "conjunto": "pncp-oportunidades",
    "snapshot_id": "pncpo-20260924-20260924-529544838db8de16",
    "geracao": 1,
    "cobertura": "janela_completa_recortada",
    "criterio": "data_publicacao_pncp",
    "data_inicial": "2026-09-24",
    "data_final": "2026-09-24",
    "ufs": [
      "DF"
    ],
    "modalidades": [
      1
    ],
    "consultado_em": "2026-09-25T11:53:26.251698Z",
    "avaliado_em": "2026-09-25T12:06:33.524502419Z",
    "evidencia": "pncp_live_contrato_2026-09-25",
    "contrato_fonte": "openapi_oficial_capturado"
  }
}
```

## Erros

| Status | Quando | Código |
| --- | --- | --- |
| 401 | Chave ausente, inválida ou revogada. |  |
| 409 | A geração do cursor deixou de ser a publicação atual. | `geracao_oportunidades_expirada` |
| 422 | Parâmetro ou cursor inválido, ou recorte fora da cobertura publicada. | `recorte_nao_coberto` |
| 429 | Cota diária da chave atingida (1.000 chamadas por padrão). Toda requisição autenticada conta, inclusive as que terminam em erro e as recusadas por cota. A contagem renova na virada do dia da base. A resposta não traz Retry-After. |  |
| 503 | Oportunidades sem janela completa publicada, autenticação indisponível, base indisponível, consulta interrompida pelo tempo limite ou consultas demais em andamento. | `oportunidades_indisponiveis` `base_indisponivel` `api_sobrecarregada` `consulta_demorada` |