# Cobertura e procedência

Cada resposta diz qual publicação foi consultada e o que ela cobre. Assim você sabe se uma busca sem resultados quer dizer que algo não existe ou só que está fora do que foi publicado. Guarde `meta` junto com o dado.

## Campos de procedência

| Campo | Onde | Significado |
| --- | --- | --- |
| `fonte` | todas | Fonte oficial: `RFB/DadosAbertos`, `PNCP` ou `Portal da Transparência/Despesas Federais`. |
| `competencia` | empresas | Mês de referência da base da Receita (`AAAA-MM`). |
| `snapshot_id` | todas | Publicação consultada. Muda quando uma nova carga entra no ar. |
| `geracao` | oportunidades, despesas | Número da publicação atual; os cursores ficam presos a ela. |
| `cobertura`, `criterio`, `data_inicial`, `data_final` | oportunidades, despesas | A janela publicada: por qual data o recorte foi feito e quais dias inclui. |
| `ufs`, `modalidades` | oportunidades | UFs e modalidades na janela. Filtrar fora delas responde `422 recorte_nao_coberto`. |
| `datas_listadas`, `datas_coletadas` | despesas | Arquivos diários do Portal da Transparência que existiam e que foram coletados. |
| `evidencia`, `contrato_fonte` | oportunidades, despesas | Como o conjunto foi obtido e verificado. `fixture_sintetica` indica dados de teste. |

## Disponibilidade: /v1/meta

[`GET /v1/meta`](https://fonteza.com.br/docs/referencia/meta.md) é público e não consome cota. `data.fontes` tem uma entrada por conjunto: `rfb`, `pncp_oportunidades` e `transparencia_despesas`.

```bash
curl https://api.fonteza.com.br/v1/meta
```

| Campo | Valores |
| --- | --- |
| `estado` | `disponivel`; `desatualizado` (consultável, carga seguinte atrasada; motivo em `motivo_atraso`); `indisponivel`. |
| `cobertura` | `completa`, `parcial` ou `desconhecida`. |
| `disponivel` | `true` quando a publicação pode ser consultada. |
| `periodo`, `coletado_em`, `promovido_em` | Período coberto, data da coleta e data em que entrou no ar. |
| `registros` | Quantidade de registros publicados. |

`data.aviso` traz o aviso operacional vigente, como manutenção ou carga em andamento, e vem `null` quando não há nenhum.

Leia `/v1/meta` no início de cada rotina e guarde o `snapshot_id` de cada conjunto. Se não mudou, os resultados que você já tem continuam valendo.

## Quando a busca não encontra nada

- **Empresas.** `/v1/buscar` só devolve estabelecimentos ativos (situação `02`). Baixadas e inaptas aparecem em [`/v1/empresas/{cnpj}`](https://fonteza.com.br/docs/referencia/empresas-cnpj.md).
- **Oportunidades.** Só a janela, as UFs e as modalidades declaradas em `meta`. Nenhum resultado quer dizer só que nada foi encontrado nesse recorte.
- **Despesas federais.** Só os arquivos diários coletados. Nenhum resultado não quer dizer que a empresa nunca recebeu recursos federais.
- **Conjunto indisponível.** A rota responde `503` com código próprio, em vez de uma resposta sem resultados.

## Formatos da Receita Federal

Campos de empresa preservam a fonte: datas `AAAAMMDD`, capital social com vírgula decimal (`150000,00`), porte e situação cadastral em códigos da RFB. Os significados estão em [Obter o cadastro de uma empresa](https://fonteza.com.br/docs/referencia/empresas-cnpj.md).