# SADIPEM API – Public debt & credit operations

## About

The SADIPEM API (`https://apidatalake.tesouro.gov.br/docs/sadipem/`) provides data on Public Debt Verification Letters (PVL) — the process by which subnational entities (states and municipalities) request authorization for credit operations and debt management from the National Treasury.

## Available functions

Portuguese | English | Description
--- | --- | ---
`get_pvl()` | `get_debt_requests()` | Search PVL requests
`get_pvl_tramitacao()` | `get_pvl_status()` | Approved PVL processing status
`get_opc_cronograma_liberacoes()` | `get_credit_release_schedule()` | Credit release schedule
`get_opc_cronograma_pagamentos()` | `get_credit_payment_schedule()` | Credit payment schedule
`get_opc_taxa_cambio()` | `get_credit_exchange_rate()` | Exchange rate data
`get_res_cdp()` | `get_debt_capacity()` | Debt capacity result (CDP)
`get_res_cronograma_pagamentos()` | `get_debt_payment_schedule()` | Debt payment schedule result

## Typical workflow

The usual workflow is to first search for PVL requests, then use the `id_pleito` value from the results to fetch detailed information.

Important: `id_pleito` is a database ID (e.g., `40353`), not a row number. Use `pvl$id_pleito[1]` to get the value from the first row, not `pvl$id_pleito[40353]` (which tries to access row 40,353).

    library(tesouror)
    library(dplyr)

    # Step 1: Search PVLs for Pernambuco
    pvl_pe <- get_debt_requests(state = "PE")

    # Step 2: Pick an id_pleito VALUE from the results
    id <- pvl_pe$id_pleito[1]

    # Step 3: Get details using that id_pleito
    pagamentos <- get_credit_payment_schedule(request_id = id)
    cdp <- get_debt_capacity(request_id = id)

### PVL processing status

The `get_pvl_status()` / `get_pvl_tramitacao()` function only returns data for approved (deferred) non-credit operation PVLs. Filter by `status == "Deferido"` first:

    pvl_deferidos <- pvl_pe |> filter(status == "Deferido")
    if (nrow(pvl_deferidos) > 0) {
      status <- get_pvl_status(request_id = pvl_deferidos$id_pleito[1])
    }

## Parameter mapping

### `get_pvl()` / `get_debt_requests()`

Portuguese | English | Description
--- | --- | ---
`uf` | `state` | State abbreviation
`tipo_interessado` | `entity_type` | Type of requesting entity
`id_ente` | `entity_id` | IBGE entity code

### Detail functions

All detail functions (`get_pvl_tramitacao`, `get_opc_*`, `get_res_*`) require a single parameter:

Portuguese | English | Description
--- | --- | ---
`id_pleito` | `request_id` | Database ID of the PVL request