### Install and Use BCV Exchange Rates Package

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Provides instructions for installing the BCV Exchange Rates package using pip or Poetry. Also includes an example of how to use the `get_bcv_exchange_rates` function within a Python application to convert USD to VES.

```bash
# Install from PyPI
pip install bcv_exchange_rates

# Or clone and install with Poetry
git clone https://github.com/tomkat-cr/bcv-exchange-rates.git
cd bcv-exchange-rates
make install   # runs: poetry install

# Run tests
make test      # runs: poetry run pytest
```

```python
# Use in a Django/Flask/FastAPI application
from bcv_exchange_rates.bcv import get_bcv_exchange_rates

def convert_usd_to_ves(usd_amount: float) -> dict:
    """Convert a USD amount to Venezuelan Bolívares using the official BCV rate."""
    rates = get_bcv_exchange_rates()
    if rates["error"]:
        return {"error": True, "message": rates["error_message"]}

    usd_rate = rates["data"]["dolar"]["value"]
    if usd_rate is None:
        return {"error": True, "message": "USD rate unavailable"}

    ves_amount = usd_amount * usd_rate
    return {
        "error": False,
        "usd": usd_amount,
        "ves": round(ves_amount, 2),
        "rate": usd_rate,
        "as_of": rates["data"]["effective_date_ymd"],
    }

print(convert_usd_to_ves(100))
```

--------------------------------

### Install Dependencies with Make

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Installs project dependencies using Poetry via the Makefile. Ensure Poetry is installed and configured.

```bash
git clone https://github.com/tomkat-cr/bcv-exchange-rates.git
cd bcv-exchange-rates
make install
```

--------------------------------

### Setup and Maintenance Commands

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Common development commands for managing project dependencies and build artifacts. Use 'make' to see all available commands.

```bash
# Install dependencies
make install

# Clean build artifacts and cache
make clean

# Update dependencies and rebuild environment
make update
```

--------------------------------

### Run Application Commands

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Commands to run the application in different modes: CLI, as a module, or with a local development server. Ensure the application is installed.

```bash
# Run the CLI version (outputs exchange rates as JSON)
make run

# Run the module directly (same as "make run")
make run_module

# Run local development server with Vercel
make run_vercel
```

--------------------------------

### Get Exchange Rates as Python Module

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Imports and uses the `get_bcv_exchange_rates` function from the library to retrieve current exchange rates. Requires the library to be installed.

```python
from bcv_exchange_rates.bcv import get_bcv_exchange_rates

# Get current exchange rates
rates = get_bcv_exchange_rates()
print(rates)
```

--------------------------------

### Run Tests with Make

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Executes all project tests using pytest via the Makefile. Ensure tests are written and pytest is installed.

```bash
# Run all tests
make test
```

--------------------------------

### Run CLI Exchange Rates

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Executes the command-line interface to fetch and display current exchange rates in JSON format. This is a quick way to get data without Python imports.

```bash
make run
```

--------------------------------

### GET /get_bcv_exchange_rates

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

The FastAPI application exposes a single GET endpoint that returns the full exchange rate payload as JSON. It is deployed to Vercel and available at `https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates`.

```APIDOC
## REST API Endpoint — `GET /get_bcv_exchange_rates`

The FastAPI application exposes a single GET endpoint that returns the full exchange rate payload as JSON. It is deployed to Vercel and available at `https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates`. The response shape mirrors the Python function's return value.

```bash
# Fetch current BCV exchange rates via the hosted API
curl https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates

# Pretty-print with jq
curl -s https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates | jq .

