Listar despesas federais de uma empresa

GET/v1/empresas/{cnpj}/despesas-federaisX-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.

Parâmetros

cnpjstring · caminhoobrigatório
CNPJ normalizado do favorecido; 12 caracteres alfanuméricos e dois dígitos verificadores.
Formato: ^[0-9A-Z]{12}[0-9]{2}$.
escopostring · query
Raiz consulta CNPJs com os mesmos oito primeiros caracteres; estabelecimento exige CNPJ exato.
Valores: raiz, estabelecimento. Padrão: "raiz".
fasestring · query
Fase documental oficial; fases não são somadas entre si.
Valores: empenho, liquidacao, pagamento.
data_destring (date) · query
Primeira data de emissão, inclusive; não amplia a janela de arquivos publicada.
data_atestring (date) · query
Última data de emissão, inclusive; não amplia a janela de arquivos publicada.
limitinteger · query
Entre 1 e 100. Padrão: 20.
cursorstring · query
Cursor opaco vinculado à geração, ao CNPJ, ao escopo e aos filtros.

Resposta

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

itemsarray de objeto
- fasestring
  Valores: empenho, liquidacao, pagamento.
- codigo_documentostring
  Código SIAFI completo de 23 caracteres (UG, gestão e número do documento).
- id_empenhostring | null
- exerciciointeger
- data_emissaostring (date)
- tipo_documentoobjeto
  - codigostring | null
  - nomestring | null
- favorecidoobjeto
  - cnpjstring
  - nomestring | null
  - papelstring
    Valores: direto, final.
- orgaoobjeto
  - codigostring | null
  - nomestring | null
- unidade_gestoraobjeto
  - codigostring | null
  - nomestring | null
  - codigo_gestaostring | null
  - gestaostring | null
- processostring | null
- observacaostring | null
- valoresobjeto
  Medidas distintas preservadas por fase; não devem ser somadas entre si.
  - documento_brlstring | null
  - empenhos_impactados_brlstring | null
  - favorecido_final_brlstring | null
- url_fontestring (uri)
- vinculo_pncpobjeto
  O contrato batch verificado não contém chave PNCP; nenhuma ligação é inferida.
  - situacao"sem_chave_oficial"
  - numero_controle_pncpnull
- arquivo_datastring (date)
has_moreboolean
next_cursorstring | null
metaobjeto
- fonte"Portal da Transparência/Despesas Federais"
- conjunto"transparencia-despesas"
- snapshot_idstring
- geracaointeger
- cobertura"janela_arquivos_completa"
- criterio"data_arquivo"
- data_inicialstring (date)
- data_finalstring (date)
- datas_listadasarray de string (date)
- datas_coletadasarray de string (date)
- manifesto_sha256string
- coletado_emstring (date-time)
- evidenciastring
  Valores: fixture_sintetica, arquivo_oficial_nao_conciliado.
- contrato_fonte"dicionario_lote_documentado"
- vinculos_pncpobjeto
  - com_chave_oficial0
  - sem_chave_oficialinteger

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`

Formatos de erro em Erros; o que conta na cota em Autenticação e cota.

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

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()

const url = new URL("https://api.fonteza.com.br/v1/empresas/11222333000181/despesas-federais");
const resposta = await fetch(url, {
  headers: { "X-Api-Key": process.env.FONTEZA_KEY },
});
if (!resposta.ok) throw new Error(`${resposta.status}: ${await resposta.text()}`);
const dados = await resposta.json();

Resposta 200

{
  "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
    }
  }
}