---
title: "Transferências Constitucionais API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Transferências Constitucionais API}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

## About

The Transferências Constitucionais API provides data on constitutional 
transfers from the Federal Government to states and municipalities. These 
transfers include FPE (Fundo de Participação dos Estados), FPM (Fundo de 
Participação dos Municípios), FUNDEB, and other mandatory transfers.

Base URL: `https://apiapex.tesouro.gov.br/aria/v1/transferencias_constitucionais/custom`

## Available functions

All functions use the `get_tc_` prefix. All filter parameters use
**numeric codes**, not names or abbreviations. Use the lookup functions
(`get_tc_transferencias`, `get_tc_estados`, `get_tc_municipios`) to
obtain the codes. Multiple values are separated by colons (`:`) —
e.g., `p_estado = "1:2"` for Acre and Alagoas.

| Portuguese | English | Description |
|:---|:---|:---|
| `get_tc_transferencias()` | `get_tc_transfer_types()` | List transfer types and codes |
| `get_tc_estados()` | `get_tc_states()` | List states and codes |
| `get_tc_municipios()` | `get_tc_municipalities()` | Search municipalities |
| `get_tc_por_estados()` | `get_tc_by_state()` | Transfers by state |
| `get_tc_por_estados_detalhe()` | `get_tc_by_state_detail()` | Detailed transfers by state |
| `get_tc_por_municipio()` | `get_tc_by_municipality()` | Transfers by municipality |
| `get_tc_por_municipio_detalhe()` | `get_tc_by_municipality_detail()` | Detailed transfers by municipality |

## Examples

### Step 1: Lookup codes

All filter parameters use numeric codes internal to this API (they are
**not** IBGE codes). Always look up codes first.

```{r}
library(tesouror)

# Transfer types — returns codigo + nome
tipos <- get_tc_transfer_types()
tipos
# e.g., codigo=10 nome="FUNDEB", codigo=14 nome="AJUSTE FUNDEB"

# State codes — returns codigo + nome
estados <- get_tc_states()
estados
# e.g., codigo=16 nome="Pernambuco" (NOT the IBGE code!)

# Municipality codes — filter by the state code from above
pe_code <- estados$codigo[estados$nome == "Pernambuco"]
mun_pe <- get_tc_municipalities(state_code = pe_code)
mun_pe
```

### State-level transfers

```{r}
# Use the state code obtained from get_tc_states()
pe_code <- estados$codigo[estados$nome == "Pernambuco"]

# All transfers for Pernambuco in 2023
tc_pe <- get_tc_by_state(state_code = pe_code, year = 2023)

# FUNDEB + AJUSTE FUNDEB — pass a vector of transfer type codes
tc_fundeb <- get_tc_by_state(
  state_code = pe_code,
  year = 2023,
  transfer_type = c(10, 14)
)

# Multiple states, Jan-Mar 2023 — vectors work everywhere
ac_code <- estados$codigo[estados$nome == "Acre"]
al_code <- estados$codigo[estados$nome == "Alagoas"]
tc_multi <- get_tc_by_state(
  state_code = c(ac_code, al_code),
  year = 2023,
  month = 1:3
)

# Same query with detailed breakdown
tc_det <- get_tc_by_state_detail(
  state_code = c(ac_code, al_code),
  year = 2023,
  month = 1:3
)
```

### Municipality-level transfers

```{r}
# Look up municipality codes
pe_code <- estados$codigo[estados$nome == "Pernambuco"]
mun_pe <- get_tc_municipalities(state_code = pe_code)
recife_code <- mun_pe$codigo[mun_pe$nome == "Recife"]

# All municipalities in Pernambuco in 2023
tc_mun <- get_tc_by_municipality(state_code = pe_code, year = 2023)

# Specific municipality: Recife
tc_recife <- get_tc_by_municipality_detail(
  state_code = pe_code,
  municipality = recife_code,
  year = 2023
)
```

## Parameter mapping

| Portuguese | English | Description |
|:---|:---|:---|
| `p_estado` | `state_code` | Numeric state code(s) from `get_tc_estados()` (Treasury code, NOT IBGE) |
| `p_municipio` | `municipality` | Numeric municipality code(s) from `get_tc_municipios()` (Treasury code) |
| `p_ano` | `year` | Year(s) |
| `p_mes` | `month` | Month(s) |
| `p_transferencia` | `transfer_type` | Transfer type code(s) from `get_tc_transferencias()` |
| `p_sn_detalhar` | `detailed` | Include detail breakdown |
| `p_nome` | `name` | Municipality name search (partial match) |
| `p_uf` | `state_code` | Numeric state code from `get_tc_estados()` (for municipality lookup) |

All multi-value parameters accept either a colon-separated string (`"1:2:3"`)
or an R vector (`c(1, 2, 3)`).