# Example JSON response:
# {
#   "error": false,
#   "error_message": [],
#   "data": {
#     "euro":  { "symbol": "EUR", "value": 39.39949699, "error": false, "error_message": null },
#     "yuan":  { "symbol": "CNY", "value": 5.07429452,  "error": false, "error_message": null },
#     "lira":  { "symbol": "TRY", "value": 1.08005430,  "error": false, "error_message": null },
#     "rublo": { "symbol": "RUB", "value": 0.40213624,  "error": false, "error_message": null },
#     "dolar": { "symbol": "USD", "value": 36.50000000, "error": false, "error_message": null },
#     "effective_date":     "Lunes, 21 Julio 2025",
#     "effective_date_ymd": "2025-07-21",
#     "run_timestamp":      "2025-07-21 14:32:10 UTC"
#   }
# }

# Run locally with Vercel CLI
make run_vercel
curl http://localhost:3000/get_bcv_exchange_rates | jq .
```
```

--------------------------------

### Run BCV Exchange Rates CLI

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Shows how to execute the BCV Exchange Rates module as a command-line tool to output exchange rates to stdout. Useful for shell scripting and cron jobs. Includes examples for piping to jq and extracting specific values.

```bash
# Via Makefile
make run

# Or directly via Python module
python -m bcv_exchange_rates.index cli

# Pipe to jq for pretty output
python -m bcv_exchange_rates.index cli | jq .

# Use specific fields in a shell script
RATE=$(python -m bcv_exchange_rates.index cli | jq -r '.data.dolar.value')
echo "Current USD/VES rate: $RATE"
```

--------------------------------

### Fetch BCV Exchange Rates via REST API

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Demonstrates how to fetch the full exchange rate payload from the deployed Vercel API endpoint using curl. Includes examples for pretty-printing with jq and running locally.

```bash
# Fetch current BCV exchange rates via the hosted API
curl https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates

# Pretty-print with jq
curl -s https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates | jq .

# Run locally with Vercel CLI
make run_vercel
curl http://localhost:3000/get_bcv_exchange_rates | jq .
```

--------------------------------

### Get BCV Exchange Rates (Production API)

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

This is the production API endpoint to retrieve current BCV currency exchange rates. It is hosted on Vercel.

```APIDOC
## Get BCV Exchange Rates (Production API)

### Description
Access the production API to fetch current currency exchange rates from the Banco Central de Venezuela (BCV).

### Method
GET

### Endpoint
`https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates`

### Parameters
None

### Request Example
```bash
curl https://bcv-exchange-rates.vercel.app/get_bcv_exchange_rates
```

### Response
#### Success Response (200 OK)
Returns a JSON object containing exchange rate data.
- **error** (boolean) - Indicates if an error occurred.
- **error_message** (array) - A list of error messages, if any.
- **data** (object) - Contains the exchange rate details.
  - **euro** (object)
    - **symbol** (string) - Currency symbol (EUR).
    - **value** (string) - Exchange rate value for Euro.
  - **yuan** (object)
    - **symbol** (string) - Currency symbol (CNY).
    - **value** (string) - Exchange rate value for Yuan.
  - **lira** (object)
    - **symbol** (string) - Currency symbol (TRY).
    - **value** (string) - Exchange rate value for Lira.
  - **rublo** (object)
    - **symbol** (string) - Currency symbol (RUB).
    - **value** (string) - Exchange rate value for Rublo.
  - **dolar** (object)
    - **symbol** (string) - Currency symbol (USD).
    - **value** (string) - Exchange rate value for Dollar.
  - **effective_date** (string) - The effective date of the exchange rates.
  - **run_timestamp** (string) - The timestamp when the data was retrieved.

#### Response Example
```json
{
  "error": false,
  "error_message": [],
  "data": {
    "euro": {
      "symbol": "EUR",
      "value": "19,39949699"
    },
    "yuan": {
      "symbol": "CNY",
      "value": "2,67429452"
    },
    "lira": {
      "symbol": "TRY",
      "value": "0,98005430"
    },
    "rublo": {
      "symbol": "RUB",
      "value": "0,25213624"
    },
    "dolar": {
      "symbol": "USD",
      "value": "18,39460000"
    },
    "effective_date": "Viernes, 06 Enero  2023",
    "run_timestamp": "2023-01-06 11:55:42 UTC"
  }
}
```
```

