System Setup - SUNAT Electronic Invoicing API

Overview

The Setup API provides endpoints for initializing and configuring the SUNAT electronic invoicing system. These endpoints handle database migrations, seed data, system configuration, and company setup.

Setup endpoints should only be used during initial system installation or when performing major system updates. Some endpoints are public (no authentication required) while others require authentication.

System Status

Checks the current status of the system and setup progress.

This endpoint does not require authentication and can be used to verify system readiness before login.

Response

system_status

object

database_connected

boolean

Whether database connection is successful

migrations_pending

boolean

Whether there are pending database migrations

seeders_executed

boolean

Whether ubigeo data has been seeded

companies_count

integer

Number of companies configured

users_count

integer

Number of users in the system

storage_writable

boolean

Whether storage directory is writable

certificates_directory

object

Status of certificate and logo directories

certificado_directory

boolean

Certificate directory exists

logo_directory

boolean

Logo directory exists

certificado_file_exists

boolean

Certificate file exists

storage_link_exists

boolean

Storage symbolic link exists

app_environment

string

Application environment (local, production, etc.)

company_environment

string

Company SUNAT environment (beta or produccion)

debug

boolean

Debug mode enabled

app_key_set

boolean

Application key is configured

certificate_exists

boolean

Company certificate exists

logo_exists

boolean

Company logo exists

setup_progress

object

Step-by-step setup progress

step_1_migrations

boolean

Migrations completed

step_2_seeders

boolean

Seeders executed

step_3_company

boolean

Company configured

step_4_ready

boolean

System ready for use

ready_for_use

boolean

Overall system readiness status

Example Request

curl -X GET "https://api.example.com/api/setup/status" \
  -H "Accept: application/json"

Example Response

{
  "system_status": {
    "database_connected": true,
    "migrations_pending": false,
    "seeders_executed": true,
    "companies_count": 1,
    "users_count": 2,
    "storage_writable": true,
    "certificates_directory": {
      "certificado_directory": true,
      "logo_directory": true,
      "certificado_file_exists": true,
      "storage_link_exists": true
    },
    "app_environment": "production",
    "company_environment": "beta",
    "debug": false,
    "app_key_set": true,
    "certificate_exists": true,
    "logo_exists": true,
    "setup_progress": {
      "step_1_migrations": true,
      "step_2_seeders": true,
      "step_3_company": true,
      "step_4_ready": true
    },
    "ready_for_use": true
  }
}

Run Migrations

Executes pending database migrations to create or update database schema.

This endpoint does not require authentication. It should be run before any other setup operations.

Example Request

curl -X POST "https://api.example.com/api/setup/migrate" \
  -H "Accept: application/json"

Example Response

{
  "message": "Migraciones ejecutadas exitosamente",
  "output": "Migrating: 2024_01_01_000000_create_companies_table\nMigrated:  2024_01_01_000000_create_companies_table (50.45ms)\nMigrating: 2024_01_01_000001_create_branches_table\nMigrated:  2024_01_01_000001_create_branches_table (42.33ms)\n..."
}

Run Seeders

Executes database seeders to populate initial data (primarily ubigeo geographic codes).

This endpoint does not require authentication. Run migrations before running seeders.

Request Body

class

string

default:"DatabaseSeeder"

Specific seeder class to run. Defaults to DatabaseSeeder which runs all seeders.

Example Request

curl -X POST "https://api.example.com/api/setup/seed" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "class": "DatabaseSeeder"
  }'

Example Response

{
  "message": "Seeder 'DatabaseSeeder' ejecutado exitosamente",
  "output": "Seeding: UbigeoSeeder\nSeeded:  UbigeoSeeder (1.2s)\n",
  "seeder_class": "DatabaseSeeder"
}

Complete Setup

Completes the full system setup by creating the first company, branch, and configuring SUNAT integration.

This endpoint requires authentication. Ensure you have run migrations and seeders first, and have created a user account.

Request Body

environment

string

required

SUNAT environment. Valid values: beta (testing) or produccion (production)

