README

Cliente PHP 8.1+ para consultar el tipo de cambio USD compra y venta del SDDE del BCCR. Funciona en PHP puro, Laravel y WordPress; no depende de ninguno de esos frameworks.

Requisitos

PHP 8.1 o superior.
La extensión curl habilitada (php -m | grep curl).
Composer.
Un token SDDE generado en el portal del BCCR.

Instalación

Cuando esté publicado en Packagist:

composer require juniorov/bccr-sdde-exchange-rate

Para probarlo antes de publicar, en el composer.json de su aplicación agregue un repositorio local. Cambie la ruta si su aplicación no está junto a este repo:

{
  "repositories": [
    { "type": "path", "url": "../exchange-rate/packages/php" }
  ],
  "require": {
    "juniorov/bccr-sdde-exchange-rate": "*"
  }
}

Después ejecute composer update juniorov/bccr-sdde-exchange-rate.

Primer programa PHP

Cree un archivo .env que no vaya a Git:
```
BCCR_SDDE_TOKEN=pegue_aqui_su_token
```
Cargue esa variable con el mecanismo habitual de su proyecto. Para una prueba rápida en terminal puede usar export BCCR_SDDE_TOKEN='...'.

Cree tipo-cambio.php:

<?php
require __DIR__ . '/vendor/autoload.php';

use Bccr\Sdde\BccrClient;

$token = getenv('BCCR_SDDE_TOKEN');
$client = new BccrClient($token);
$rates = $client->dollarRates();

echo "Fecha: {$rates->date}\n";
echo 'Compra: ₡' . number_format($rates->buy->value, 2) . "\n";
echo 'Venta: ₡' . number_format($rates->sell->value, 2) . "\n";

Ejecute php tipo-cambio.php.

API del cliente

`dollarRates()`

Obtiene compra y venta. Por defecto busca los últimos 10 días y devuelve el último valor disponible de cada indicador.

$rates = $client->dollarRates();
// $rates->date       Ejemplo: '2026-07-24'
// $rates->buy->value Ejemplo: 500.25
// $rates->sell->value

Para consultar con fecha de referencia y una ventana distinta:

$rates = $client->dollarRates(new DateTimeImmutable('2026-07-24'), 7);

`series()`

Devuelve todos los puntos de un indicador en un intervalo:

$series = $client->series(317, '2026-07-01', '2026-07-24');
foreach ($series as $rate) {
    echo "{$rate->date}: {$rate->value}\n";
}

Códigos configurables

Si el BCCR confirma códigos distintos para su cuenta:

$client = new BccrClient($token, BccrClient::BASE_URL, 317, 318);
//                                       compra       venta

Laravel

Instale el paquete con Composer.
En .env agregue BCCR_SDDE_TOKEN=....

En config/services.php agregue:

'bccr' => ['token' => env('BCCR_SDDE_TOKEN')],

En app/Providers/AppServiceProvider.php, registre un singleton:

use Bccr\Sdde\BccrClient;

public function register(): void
{
    $this->app->singleton(BccrClient::class, fn () => new BccrClient(
        config('services.bccr.token')
    ));
}

Inyéctelo en un controlador y use caché para no consultar el BCCR en cada solicitud:

use Bccr\Sdde\BccrClient;
use Illuminate\Support\Facades\Cache;

public function show(BccrClient $bccr)
{
    $rates = Cache::remember('bccr.usd.rates', now()->addHour(),
        fn () => $bccr->dollarRates()
    );
    return response()->json($rates);
}

WordPress

Instale Composer dentro de su plugin personalizado. No añada el token al tema, porque podría terminar en un repositorio o una copia pública.

Cree wp-content/plugins/mi-tipo-cambio/.
Copie el ejemplo de examples/wordpress/bccr-sdde-example.php como archivo principal del plugin.
Desde esa carpeta ejecute Composer y asegúrese de que vendor/ exista.
En wp-config.php, antes de la línea “That's all”, agregue:
```
define('BCCR_SDDE_TOKEN', 'su_token_real');
```
Active el plugin y agregue [bccr_tipo_cambio] a una página.

El ejemplo usa un transient de una hora: protege el token y reduce llamadas al API. Para forzar actualización, borre el transient bccr_usd_rates.

Manejo de errores

La librería lanza BccrException. Revise el código HTTP para informar una acción útil al usuario o registrar el incidente:

use Bccr\Sdde\BccrException;

try {
    $rates = $client->dollarRates();
} catch (BccrException $error) {
    if ($error->statusCode === 401) {
        // Token ausente, inválido o vencido.
    } elseif ($error->statusCode === 429) {
        // Demasiadas solicitudes: use caché y reintente más tarde.
    }
    error_log($error->getMessage()); // Nunca registre el token.
}

Los códigos comunes son 401 (token), 403 (suscripción), 404 (URL/configuración), 429 (demasiadas solicitudes) y 500 (problema del BCCR).

Pruebas

Desde esta carpeta ejecute:

composer test

La prueba no contacta al BCCR ni requiere token real.

juniorov / bccr-sdde-exchange-rate

Package info

Security

Statistics