--------------------------------

### Python Package Usage

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

BCV Exchange Rates can be installed as a Python package from PyPI or from source using Poetry, making it embeddable in any Python application that needs programmatic access to official Venezuelan Bolívar exchange rates.

```APIDOC
## Installation and Package Usage

BCV Exchange Rates can be installed as a Python package from PyPI or from source using Poetry, making it embeddable in any Python application that needs programmatic access to official Venezuelan Bolívar exchange rates.

```bash
# Install from PyPI
pip install bcv_exchange_rates

# Or clone and install with Poetry
git clone https://github.com/tomkat-cr/bcv-exchange-rates.git
cd bcv-exchange-rates
make install   # runs: poetry install

# Run tests
make test      # runs: poetry run pytest
```

```python
# Use in a Django/Flask/FastAPI application
from bcv_exchange_rates.bcv import get_bcv_exchange_rates

def convert_usd_to_ves(usd_amount: float) -> dict:
    """Convert a USD amount to Venezuelan Bolívares using the official BCV rate."""
    rates = get_bcv_exchange_rates()
    if rates["error"]:
        return {"error": True, "message": rates["error_message"]}

    usd_rate = rates["data"]["dolar"]["value"]
    if usd_rate is None:
        return {"error": True, "message": "USD rate unavailable"}

    ves_amount = usd_amount * usd_rate
    return {
        "error": False,
        "usd": usd_amount,
        "ves": round(ves_amount, 2),
        "rate": usd_rate,
        "as_of": rates["data"]["effective_date_ymd"],
    }

print(convert_usd_to_ves(100))
# {"error": False, "usd": 100, "ves": 3650.0, "rate": 36.5, "as_of": "2025-07-21"}
```
```

--------------------------------

### Get BCV Exchange Rates (Python Module)

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

This function retrieves the current exchange rates from the BCV. It can be used as a Python module within your applications.

```APIDOC
## Get BCV Exchange Rates

### Description
Retrieves the current currency exchange rates from the Banco Central de Venezuela (BCV).

### Method
Python Module Function

### Function Signature
`get_bcv_exchange_rates()`

### Parameters
None

### Request Example
```python
from bcv_exchange_rates.bcv import get_bcv_exchange_rates

rates = get_bcv_exchange_rates()
print(rates)
```

### Response
#### Success Response
Returns a JSON object containing exchange rate data.
- **error** (boolean) - Indicates if an error occurred.
- **error_message** (array) - A list of error messages, if any.
- **data** (object) - Contains the exchange rate details.
  - **euro** (object)
    - **symbol** (string) - Currency symbol (EUR).
    - **value** (string) - Exchange rate value for Euro.
  - **yuan** (object)
    - **symbol** (string) - Currency symbol (CNY).
    - **value** (string) - Exchange rate value for Yuan.
  - **lira** (object)
    - **symbol** (string) - Currency symbol (TRY).
    - **value** (string) - Exchange rate value for Lira.
  - **rublo** (object)
    - **symbol** (string) - Currency symbol (RUB).
    - **value** (string) - Exchange rate value for Rublo.
  - **dolar** (object)
    - **symbol** (string) - Currency symbol (USD).
    - **value** (string) - Exchange rate value for Dollar.
  - **effective_date** (string) - The effective date of the exchange rates.
  - **run_timestamp** (string) - The timestamp when the data was retrieved.

#### Response Example
```json
{
  "error": false,
  "error_message": [],
  "data": {
    "euro": {
      "symbol": "EUR",
      "value": "19,39949699"
    },
    "yuan": {
      "symbol": "CNY",
      "value": "2,67429452"
    },
    "lira": {
      "symbol": "TRY",
      "value": "0,98005430"
    },
    "rublo": {
      "symbol": "RUB",
      "value": "0,25213624"
    },
    "dolar": {
      "symbol": "USD",
      "value": "18,39460000"
    },
    "effective_date": "Viernes, 06 Enero  2023",
    "run_timestamp": "2023-01-06 11:55:42 UTC"
  }
}
```
```

