Skip to main content

​
Overview

The Currency Rates API provides endpoints to retrieve and update USD (Dollar) and EUR (Euro) exchange rates for Venezuelan Bolivares. Rates are fetched from DolarAPI and cached for performance.

​
Caching

  • Rates are cached for 1 hour (3600 seconds)
  • Cache is automatically invalidated when rates are refreshed
  • Fallback rates are used if the database has no active rates:
    • USD: 36.50 Bs.
    • EUR: 495.00 Bs.

​
Get Dollar Rate

Retrieve the current USD exchange rate from cache or database. This is a public endpoint.

​
Response

​
success
boolean
Always true
​
rate
float
Current USD exchange rate in Bolivares
{
  "success": true,
  "rate": 36.50
}

​
Get Euro Rate

Retrieve the current EUR exchange rate from cache or database. This is a public endpoint.

​
Response

​
success
boolean
Always true
​
rate
float
Current EUR exchange rate in Bolivares
{
  "success": true,
  "rate": 495.00
}

​
Refresh Dollar Rate

Fetch the latest USD rate from DolarAPI and propagate it to all active tenants with auto-update enabled.

​
Process Flow

  1. Fetch rate from https://ve.dolarapi.com/v1/dolares/oficial
  2. Validate rate is positive and reasonable (max 10% change warning)
  3. Deactivate previous USD rates in database
  4. Store new rate with source: 'dolarapi'
  5. Invalidate cache
  6. Propagate to all active tenants with auto_update: true

​
Response

​
success
boolean
Whether the operation was successful
​
rate
float
The new exchange rate (only on success)
​
source
string
Always 'dolarapi' (only on success)
​
message
string
Descriptive message about the operation result
{
  "success": true,
  "rate": 36.75,
  "source": "dolarapi",
  "message": "Rate successfully fetched and stored"
}

​
Rate Change Alerts

If the new rate differs from the previous rate by more than 10%, a warning is logged: 
Log::warning('DollarRateService: Unusual rate change detected', [
    'previous_rate' => 36.50,
    'new_rate' => 41.00,
    'change_percent' => 12.33,
]);

​
Refresh Euro Rate

Fetch the latest EUR rate from DolarAPI and propagate it to all active tenants with auto-update enabled.

​
Process Flow

  1. Fetch rate from https://ve.dolarapi.com/v1/euros/oficial
  2. Validate rate is positive
  3. Deactivate previous EUR rates in database
  4. Store new rate with source: 'dolarapi'
  5. Invalidate cache
  6. Propagate to all active tenants with auto_update: true

​
Response

​
success
boolean
Whether the operation was successful
​
rate
float
The new exchange rate (only on success)
​
source
string
Always 'dolarapi' (only on success)
​
message
string
Descriptive message about the operation result
{
  "success": true,
  "rate": 498.50,
  "source": "dolarapi",
  "message": "EUR rate successfully fetched and stored"
}

​
Auto-Propagation to Tenants

When rates are refreshed, they are automatically propagated to all active tenants that have auto_update enabled in their currency settings.

​
Tenant Currency Settings Updated

For USD: 
{
  "engine_settings": {
    "currency": {
      "exchange_rate": 36.75,
      "source": "dolarapi",
      "last_update": "2026-03-08",
      "auto_update": true
    }
  }
}
For EUR: 
{
  "engine_settings": {
    "currency": {
      "euro_rate": 498.50,
      "euro_last_update": "2026-03-08",
      "auto_update": true
    }
  }
}

​
Skipping Tenants

Tenants are skipped if:
  • status is not 'active'
  • auto_update is set to false

​
Implementation Notes

​
HTTP Timeout

All external API requests use a 10-second timeout to prevent hanging.

​
Database Schema

Rates are stored in the dollar_rates table:
ColumnTypeDescription
ratedecimal(10,4)Exchange rate value
sourcestringAlways 'dolarapi'
currency_typeenum'USD' or 'EUR'
effective_fromtimestampWhen rate became active
effective_untiltimestampWhen rate was deactivated
is_activebooleanWhether this is the current rate

​
Example Scheduled Job

You can schedule automatic rate updates using Laravel’s task scheduler: 
// app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
    // Update USD and EUR rates every 6 hours
    $schedule->call(function () {
        $service = app(DollarRateService::class);
        $service->fetchAndPropagateAll();
    })->everySixHours();
}

Build docs developers (and LLMs) love

Get started for freeTalk to us