Installation Guide

This guide covers the complete installation and configuration of the SUNAT Electronic Invoicing API on your server.

System Requirements

Minimum Requirements

PHP

Version 8.2 or higher with required extensions

Database

MySQL 8.0+ or PostgreSQL 12+

Composer

Latest stable version for dependency management

Web Server

Apache 2.4+ or Nginx 1.18+ (optional for production)

Required PHP Extensions

Verify these extensions are installed and enabled:

php -m | grep -E 'openssl|pdo|mbstring|tokenizer|xml|ctype|json|bcmath|curl|fileinfo|zip'

Required extensions:

openssl - For certificate handling
pdo_mysql or pdo_pgsql - Database connectivity
mbstring - Multibyte string handling
tokenizer - Laravel requirement
xml - XML processing
ctype - Character type checking
json - JSON handling
bcmath - Arbitrary precision mathematics
curl - HTTP requests to SUNAT
fileinfo - File type detection
zip - Handling CDR zip files

If any extensions are missing, install them before proceeding:

# Ubuntu/Debian
sudo apt-get install php8.2-{cli,fpm,mysql,xml,mbstring,curl,zip,bcmath}

# CentOS/RHEL
sudo yum install php82-{cli,fpm,mysqlnd,xml,mbstring,curl,zip,bcmath}

Step 1: Clone the Repository

Clone the project from GitHub:

git clone https://github.com/yorchavez9/Api-de-facturacion-electronica-sunat-Peru.git
cd Api-de-facturacion-electronica-sunat-Peru

Alternatively, download the ZIP file and extract it to your preferred location.

Step 2: Install Dependencies

Install all required PHP packages using Composer:

composer install

This will install:

Package	Version	Purpose
laravel/framework	^12.0	Core framework
greenter/lite	^5.1	SUNAT integration
greenter/consulta-cpe	*	CPE query service
dompdf/dompdf	^3.1	PDF generation
endroid/qr-code	*	QR code creation
laravel/sanctum	^4.0	API authentication

Installation time: Composer installation typically takes 2-5 minutes depending on your internet connection.

Step 3: Environment Configuration

Create your environment configuration file:

cp .env.example .env

Generate Application Key

php artisan key:generate

This generates a secure encryption key for Laravel.

Configure Environment Variables

Edit the .env file with your settings:

# Application Configuration
APP_NAME="API Facturación SUNAT - BETA"
APP_ENV=local
APP_KEY=base64:YOUR_GENERATED_KEY
APP_DEBUG=true
APP_URL=http://localhost:8000

# Locale Configuration
APP_LOCALE=es
APP_FALLBACK_LOCALE=es
APP_FAKER_LOCALE=es_PE

Step 4: Database Setup

Create Database

MySQL
PostgreSQL

CREATE DATABASE db_api_sunat CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Create dedicated user (recommended)
CREATE USER 'sunat_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON db_api_sunat.* TO 'sunat_user'@'localhost';
FLUSH PRIVILEGES;

CREATE DATABASE db_api_sunat WITH ENCODING 'UTF8';

-- Create dedicated user (recommended)
CREATE USER sunat_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE db_api_sunat TO sunat_user;

Run Migrations

Execute database migrations to create all required tables:

php artisan migrate

This creates the following tables:

Core Tables

users - System users and authentication
roles - User roles (super_admin, admin, user)
permissions - Granular permissions
role_permission - Role-permission mapping
personal_access_tokens - API tokens (Sanctum)

Company Tables

companies - Issuing companies
company_configurations - Per-company settings
branches - Branch offices
clients - Customers and suppliers
correlatives - Document series and numbering

Document Tables

invoices - Electronic invoices (Facturas)
boletas - Sales receipts
credit_notes - Credit notes (future)
debit_notes - Debit notes (future)

Ubigeo Tables

ubi_regiones - Peru regions
ubi_provincias - Provinces
ubi_distritos - Districts