--------------------------------

### BCV Exchange Rates JSON Response

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Example of the JSON response structure returned by the API, containing exchange rates for various currencies, effective date, and run timestamp. Note the format of currency values.

```json
{
  "error": false,
  "error_message": [],
  "data": {
    "euro": {
      "symbol": "EUR",
      "value": "19,39949699"
    },
    "yuan": {
      "symbol": "CNY",
      "value": "2,67429452"
    },
    "lira": {
      "symbol": "TRY",
      "value": "0,98005430"
    },
    "rublo": {
      "symbol": "RUB",
      "value": "0,25213624"
    },
    "dolar": {
      "symbol": "USD",
      "value": "18,39460000"
    },
    "effective_date": "Viernes, 06 Enero  2023",
    "run_timestamp": "2023-01-06 11:55:42 UTC"
  }
}
```

--------------------------------

### Get Current UTC Timestamp String

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Generates a formatted string of the current UTC date and time, useful for logging or API response timestamps. The format is 'YYYY-MM-DD HH:MM:SS UTC'.

```python
from bcv_exchange_rates.utilities import get_formatted_date

timestamp = get_formatted_date()
print(timestamp)
```

--------------------------------

### Publish to PyPI Commands

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Commands for building and publishing the package to PyPI, including test and production environments. Ensure build tools and credentials are set up.

```bash
# Build package for PyPI
make pypi-build

# Publish to test PyPI
make pypi-publish-test

# Publish to production PyPI
make pypi-publish
```

--------------------------------

### get_bcv_exchange_rates() — Fetch all exchange rates

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

The main entry point of the library. It fetches the BCV website, parses the HTML, and returns a structured dictionary containing exchange values for USD, EUR, CNY, TRY, RUB, the effective date (both in Spanish and ISO format), and a UTC timestamp. SSL errors are silently retried without certificate verification, and any network or parsing error is captured in the `error` / `error_message` fields rather than raising an exception.

```APIDOC
## `get_bcv_exchange_rates()` — Fetch all exchange rates

### Description
The main entry point of the library. It fetches the BCV website, parses the HTML, and returns a structured dictionary containing exchange values for USD, EUR, CNY, TRY, RUB, the effective date (both in Spanish and ISO format), and a UTC timestamp. SSL errors are silently retried without certificate verification, and any network or parsing error is captured in the `error` / `error_message` fields rather than raising an exception.

### Usage
```python
from bcv_exchange_rates.bcv import get_bcv_exchange_rates

rates = get_bcv_exchange_rates()

if rates["error"]:
    print("Error fetching rates:", rates["error_message"])
else:
    data = rates["data"]
    print(f"USD: {data['dolar']['value']} {data['dolar']['symbol']}")
    print(f"EUR: {data['euro']['value']} {data['euro']['symbol']}")
    print(f"CNY: {data['yuan']['value']} {data['yuan']['symbol']}")
    print(f"TRY: {data['lira']['value']} {data['lira']['symbol']}")
    print(f"RUB: {data['rublo']['value']} {data['rublo']['symbol']}")
    print(f"Effective date (Spanish): {data['effective_date']}")
    print(f"Effective date (ISO):     {data['effective_date_ymd']}")
    print(f"Run timestamp:            {data['run_timestamp']}")
