# Listar despesas federais de uma empresa

`GET /v1/empresas/{cnpj}/despesas-federais` · requer o header `X-Api-Key`

Documentos de empenho, liquidação e pagamento nos arquivos diários publicados do Portal da Transparência. O escopo raiz inclui estabelecimentos com a mesma raiz e o escopo estabelecimento exige CNPJ exato; cada aparição conserva o CNPJ e o papel do favorecido. Fases e medidas monetárias permanecem separadas. Nenhum resultado quer dizer só que nada apareceu na janela de arquivos declarada em meta, não que a empresa nunca recebeu recursos federais. Não há chave PNCP oficial verificada neste contrato batch e nenhum vínculo é inferido. Exemplos ilustrativos; não representam conciliação oficial nem cobertura histórica completa.

## Requisição

```bash
curl https://api.fonteza.com.br/v1/empresas/11222333000181/despesas-federais \
  -H "X-Api-Key: $FONTEZA_KEY"
```

```python
import os
import requests

resposta = requests.get(
    "https://api.fonteza.com.br/v1/empresas/11222333000181/despesas-federais",
    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 |
| --- | --- | --- | --- | --- |
| `cnpj` | string | caminho | sim | CNPJ normalizado do favorecido; 12 caracteres alfanuméricos e dois dígitos verificadores. Formato: `^[0-9A-Z]{12}[0-9]{2}$`. |
| `escopo` | string | query | não | Raiz consulta CNPJs com os mesmos oito primeiros caracteres; estabelecimento exige CNPJ exato. Valores: `raiz`, `estabelecimento`. Padrão: `"raiz"`. |
| `fase` | string | query | não | Fase documental oficial; fases não são somadas entre si. Valores: `empenho`, `liquidacao`, `pagamento`. |
| `data_de` | string (date) | query | não | Primeira data de emissão, inclusive; não amplia a janela de arquivos publicada. |
| `data_ate` | string (date) | query | não | Última data de emissão, inclusive; não amplia a janela de arquivos publicada. |
| `limit` | integer | query | não | Entre 1 e 100. Padrão: `20`. |
| `cursor` | string | query | não | Cursor opaco vinculado à geração, ao CNPJ, ao escopo e aos filtros. |

## Resposta 200

Página vinculada a uma única geração publicada e aos filtros da consulta.

- `items` (array de objeto)
  - `fase` (string): Valores: `empenho`, `liquidacao`, `pagamento`.
  - `codigo_documento` (string): Código SIAFI completo de 23 caracteres (UG, gestão e número do documento).
  - `id_empenho` (string | null)
  - `exercicio` (integer)
  - `data_emissao` (string (date))
  - `tipo_documento` (objeto)
    - `codigo` (string | null)
    - `nome` (string | null)
  - `favorecido` (objeto)
    - `cnpj` (string)
    - `nome` (string | null)
    - `papel` (string): Valores: `direto`, `final`.
  - `orgao` (objeto)
    - `codigo` (string | null)
    - `nome` (string | null)
  - `unidade_gestora` (objeto)
    - `codigo` (string | null)
    - `nome` (string | null)
    - `codigo_gestao` (string | null)
    - `gestao` (string | null)
  - `processo` (string | null)
  - `observacao` (string | null)
  - `valores` (objeto): Medidas distintas preservadas por fase; não devem ser somadas entre si.
    - `documento_brl` (string | null)
    - `empenhos_impactados_brl` (string | null)
    - `favorecido_final_brl` (string | null)
  - `url_fonte` (string (uri))
  - `vinculo_pncp` (objeto): O contrato batch verificado não contém chave PNCP; nenhuma ligação é inferida.
    - `situacao` ("sem_chave_oficial")
    - `numero_controle_pncp` (null)
  - `arquivo_data` (string (date))
- `has_more` (boolean)
- `next_cursor` (string | null)
- `meta` (objeto)
  - `fonte` ("Portal da Transparência/Despesas Federais")
  - `conjunto` ("transparencia-despesas")
  - `snapshot_id` (string)
  - `geracao` (integer)
  - `cobertura` ("janela_arquivos_completa")
  - `criterio` ("data_arquivo")
  - `data_inicial` (string (date))
  - `data_final` (string (date))
  - `datas_listadas` (array de string (date))
  - `datas_coletadas` (array de string (date))
  - `manifesto_sha256` (string)
  - `coletado_em` (string (date-time))
  - `evidencia` (string): Valores: `fixture_sintetica`, `arquivo_oficial_nao_conciliado`.
  - `contrato_fonte` ("dicionario_lote_documentado")
  - `vinculos_pncp` (objeto)
    - `com_chave_oficial` (0)
    - `sem_chave_oficial` (integer)

Exemplo (Pagamento sem vínculo PNCP inferido):

```json
{
  "items": [
    {
      "fase": "pagamento",
      "codigo_documento": "150002000012026OB000123",
      "id_empenho": null,
      "exercicio": 2026,
      "data_emissao": "2026-09-22",
      "tipo_documento": {
        "codigo": "OB",
        "nome": "Ordem Bancária"
      },
      "favorecido": {
        "cnpj": "11222333000181",
        "nome": "FORNECEDOR EXEMPLO LTDA",
        "papel": "direto"
      },
      "orgao": {
        "codigo": "26000",
        "nome": "Ministério da Educação"
      },
      "unidade_gestora": {
        "codigo": "150002",
        "nome": "UNIDADE GESTORA EXEMPLO/MEC",
        "codigo_gestao": "00001",
        "gestao": "TESOURO NACIONAL"
      },
      "processo": "23000.012345/2026-11",
      "observacao": "Pagamento referente à nota fiscal 1234, serviços de transporte de agosto/2026",
      "valores": {
        "documento_brl": "120.00",
        "empenhos_impactados_brl": "120.00",
        "favorecido_final_brl": null
      },
      "url_fonte": "https://portaldatransparencia.gov.br/despesas/pagamento/150002000012026OB000123",
      "vinculo_pncp": {
        "situacao": "sem_chave_oficial",
        "numero_controle_pncp": null
      },
      "arquivo_data": "2026-09-22"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "meta": {
    "fonte": "Portal da Transparência/Despesas Federais",
    "conjunto": "transparencia-despesas",
    "snapshot_id": "desp-20260922-20260922-8d41f07a2c96b3e5",
    "geracao": 1,
    "cobertura": "janela_arquivos_completa",
    "criterio": "data_arquivo",
    "data_inicial": "2026-09-22",
    "data_final": "2026-09-22",
    "datas_listadas": [
      "2026-09-22"
    ],
    "datas_coletadas": [
      "2026-09-22"
    ],
    "manifesto_sha256": "8d41f07a2c96b3e5d2a0c7f91e4b6a38f5c09d27b1e83a4c6f72d05e9ab14c63",
    "coletado_em": "2026-09-23T12:00:00Z",
    "evidencia": "arquivo_oficial_nao_conciliado",
    "contrato_fonte": "dicionario_lote_documentado",
    "vinculos_pncp": {
      "com_chave_oficial": 0,
      "sem_chave_oficial": 1
    }
  }
}
```

## 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_despesas_expirada` |
| 422 | CNPJ, filtro ou cursor inválido. |  |
| 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 | Despesas sem janela completa publicada, contrato inconsistente, base indisponível, consulta interrompida pelo tempo limite ou consultas demais em andamento. | `despesas_indisponiveis` `base_indisponivel` `api_sobrecarregada` `consulta_demorada` |