company

object

required

Example Request

curl -X POST "https://api.example.com/api/v1/setup/complete" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'environment=beta' \
  -F 'company[ruc]=20123456789' \
  -F 'company[razon_social]=MI EMPRESA SAC' \
  -F 'company[nombre_comercial]=Mi Empresa' \
  -F 'company[direccion]=Av. Principal 123, Miraflores' \
  -F 'company[ubigeo]=150122' \
  -F 'company[distrito]=Miraflores' \
  -F 'company[provincia]=Lima' \
  -F 'company[departamento]=Lima' \
  -F 'company[telefono]=+51 1 1234567' \
  -F 'company[email][email protected]' \
  -F 'company[web]=https://www.miempresa.com' \
  -F 'company[usuario_sol]=MODDATOS' \
  -F 'company[clave_sol]=moddatos' \
  -F 'certificado_pem=@/path/to/certificate.pem' \
  -F 'certificado_password=mycertpassword' \
  -F 'logo_path=@/path/to/logo.png' \
  -F 'modo_produccion=false' \
  -F 'activo=true'

Example Response

{
  "message": "Setup completado exitosamente",
  "company": {
    "id": 1,
    "ruc": "20123456789",
    "razon_social": "MI EMPRESA SAC",
    "environment": "beta",
    "has_certificate": true,
    "branch_count": 1
  },
  "branch": {
    "id": 1,
    "codigo": "0000",
    "nombre": "Sucursal Principal"
  }
}

Configure SUNAT

Configures or updates SUNAT integration settings for a company.

Requires authentication. User must be a super admin or belong to the company being configured.

Request Body

company_id

integer

required

The company ID to configure

environment

string

required

SUNAT environment: beta or produccion

certificate_file

file

Digital certificate file in PEM format

certificate_password

string

Certificate password

force_update

boolean

default:"false"

Force update of existing configuration

Example Request

curl -X POST "https://api.example.com/api/v1/setup/configure-sunat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'company_id=1' \
  -F 'environment=produccion' \
  -F 'certificate_file=@/path/to/production-cert.pem' \
  -F 'certificate_password=prodpassword' \
  -F 'force_update=true'

Example Response

{
  "message": "Configuración SUNAT actualizada exitosamente",
  "company": {
    "id": 1,
    "ruc": "20123456789",
    "environment": "produccion",
    "has_certificate": true
  }
}

Setup Workflow

Follow this sequence for initial system setup:

Step 1: Check System Status

curl -X GET "https://api.example.com/api/setup/status"

Verify database connectivity and identify pending steps.

Step 2: Run Migrations

curl -X POST "https://api.example.com/api/setup/migrate"

Create database tables and schema.

Step 3: Run Seeders

curl -X POST "https://api.example.com/api/setup/seed"

Populate ubigeo data and other initial records.

Step 4: Initialize Admin User

curl -X POST "https://api.example.com/api/auth/initialize" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin User",
    "email": "[email protected]",
    "password": "secure_password",
    "password_confirmation": "secure_password"
  }'

Create the first admin user account.

Step 5: Complete Setup

curl -X POST "https://api.example.com/api/v1/setup/complete" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'environment=beta' \
  -F 'company[ruc]=20123456789' \
  # ... other company fields

Create company, branch, and configure SUNAT integration.

Step 6: Verify Setup

curl -X GET "https://api.example.com/api/setup/status"

Confirm ready_for_use is true.

Error Responses

Migrations Required

{
  "success": false,
  "message": "Debe ejecutar las migraciones primero",
  "required_action": "POST /api/setup/migrate",
  "current_step": "migrations_required"
}

Seeders Required

{
  "success": false,
  "message": "Debe ejecutar los seeders primero",
  "required_action": "POST /api/setup/seed",
  "current_step": "seeders_required"
}

Permission Denied