```

### Response Structure
- **error** (boolean): Indicates if an error occurred during fetching or parsing.
- **error_message** (string): A message describing the error, if `error` is true.
- **data** (dict): A dictionary containing the exchange rates and related information.
  - **dolar** (dict): Exchange rate for USD.
    - **value** (float): The exchange rate value.
    - **symbol** (string): The currency symbol (USD).
  - **euro** (dict): Exchange rate for EUR.
    - **value** (float): The exchange rate value.
    - **symbol** (string): The currency symbol (EUR).
  - **yuan** (dict): Exchange rate for CNY.
    - **value** (float): The exchange rate value.
    - **symbol** (string): The currency symbol (CNY).
  - **lira** (dict): Exchange rate for TRY.
    - **value** (float): The exchange rate value.
    - **symbol** (string): The currency symbol (TRY).
  - **rublo** (dict): Exchange rate for RUB.
    - **value** (float): The exchange rate value.
    - **symbol** (string): The currency symbol (RUB).
  - **effective_date** (string): The effective date in Spanish format.
  - **effective_date_ymd** (string): The effective date in ISO 8601 format (YYYY-MM-DD).
  - **run_timestamp** (string): The timestamp when the data was fetched (UTC).
```

--------------------------------

### Deployment Commands

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Commands for deploying the application to production or managing staging deployments. Deployment to Vercel is supported.

```bash
# Deploy to production (Vercel)
make deploy_prod

# Rename staging deployment (requires deployment URL as parameter)
make rename_staging <deployment-url>
```

--------------------------------

### Run Module Directly

Source: https://github.com/tomkat-cr/bcv-exchange-rates/blob/main/README.md

Executes the main module directly using the Python interpreter to display exchange rates. This is an alternative to using 'make run'.

```bash
python -m bcv_exchange_rates.index cli
```

--------------------------------

### CLI Usage

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

The module can be executed directly from the terminal to print the full exchange rate JSON to stdout. This is useful for shell scripts, cron jobs, or quick one-off queries.

```APIDOC
## CLI Usage — Run as a command-line tool

The module can be executed directly from the terminal to print the full exchange rate JSON to stdout. This is useful for shell scripts, cron jobs, or quick one-off queries.

```bash
# Via Makefile
make run

# Or directly via Python module
python -m bcv_exchange_rates.index cli

# Pipe to jq for pretty output
python -m bcv_exchange_rates.index cli | jq .

# Use specific fields in a shell script
RATE=$(python -m bcv_exchange_rates.index cli | jq -r '.data.dolar.value')
echo "Current USD/VES rate: $RATE"
# Current USD/VES rate: 36.5
```
```

--------------------------------

### Fetch all BCV exchange rates using Python

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Use this function to retrieve all available exchange rates from the BCV website. It handles network and parsing errors internally, returning an error status and message if issues occur. Ensure you check the 'error' field before accessing the 'data'.

```python
from bcv_exchange_rates.bcv import get_bcv_exchange_rates

rates = get_bcv_exchange_rates()

if rates["error"]:
    print("Error fetching rates:", rates["error_message"])
else:
    data = rates["data"]
    print(f"USD: {data['dolar']['value']} {data['dolar']['symbol']}")
    print(f"EUR: {data['euro']['value']} {data['euro']['symbol']}")
    print(f"CNY: {data['yuan']['value']} {data['yuan']['symbol']}")
    print(f"TRY: {data['lira']['value']} {data['lira']['symbol']}")
    print(f"RUB: {data['rublo']['value']} {data['rublo']['symbol']}")
    print(f"Effective date (Spanish): {data['effective_date']}")
    print(f"Effective date (ISO):     {data['effective_date_ymd']}")
    print(f"Run timestamp:            {data['run_timestamp']}")

# Expected output:
# USD: 36.5 USD
# EUR: 39.84949699 EUR
# CNY: 5.07429452 CNY
# TRY: 1.08005430 TRY
# RUB: 0.40213624 RUB
# Effective date (Spanish): Lunes, 21 Julio 2025
# Effective date (ISO):     2025-07-21
# Run timestamp:            2025-07-21 14:32:10 UTC
```

--------------------------------

### Normalize and convert currency string to float

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Use this utility function to convert currency strings from the BCV website, which use a comma as a decimal separator, into Python floats. It also accepts dot separators and returns None with a UserWarning for invalid inputs.