System Tables

jobs - Queue jobs
cache - Application cache
sessions - User sessions

Expected output: All migrations should run successfully with no errors

Step 5: Certificate Setup

Understanding SUNAT Certificates

SUNAT requires a digital certificate to sign electronic documents. You’ll receive a .pfx file from your certificate provider.

Convert Certificate to PEM Format

The API uses .pem format certificates. Convert your .pfx file:

# Convert .pfx to .pem (includes both private key and certificate)
openssl pkcs12 -in certificado.pfx -out certificado.pem -nodes

You’ll be prompted for the certificate password. This is the password provided by your certificate authority, not your SOL password.

What this command does:

-in certificado.pfx - Input file
-out certificado.pem - Output file
-nodes - Don’t encrypt the private key

Place Certificate in Correct Location

# Create certificate directory
mkdir -p storage/app/public/certificado

# Copy certificate (maintain strict permissions)
cp certificado.pem storage/app/public/certificado/certificado.pem
chmod 644 storage/app/public/certificado/certificado.pem

For testing: SUNAT provides test certificates for the beta environment. Contact SUNAT or use the credentials from their documentation.

Verify Certificate

Validate your certificate is correctly formatted:

# View certificate details
openssl x509 -in storage/app/public/certificado/certificado.pem -text -noout

# Check private key
openssl rsa -in storage/app/public/certificado/certificado.pem -check

Expected components in the .pem file:

-----BEGIN PRIVATE KEY-----
[Base64 encoded private key]
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
[Base64 encoded certificate]
-----END CERTIFICATE-----

Step 6: Storage Permissions

Set correct permissions for Laravel storage and cache:

# Set storage permissions
chmod -R 775 storage bootstrap/cache

# Set ownership (if running as www-data)
sudo chown -R www-data:www-data storage bootstrap/cache

# Create SUNAT files directory
mkdir -p storage/app/sunat
chmod -R 775 storage/app/sunat

# Create Greenter cache directory
mkdir -p storage/app/greenter/cache
chmod -R 775 storage/app/greenter/cache

Security Note: Never set permissions to 777. Use 775 for directories and 664 for files, with appropriate ownership.

Step 7: Test the Installation

Start Development Server

php artisan serve

The server will start at http://localhost:8000

Verify API is Running

Test the system info endpoint:

curl http://localhost:8000/api/system/info

Expected response:

{
  "system_initialized": false,
  "user_count": 0,
  "roles_count": 0,
  "app_name": "API Facturación SUNAT - BETA",
  "app_env": "local",
  "app_debug": true,
  "database_connected": true
}

If database_connected: true, your installation is successful!

Step 8: Optional - Seed Sample Data

Load sample ubigeo (geographic) data:

php artisan db:seed --class=UbigeoSeeder

This populates Peru’s regions, provinces, and districts for address validation.

Production Deployment

Optimization Commands

Before deploying to production:

# Optimize configuration loading
php artisan config:cache

# Optimize route loading
php artisan route:cache

# Optimize view compilation
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

Production Environment

Update .env for production:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Use production SUNAT endpoints
SUNAT_ENVIRONMENT=production

Web Server Configuration

Nginx
Apache

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/api-sunat/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/api-sunat/public

    <Directory /var/www/api-sunat/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/sunat-error.log
    CustomLog ${APACHE_LOG_DIR}/sunat-access.log combined
</VirtualHost>

Enable required modules:

sudo a2enmod rewrite
sudo systemctl restart apache2

SSL/HTTPS Setup

For production, always use HTTPS:

# Using Certbot (Let's Encrypt)
sudo apt-get install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Queue Configuration (Optional)

For better performance, configure queues:

# Update .env
QUEUE_CONNECTION=database

# Run migrations for jobs table (already included)
php artisan migrate

# Start queue worker
php artisan queue:work --tries=3 --timeout=90

For production, use Supervisor:

[program:sunat-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/api-sunat/artisan queue:work database --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/api-sunat/storage/logs/worker.log
stopwaitsecs=3600

Troubleshooting

500 Internal Server Error

Symptoms: White page or 500 errorSolutions:

Check storage permissions: chmod -R 775 storage
Clear cached config: php artisan config:clear
Check Laravel logs: tail -f storage/logs/laravel.log
Verify .env file exists and APP_KEY is set

Database Connection Failed

Symptoms: SQLSTATE[HY000] [2002] Connection refusedSolutions:

Verify database is running: systemctl status mysql
Check credentials in .env
Test connection: php artisan migrate:status
Verify database exists: SHOW DATABASES;

Certificate Not Found

Symptoms: Archivo de certificado no encontradoSolutions:

Verify path: ls -l storage/app/public/certificado/
Check file exists: certificado.pem
Verify permissions: chmod 644 certificado.pem
Check certificate format with openssl

Composer Memory Exhausted

Symptoms: Fatal error: Allowed memory size exhaustedSolutions:

Increase PHP memory: php -d memory_limit=-1 /usr/bin/composer install
Or update php.ini: memory_limit = 512M

Permission Denied Errors

Symptoms: Cannot write to storage/logsSolutions:

# Fix ownership
sudo chown -R $USER:www-data storage bootstrap/cache

# Fix permissions
chmod -R 775 storage bootstrap/cache

# Set default ACL (if available)
setfacl -R -m u:www-data:rwX storage bootstrap/cache
setfacl -dR -m u:www-data:rwX storage bootstrap/cache

Verification Checklist

Before proceeding to create invoices:

Database Connected

✓ system/info endpoint returns database_connected: true

Migrations Complete

✓ All tables created: php artisan migrate:status

Certificate Installed

✓ Certificate exists at storage/app/public/certificado/certificado.pem

Storage Writable

✓ Storage directories have correct permissions

Environment Configured

✓ .env file has all required settings

Next Steps

Now that installation is complete:

Quickstart Guide

Create your first invoice in 10 minutes

API Reference

Explore all available endpoints

Authentication

Learn about API authentication

Configuration

Advanced configuration options

Getting Help

If you encounter issues during installation:

Check the GitHub Issues
Review Laravel logs in storage/logs/laravel.log
Watch the YouTube tutorial series
Contact via WhatsApp

Get Started

Core Concepts

Guides

Advanced

​Installation Guide

​System Requirements

​Minimum Requirements

PHP

Database

Composer

Web Server

​Required PHP Extensions

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Environment Configuration

​Generate Application Key

​Configure Environment Variables

​Step 4: Database Setup

​Create Database

​Run Migrations

​Step 5: Certificate Setup

​Understanding SUNAT Certificates

​Convert Certificate to PEM Format

​Place Certificate in Correct Location

​Verify Certificate

​Step 6: Storage Permissions

​Step 7: Test the Installation

​Start Development Server

​Verify API is Running

​Step 8: Optional - Seed Sample Data

​Production Deployment

​Optimization Commands

​Production Environment

​Web Server Configuration

​SSL/HTTPS Setup

​Queue Configuration (Optional)

​Troubleshooting

​Verification Checklist

​Next Steps

Quickstart Guide

API Reference

Authentication

Configuration

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Minimum Requirements

Required PHP Extensions

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Generate Application Key

Configure Environment Variables

Step 4: Database Setup

Create Database

Run Migrations

Step 5: Certificate Setup

Understanding SUNAT Certificates

Convert Certificate to PEM Format

Place Certificate in Correct Location

Verify Certificate

Step 6: Storage Permissions

Step 7: Test the Installation

Start Development Server

Verify API is Running

Step 8: Optional - Seed Sample Data

Production Deployment

Optimization Commands

Production Environment

Web Server Configuration

SSL/HTTPS Setup

Queue Configuration (Optional)

Troubleshooting

Verification Checklist

Next Steps

Getting Help