{
  "message": "No tienes permisos para configurar esta empresa",
  "status": "error"
}

Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "company.ruc": [
      "El campo ruc es obligatorio.",
      "El campo ruc debe tener 11 caracteres."
    ],
    "company.ubigeo": [
      "El campo ubigeo debe tener 6 caracteres."
    ],
    "environment": [
      "El campo environment debe ser beta o produccion."
    ]
  }
}

SUNAT Environments

Beta Environment (Testing)

Use for: Development, testing, trainingEndpoint: https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billServiceCredentials: Use SUNAT-provided test credentials (MODDATOS/moddatos)Certificates: Test certificates from SUNATFeatures:

No real tax implications
Can generate test documents freely
RUC validation may be relaxed
CDR responses may differ from production

Production Environment

Use for: Real business operationsEndpoint: https://e-factura.sunat.gob.pe/ol-ti-itcpfegem/billServiceCredentials: Real company SOL credentialsCertificates: Valid digital certificates from authorized providersFeatures:

Real tax documents with legal validity
Strict validation
Must comply with all SUNAT regulations
Documents are permanent and auditable

Only switch to production after thorough testing in beta environment and obtaining proper certificates.

Digital Certificate Requirements

Digital certificates are required for signing electronic documents sent to SUNAT.

Certificate Format

Format: PEM (Privacy Enhanced Mail)
File Extensions: .pem, .crt, .cer
Max Size: 2MB

Obtaining Certificates

Beta Environment:
- Download test certificates from SUNAT’s website
- No cost, for testing only
Production Environment:
- Purchase from authorized Certificate Authorities (CA)
- Common providers in Peru: RENIEC, eCertiPerú, IFARHU
- Must be valid and not expired
- Associated with your company’s RUC

Certificate Password

Store certificate password securely
Required for signing documents
Include in setup configuration

Best Practices

Initial Setup

Always start with the beta environment
Test thoroughly before switching to production
Keep backup of configuration data
Document your setup process
Store certificates and passwords securely

Security

Use strong passwords for SOL credentials
Restrict access to setup endpoints in production
Enable HTTPS for all API communications
Regularly rotate SOL passwords
Monitor certificate expiration dates

Maintenance

Keep system status checks automated
Set up alerts for certificate expiration
Regular backup of company configurations
Document any custom configurations
Plan for environment switches (beta to production)

Multi-Company Setup

If managing multiple companies:

Complete setup for first company
Use company management endpoints for additional companies
Each company needs its own:
- RUC and business information
- SOL credentials
- Digital certificate
- SUNAT environment configuration
Users can be assigned to specific companies

Authentication

Companies & Branches

Clients

Electronic Documents

Consultations

Configuration

​Overview

​System Status

​Response

​Example Request

​Example Response

​Run Migrations

​Example Request

​Example Response

​Run Seeders

​Request Body

​Example Request

​Example Response

​Complete Setup

​Request Body

​Example Request

​Example Response

​Configure SUNAT

​Request Body

​Example Request

​Example Response

​Setup Workflow

​Step 1: Check System Status

​Step 2: Run Migrations

​Step 3: Run Seeders

​Step 4: Initialize Admin User

​Step 5: Complete Setup

​Step 6: Verify Setup

​Error Responses

​Migrations Required

​Seeders Required

​Permission Denied

​Validation Error

​SUNAT Environments

​Digital Certificate Requirements

​Certificate Format

​Obtaining Certificates

​Certificate Password

​Best Practices

Build docs developers (and LLMs) love

Overview

System Status

Response

Example Request

Example Response

Run Migrations

Example Request

Example Response

Run Seeders

Request Body

Example Request

Example Response

Complete Setup

Request Body

Example Request

Example Response

Configure SUNAT

Request Body

Example Request

Example Response

Setup Workflow

Step 1: Check System Status

Step 2: Run Migrations

Step 3: Run Seeders

Step 4: Initialize Admin User

Step 5: Complete Setup

Step 6: Verify Setup

Error Responses

Migrations Required

Seeders Required

Permission Denied

Validation Error

SUNAT Environments

Digital Certificate Requirements

Certificate Format

Obtaining Certificates

Certificate Password

Best Practices