```python
from bcv_exchange_rates.utilities import fix_value
import warnings

# Normal conversion (BCV uses comma as decimal separator)
print(fix_value("36,50000000"))  # 36.5
print(fix_value("0,25213624"))   # 0.25213624
print(fix_value("1.23"))         # 1.23  (dot separator also accepted)

# Invalid input returns None and warns
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    result = fix_value("N/A")
    print(result)                # None
    print(w[0].message)          # Invalid value encountered in fix_value: N/A. Error: ...
```

--------------------------------

### Convert Spanish Date String to ISO 8601

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Parses Spanish date strings like 'Lunes, 21 Julio 2025' into 'YYYY-MM-DD' format. Handles various input formats and returns None for invalid or unrecognized dates. Month names are case-insensitive.

```python
from bcv_exchange_rates.utilities import convert_spanish_date

print(convert_spanish_date("Lunes, 21 Julio 2025"))
print(convert_spanish_date("Martes, 1 Enero 2024"))
print(convert_spanish_date("Viernes, 06 Enero 2023"))
print(convert_spanish_date("Lunes, 21 XYZ 2025"))
print(convert_spanish_date("Invalid Date"))
print(convert_spanish_date(None))
print(convert_spanish_date(""))
```

--------------------------------

### fix_value(value) — Normalize and convert a currency string to float

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Converts a comma-decimal string as returned by the BCV website (e.g., "36,50000000") into a Python `float` by replacing `,` with `.`. Returns `None` and emits a `UserWarning` if the input is not a valid numeric string or is `None`.

```APIDOC
## `fix_value(value)` — Normalize and convert a currency string to float

### Description
Converts a comma-decimal string as returned by the BCV website (e.g., `"36,50000000"`) into a Python `float` by replacing `,` with `.`. Returns `None` and emits a `UserWarning` if the input is not a valid numeric string or is `None`.

### Parameters
#### Path Parameters
- **value** (string) - Required - The currency string to normalize and convert.

### Usage
```python
from bcv_exchange_rates.utilities import fix_value
import warnings

# Normal conversion (BCV uses comma as decimal separator)
print(fix_value("36,50000000"))  # 36.5
print(fix_value("0,25213624"))   # 0.25213624
print(fix_value("1.23"))         # 1.23  (dot separator also accepted)

# Invalid input returns None and warns
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    result = fix_value("N/A")
    print(result)                # None
    print(w[0].message)          # Invalid value encountered in fix_value: N/A. Error: ...
```

### Returns
- **float**: The normalized numeric value.
- **None**: If the input value is invalid or cannot be converted.
```

--------------------------------

### get_currency_section_value(soup, apiResponse, currency) — Parse a single currency block

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Locates a specific currency `<div id="<currency>">` within a BeautifulSoup-parsed document and populates `apiResponse['data'][currency]` with `symbol` (from `<span>`) and `value` (from `<strong>`, converted to `float`). If the `<div>` is missing or the required tags are absent, it sets `error: True` and records a descriptive message on the per-currency entry without affecting the parent response's error flag.

```APIDOC
## `get_currency_section_value(soup, apiResponse, currency)` — Parse a single currency block

### Description
Locates a specific currency `<div id="<currency>">` within a BeautifulSoup-parsed document and populates `apiResponse['data'][currency]` with `symbol` (from `<span>`) and `value` (from `<strong>`, converted to `float`). If the `<div>` is missing or the required tags are absent, it sets `error: True` and records a descriptive message on the per-currency entry without affecting the parent response's error flag.

### Parameters
#### Path Parameters
- **soup** (BeautifulSoup object) - Required - The parsed HTML document from BeautifulSoup.
- **apiResponse** (dict) - Required - The dictionary to populate with currency data and errors.
- **currency** (string) - Required - The identifier for the currency to parse (e.g., "dolar", "euro").

### Usage
```python
from bs4 import BeautifulSoup
from bcv_exchange_rates.bcv import get_currency_section_value

