Installation Guide

System Requirements

Before installing Mi API BCV, ensure your system meets these requirements:

Required

PHP: 8.2 or higher
Composer: Latest version (2.x)
Database: One of the following:
- SQLite 3.8.8+ (default, easiest setup)
- MySQL 5.7+ / MariaDB 10.3+
- PostgreSQL 10.0+
PHP Extensions:
- BCMath
- Ctype
- cURL
- DOM
- Fileinfo
- JSON
- Mbstring
- OpenSSL
- PCRE
- PDO
- Tokenizer
- XML

Checking PHP Requirements

# Check PHP version
php -v

# Check installed extensions
php -m

# Check Composer version
composer --version

If you’re missing extensions, install them using your system’s package manager (apt, yum, brew, etc.).

Installation Steps

Clone the Repository

Clone the Mi API BCV repository to your local machine:

git clone https://github.com/yourusername/mi-api-bcv.git
cd mi-api-bcv

Alternatively, download and extract the ZIP file if not using Git.

Install PHP Dependencies

Use Composer to install all required PHP packages:

composer install

This installs:

Laravel 12 framework
Symfony DomCrawler for web scraping
Symfony CSS Selector for HTML parsing
Laravel Sanctum for API authentication
Other Laravel dependencies

The first installation may take a few minutes depending on your internet connection.

Create Environment File

Copy the example environment file:

cp .env.example .env

This creates your .env configuration file with default settings.

Generate Application Key

Generate a unique application encryption key:

php artisan key:generate

This updates the APP_KEY in your .env file. This key is used for:

Session encryption
Password hashing
Data encryption

Never share your APP_KEY publicly or commit it to version control.

Configure Database

Option A: SQLite (Recommended for Development)Create the SQLite database file:

touch database/database.sqlite

Verify .env settings:

DB_CONNECTION=sqlite

Option B: MySQLCreate a MySQL database:

CREATE DATABASE mi_api_bcv CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Update .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mi_api_bcv
DB_USERNAME=your_username
DB_PASSWORD=your_password

Option C: PostgreSQLCreate a PostgreSQL database:

CREATE DATABASE mi_api_bcv;

Update .env:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=mi_api_bcv
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run Database Migrations

Create all necessary database tables:

php artisan migrate

This creates:

reference_records - Stores exchange rate data
cache - Stores cached responses
cache_locks - Handles cache locking
jobs - Manages queue jobs
job_batches - Tracks batch jobs
failed_jobs - Logs failed queue jobs
sessions - Stores session data
users - User authentication (optional)
personal_access_tokens - API tokens (optional)

Expected output:

INFO  Preparing database.

Creating migration table ............................ 15.12ms DONE

INFO  Running migrations.

0001_01_01_000000_create_users_table ................ 10.45ms DONE
0001_01_01_000001_create_cache_table ................ 8.23ms DONE
0001_01_01_000002_create_jobs_table ................. 7.89ms DONE
2026_01_27_133458_create_personal_access_tokens_table 6.12ms DONE
2026_01_28_203351_create_reference_records_table .... 5.67ms DONE

Set File Permissions

Ensure Laravel can write to storage and cache directories:

# Linux/macOS
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Or for development
chmod -R 777 storage bootstrap/cache

777 permissions are only for development. Use 775 with proper ownership in production.

Configure Cache

The default .env uses database caching:

CACHE_STORE=database

No additional setup needed. For Redis caching, see the Configuration Guide.

Fetch Initial Exchange Rates

Populate the database with current exchange rates:

php artisan rates:update

Expected output:

Iniciando actualización de tasas...
Banco bdv procesado.
Banco banplus procesado.
Banco bnc procesado.
Banco bcv procesado.
Tasas actualizadas exitosamente.

This command scrapes all four banks and stores their current rates. It may take 10-30 seconds depending on network speed.

Start Development Server

Launch the built-in PHP development server:

php artisan serve

The API is now accessible at:

http://localhost:8000

Alternatively, specify a different port:

php artisan serve --port=8080

Verify Installation

Test API Endpoint

curl http://localhost:8000/

Expected response:

{
  "message": "Consulta exitosa",
  "bdv": {
    "value": 45.26,
    "date": "2026-03-04"
  },
  "banplus": {
    "value": 45.30,
    "date": "2026-03-04"
  },
  "bnc": {
    "value": 45.28,
    "date": "2026-03-04"
  },
  "bcv": {
    "value": 45.25,
    "date": "2026-03-04"
  }
}

Check Database

php artisan tinker

// Count stored records
App\Models\ReferenceRecord::count();
// Should return: 4 (one for each bank)

