# SICONFI API – Fiscal data

## About

The SICONFI API (`https://apidatalake.tesouro.gov.br/docs/siconfi/`) provides fiscal data for all Brazilian states, municipalities, and the Federal District. It includes budget execution reports (RREO), fiscal management reports (RGF), annual accounts declarations (DCA), and accounting balances matrices (MSC).

## Available functions

Portuguese | English | Description
--- | --- | ---
`get_entes()` | `get_entities()` | List of government entities
`get_anexos()` | `get_annexes()` | Report appendix reference table
`get_dca_ufs()` | `get_annual_accounts_ufs()` | Annual accounts (DCA)
`get_extrato()` | `get_delivery_status()` | Report delivery status
`get_rreo_ufs()` | `get_budget_report_ufs()` | Budget execution report (RREO)
`get_rgf_ufs()` | `get_fiscal_report_ufs()` | Fiscal management report (RGF)
`get_msc_patrimonial()` | `get_msc_equity()` | MSC equity accounts (classes 1-4)
`get_msc_orcamentaria()` | `get_msc_budget()` | MSC budgetary accounts (classes 5-6)
`get_msc_controle()` | `get_msc_control()` | MSC control accounts (classes 7-8)

## Parameter mapping

Portuguese (API) | English | Description
--- | --- | ---
`an_exercicio` | `fiscal_year` | Fiscal year
`id_ente` | `entity_id` | IBGE entity code
`no_anexo` | `appendix` | Report appendix name
`an_referencia` | `year` | Reference year
`me_referencia` | `month` | Reference month
`nr_periodo` | `period` | Period number
`co_tipo_demonstrativo` | `report_type` | Report type
`co_esfera` | `sphere` | Government sphere (M/E/U) — optional; omit if a filtered call returns empty
`co_poder` | `branch` | Government branch
`in_periodicidade` | `periodicity` | Periodicity (Q/S)
`co_tipo_matriz` | `matrix_type` | MSC matrix type (MSCC/MSCE)
`classe_conta` | `account_class` | Account class
`id_tv` | `value_type` | Value type

## Examples

### Entity lookup

    library(tesouror)
    library(dplyr)

    # All entities
    entes <- get_entes()

    # Filter states only
    estados <- entes |> filter(esfera == "E")

### RREO – Budget Execution

    # RREO Anexo 01 for Tocantins, 6th bimester of 2022
    rreo <- get_budget_report_ufs(
      fiscal_year = 2022, period = 6,
      report_type = "RREO",
      appendix = "RREO-Anexo 01",
      sphere = "E", entity_id = 17
    )

The `sphere` argument (`co_esfera`) is optional. Some entities only return data when the sphere filter is omitted — notably the Federal District constitutional fund, whose previdência appendix comes back empty if a sphere is supplied. If a sphere-filtered call returns nothing, drop `sphere`/`co_esfera` entirely:

    # Federal District constitutional fund (id_ente = 1), RREO-Anexo 04.2 —
    # only returns rows when co_esfera is NOT passed
    fcdf <- get_rreo_ufs(
      an_exercicio = 2023, nr_periodo = 6,
      co_tipo_demonstrativo = "RREO",
      no_anexo = "RREO-Anexo 04.2",
      id_ente = 1
    )

### RGF – Fiscal Management

    # RGF Anexo 01 for the executive branch of Tocantins
    rgf <- get_fiscal_report_ufs(
      fiscal_year = 2022, periodicity = "Q", period = 3,
      report_type = "RGF", appendix = "RGF-Anexo 01",
      sphere = "E", branch = "E", entity_id = 17
    )

### DCA – Annual Accounts

    dca <- get_annual_accounts_ufs(fiscal_year = 2022, entity_id = 17)

### MSC – Accounting Balances Matrix

    # Equity accounts (class 1) for December 2022
    msc <- get_msc_equity(
      entity_id = 17, year = 2022, month = 12,
      matrix_type = "MSCC", account_class = 1,
      value_type = "ending_balance"
    )