html = """
<div id="dolar">
    <strong>36,50000000</strong>
    <span>USD</span>
</div>
"""
soup = BeautifulSoup(html, "html.parser")
api_response = {"data": {}, "error": False, "error_message": []}

get_currency_section_value(soup, api_response, "dolar")

entry = api_response["data"]["dolar"]
if entry["error"]:
    print("Parse error:", entry["error_message"])
else:
    print(f"Symbol: {entry['symbol']}")   # Symbol: USD
    print(f"Value:  {entry['value']}")    # Value:  36.5
    print(f"Type:   {type(entry['value']).__name__}")  # Type: float
```

### Response Structure (within `apiResponse['data'][currency]`)
- **symbol** (string): The currency symbol (e.g., "USD").
- **value** (float): The exchange rate value.
- **error** (boolean): Indicates if an error occurred while parsing this specific currency.
- **error_message** (string): A message describing the error for this currency, if `error` is true.
```

--------------------------------

### convert_spanish_date

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Parses a Spanish date string in the format "Día, DD Mes AAAA" and returns the equivalent "YYYY-MM-DD" string. Returns None for invalid inputs.

```APIDOC
## `convert_spanish_date(date_str)` — Convert Spanish date string to ISO 8601

Parses a date string in the format `"Día, DD Mes AAAA"` (as published by the BCV, e.g., `"Lunes, 21 Julio 2025"`) and returns the equivalent `"YYYY-MM-DD"` string. Month names are matched case-insensitively. Returns `None` for `None`, empty strings, strings with fewer than 4 parts, or unrecognized month names.

```python
from bcv_exchange_rates.utilities import convert_spanish_date

print(convert_spanish_date("Lunes, 21 Julio 2025"))      # "2025-07-21"
print(convert_spanish_date("Martes, 1 Enero 2024"))      # "2024-01-01"
print(convert_spanish_date("Viernes, 06 Enero 2023"))    # "2023-01-06"
print(convert_spanish_date("Lunes, 21 XYZ 2025"))        # None (unknown month)
print(convert_spanish_date("Invalid Date"))              # None (too few parts)
print(convert_spanish_date(None))                        # None
print(convert_spanish_date(""))                          # None
```
```

--------------------------------

### get_formatted_date

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

Returns the current UTC date and time as a formatted string in the "YYYY-MM-DD HH:MM:SS UTC" format.

```APIDOC
## `get_formatted_date()` — Get current UTC timestamp string

Returns the current UTC date and time as a formatted string in the `"YYYY-MM-DD HH:MM:SS UTC"` format. Used internally to populate the `run_timestamp` field in every API response.

```python
from bcv_exchange_rates.utilities import get_formatted_date

timestamp = get_formatted_date()
print(timestamp)
# "2025-07-21 14:32:10 UTC"
```
```

--------------------------------

### Parse a single currency block from HTML

Source: https://context7.com/tomkat-cr/bcv-exchange-rates/llms.txt

This function is used internally to parse a specific currency's data from an HTML document using BeautifulSoup. It populates a given response dictionary with the currency symbol and value, handling missing elements by setting an error flag and message for that specific currency.

```python
from bs4 import BeautifulSoup
from bcv_exchange_rates.bcv import get_currency_section_value

html = """
<div id="dolar">
    <strong>36,50000000</strong>
    <span>USD</span>
</div>
"""
soup = BeautifulSoup(html, "html.parser")
api_response = {"data": {}, "error": False, "error_message": []}

get_currency_section_value(soup, api_response, "dolar")

entry = api_response["data"]["dolar"]
if entry["error"]:
    print("Parse error:", entry["error_message"])
else:
    print(f"Symbol: {entry['symbol']}")   # Symbol: USD
    print(f"Value:  {entry['value']}")    # Value:  36.5
    print(f"Type:   {type(entry['value']).__name__}")  # Type: float
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.