// View all records
App\Models\ReferenceRecord::all();

Test Specific Bank

curl http://localhost:8000/info/2026-03-04/bcv

Should return only BCV data.

Post-Installation

Set Up Scheduled Tasks

To automatically update rates, configure the Laravel scheduler: Linux/macOS:

crontab -e

Add:

* * * * * cd /path/to/mi-api-bcv && php artisan schedule:run >> /dev/null 2>&1

Windows: Use Task Scheduler to run every minute:

Program: C:\path\to\php.exe
Arguments: artisan schedule:run
Start in: C:\path\to\mi-api-bcv

Configure Logging

Logs are stored in storage/logs/laravel.log. To monitor:

tail -f storage/logs/laravel.log

Optional: Install Node Dependencies

If you plan to customize frontend assets:

npm install
npm run build

Common Installation Issues

Composer install fails

Problem: Composer can’t install dependenciesSolutions:

Update Composer: composer self-update
Clear Composer cache: composer clear-cache
Increase memory limit: php -d memory_limit=-1 $(which composer) install
Check PHP version: php -v (must be 8.2+)

Migration fails

Problem: php artisan migrate returns errorsSolutions:

Verify database connection in .env
Test connection: php artisan tinker then DB::connection()->getPdo();
Check database exists: mysql -u root -p then SHOW DATABASES;
For SQLite: Ensure database/database.sqlite exists and is writable
Reset migrations: php artisan migrate:fresh (WARNING: deletes all data)

Permission denied errors

Problem: Laravel can’t write to directoriesSolutions:

# Linux/macOS
sudo chown -R $USER:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

# Or development only
chmod -R 777 storage bootstrap/cache

rates:update command fails

Problem: Scraping command returns errorsSolutions:

Check internet connection
Verify cURL extension: php -m | grep curl
Check logs: tail -f storage/logs/laravel.log
Test individual bank in tinker:

php artisan tinker
$service = new \App\Services\UrlProviderService();
$service->getStrategy('bcv')->getValue();

Port 8000 already in use

Problem: php artisan serve failsSolutions:

Use different port: php artisan serve --port=8080
Kill existing process:
- Linux/macOS: lsof -ti:8000 | xargs kill
- Windows: netstat -ano | findstr :8000 then taskkill /PID <pid> /F

Directory Structure

After installation, your directory structure should look like:

mi-api-bcv/
├── app/
│   ├── Console/Commands/
│   │   └── FetchExchangeRates.php
│   ├── Http/Controllers/Api/
│   │   └── ScraperController.php
│   ├── Models/
│   │   └── ReferenceRecord.php
│   ├── Observers/
│   │   └── ReferenceObserver.php
│   ├── Services/
│   │   ├── ScraperService.php
│   │   └── UrlProviderService.php
│   └── Strategies/Url/
│       ├── UrlBcv.php
│       ├── UrlBanplus.php
│       ├── UrlBnc.php
│       └── UrlBdv.php
├── bootstrap/
├── config/
├── database/
│   ├── migrations/
│   └── database.sqlite
├── public/
├── resources/
├── routes/
│   ├── api.php
│   └── console.php
├── storage/
│   └── logs/
├── tests/
├── vendor/
├── .env
├── .env.example
├── artisan
├── composer.json
└── composer.lock

Next Steps

Configuration

Configure environment variables and settings

Deployment

Deploy to production

How It Works

Understand the architecture

API Reference

Explore API endpoints

Get Started

Core Concepts

Guides

System Requirements

Required

Recommended

Checking PHP Requirements

Installation Steps

Verify Installation

Test API Endpoint

Check Database

Test Specific Bank

Post-Installation

Set Up Scheduled Tasks

Configure Logging

Optional: Install Node Dependencies

Common Installation Issues

Directory Structure

Next Steps

Configuration

Deployment

How It Works

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​System Requirements

​Required

​Recommended

​Checking PHP Requirements

​Installation Steps

​Verify Installation

​Test API Endpoint

​Check Database

​Test Specific Bank

​Post-Installation

​Set Up Scheduled Tasks

​Configure Logging

​Optional: Install Node Dependencies

​Common Installation Issues

​Directory Structure

​Next Steps

Configuration

Deployment

How It Works

API Reference

Build docs developers (and LLMs) love

System Requirements

Required

Recommended

Checking PHP Requirements

Installation Steps

Verify Installation

Test API Endpoint

Check Database

Test Specific Bank

Post-Installation

Set Up Scheduled Tasks

Configure Logging

Optional: Install Node Dependencies

Common Installation Issues

Directory Structure

Next Steps