Forem: Luis Dev

🚀 Automatiza tu Facturación Electrónica en Perú: De Manual a API en 10 minutos con PHP

Luis Dev — Thu, 26 Jun 2025 23:07:59 +0000

¿Sigues emitiendo facturas manualmente? Si eres desarrollador PHP en Perú, probablemente has sufrido con los procesos manuales de facturación de SUNAT. ¡Hay una mejor manera! Te muestro cómo automatizar todo el proceso con menos de 100 líneas de código PHP.

📋 Lo que vas a aprender

✅ Configurar facturación electrónica desde código PHP
✅ Integrar SUNAT con PHP usando APIs modernas
✅ Manejar errores y validaciones como un pro
✅ Optimizar el flujo para aplicaciones en producción
✅ Casos de uso reales y mejores prácticas

Tiempo estimado: 10-15 minutos | Nivel: Intermedio

🎯 El problema que todos enfrentamos

Como desarrolladores PHP, constantemente necesitamos integrar sistemas de facturación en nuestras aplicaciones. El proceso tradicional implica:

😤 Llenar formularios web manualmente
⏰ Perder tiempo en tareas repetitivas
🐛 Errores humanos en la captura de datos
🔄 Falta de automatización en workflows

La solución: Una API que maneje todo esto por nosotros.

🛠️ Tecnologías que usaremos

<?php
// Stack técnico
$stack = [
    'runtime' => 'PHP 8.0+',
    'API' => 'Billme',
    'method' => 'REST API',
    'format' => 'JSON',
    'auth' => 'Token-based',
    'http_client' => 'cURL / Guzzle'
];
?>

🚀 Setup inicial (2 minutos)

Prerrequisitos

PHP 8.0 o superior
Composer (para gestión de dependencias)
Cuenta gratuita en Billme
RUC de prueba

1. Crear cuenta de testing

# Paso 1: Registrarse en Billme
# Paso 2: Crear empresa de prueba
# Paso 3: Obtener token de sandbox

💡 Pro tip: Billme tiene ambiente de pruebas gratuito, perfecto para desarrollo y testing.

Sigue su documentación oficial para el setup inicial.

💻 Implementación paso a paso

Estructura del proyecto

facturacion-sunat-php/
├── src/
│   ├── Config/
│   │   └── BillmeConfig.php
│   ├── Services/
│   │   └── InvoiceService.php
│   ├── Utils/
│   │   └── Logger.php
│   └── Models/
│       └── Invoice.php
├── vendor/
├── composer.json
└── script.php

1. Configuración inicial con Composer

{
  "name": "tu-usuario/facturacion-sunat",
  "description": "Sistema de facturación electrónica para SUNAT con PHP",
  "require": {
    "php": "^8.0",
    "guzzlehttp/guzzle": "^7.0",
    "vlucas/phpdotenv": "^5.0"
  },
  "autoload": {
    "psr-4": {
      "FacturacionSunat\\": "src/"
    }
  }
}

2. Configuración base

<?php
// src/Config/BillmeConfig.php

namespace FacturacionSunat\Config;

class BillmeConfig
{
    private const BASE_URL = 'https://www.api.billmeperu.com/api/v1';
    private const ENDPOINTS = [
        'invoice' => '/Emission/EnviarBoletaFactura'
    ];

    private string $token;
    private string $environment;

    public function __construct()
    {
        $this->token = $_ENV['BILLME_TOKEN'] ?? 'your-token-here';
        $this->environment = $_ENV['BILLME_ENV'] ?? 'sandbox';
    }

    public function getBaseUrl(): string
    {
        return self::BASE_URL;
    }

    public function getInvoiceEndpoint(): string
    {
        return self::BASE_URL . self::ENDPOINTS['invoice'];
    }

    public function getToken(): string
    {
        return $this->token;
    }

    public function isProduction(): bool
    {
        return $this->environment === 'production';
    }

    public function getHeaders(): array
    {
        return [
            'Content-Type' => 'application/json',
            'token' => $this->token,
            'Accept' => 'application/json'
        ];
    }
}

3. Modelo de datos de factura

<?php
// src/Models/Invoice.php

namespace FacturacionSunat\Models;

class Invoice
{
    private array $data;

    public function __construct()
    {
        $this->data = [];
    }

    public function generateSampleInvoice(): array
    {
        $this->data = [
            'tipoOperacion' => '010',
            'serie' => 'F001',
            'correlativo' => $this->generateCorrelativo(),
            'fechaEmision' => date('Y-m-d'),
            'horaEmision' => '00:00:00',
            'fechaVencimiento' => date('Y-m-d'),
            'codigoTipoOperacion' => '0101',
            'codigoTipoDocumento' => '01',
            'moneda' => 'PEN',
            'montoCredito' => 0,
            'formaPago' => 'Contado',
            'igv' => 18.00,
            'icbper' => 0,
            'cuotas' => [],

            // Datos del emisor (tu empresa)
            'emisor' => [
                'codigoTipoDocumento' => '6',
                'numDocumento' => '20123456721',
                'razonSocial' => 'TU EMPRESA SAC',
                'nombreComercial' => 'TU EMPRESA',
                'ubigeo' => '150101', // Lima
                'ciudad' => 'LIMA',
                'distrito' => 'LIMA',
                'provincia' => 'LIMA',
                'direccion' => 'AV. EJEMPLO 123, LIMA'
            ],

            // Datos del cliente
            'cliente' => [
                'codigoTipoDocumento' => '1', // DNI
                'numDocumento' => '12345678',
                'razonSocial' => 'CLIENTE EJEMPLO',
                'nombreComercial' => 'CLIENTE EJEMPLO',
                'ubigeo' => '',
                'ciudad' => '',
                'distrito' => '',
                'provincia' => '',
                'direccion' => ''
            ],

            // Cálculos automáticos
            'totales' => [
                'totalOpGravadas' => 100.00,
                'totalOpInafectas' => 0,
                'totalOpExoneradas' => 0,
                'totalImpuestos' => 18.00,
                'totalSinImpuestos' => 100.00,
                'totalConImpuestos' => 118.00,
                'totalPagar' => 118.00,
                'totalDescuentoGlobal' => 0,
                'totalDescuentoProductos' => 0
            ],

            // Productos/servicios
            'productos' => [[
                'unidades' => 1,
                'codigoUnidad' => 'NIU', // Unidad
                'nombre' => 'Desarrollo de Software',
                'moneda' => 'PEN',
                'precioUnitario' => 100.00,
                'precioLista' => '118.00',
                'montoSinImpuesto' => 100.00,
                'montoImpuestos' => 18.00,
                'montoTotal' => 100.00,
                'montoIcbper' => 0,
                'factorIcbper' => 0,
                'montoDescuento' => 0,
                'codigoTipoPrecio' => '01',
                'impuestos' => [[
                    'monto' => 18.00,
                    'idCategoria' => 'S',
                    'porcentaje' => 18,
                    'codigoAfectacionIgv' => '10',
                    'codigoInterTributo' => 'VAT',
                    'nombreTributo' => 'IGV',
                    'codigoTributo' => '1000'
                ]],
                'id' => 'DEV001',
                'codigoClasificacion' => '531117'
            ]]
        ];

        return $this->data;
    }

    /**
     * Genera correlativo único basado en timestamp
     */
    private function generateCorrelativo(): string
    {
        $timestamp = substr((string) time(), -5);
        return str_pad($timestamp, 8, '0', STR_PAD_LEFT);
    }

    public function getData(): array
    {
        return $this->data;
    }

    public function setData(array $data): void
    {
        $this->data = $data;
    }
}

4. Servicio de facturación (¡La magia sucede aquí!)

<?php
// src/Services/InvoiceService.php

namespace FacturacionSunat\Services;

use FacturacionSunat\Config\BillmeConfig;
use FacturacionSunat\Models\Invoice;
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
use Exception;

class InvoiceService
{
    private BillmeConfig $config;
    private Client $httpClient;

    public function __construct()
    {
        $this->config = new BillmeConfig();
        $this->httpClient = new Client([
            'timeout' => 30,
            'verify' => true
        ]);
    }

    /**
     * Emite una factura electrónica a SUNAT
     * 
     * @param array $invoiceData Datos de la factura
     * @return array Respuesta de SUNAT
     * @throws Exception
     */
    public function emitInvoice(array $invoiceData): array
    {
        try {
            echo "🚀 Emitiendo factura a SUNAT...\n";

            $response = $this->httpClient->post($this->config->getInvoiceEndpoint(), [
                'headers' => $this->config->getHeaders(),
                'json' => $invoiceData,
                'timeout' => 30
            ]);

            $statusCode = $response->getStatusCode();
            $responseBody = $response->getBody()->getContents();
            $result = json_decode($responseBody, true);

            if ($statusCode !== 200) {
                throw new Exception("Error HTTP {$statusCode}: " . ($result['message'] ?? 'Error desconocido'));
            }

            echo "✅ Factura emitida exitosamente\n";
            echo "📄 Serie: {$invoiceData['serie']}-{$invoiceData['correlativo']}\n";
            echo "💰 Monto: S/ {$invoiceData['totales']['totalPagar']}\n";

            return $result;

        } catch (GuzzleException $e) {
            $errorMessage = "Error de conexión: " . $e->getMessage();
            echo "❌ $errorMessage\n";
            throw new Exception($errorMessage);
        } catch (Exception $e) {
            echo "❌ Error al emitir factura: {$e->getMessage()}\n";
            throw $e;
        }
    }

    /**
     * Emite factura con reintentos automáticos
     * 
     * @param array $invoiceData
     * @param int $maxRetries
     * @return array
     * @throws Exception
     */
    public function emitInvoiceWithRetry(array $invoiceData, int $maxRetries = 3): array
    {
        $lastException = null;

        for ($attempt = 1; $attempt <= $maxRetries; $attempt++) {
            try {
                return $this->emitInvoice($invoiceData);
            } catch (Exception $e) {
                $lastException = $e;

                if ($attempt === $maxRetries) {
                    throw $e;
                }

                echo "⚠️ Intento {$attempt} falló, reintentando...\n";
                sleep($attempt); // Backoff exponencial simple
            }
        }

        throw $lastException;
    }

    /**
     * Valida los datos de la factura antes de enviar
     * 
     * @param array $invoiceData
     * @return bool
     * @throws Exception
     */
    public function validateInvoiceData(array $invoiceData): bool
    {
        $requiredFields = [
            'serie', 'correlativo', 'fechaEmision', 'emisor', 
            'cliente', 'totales', 'productos'
        ];

        foreach ($requiredFields as $field) {
            if (!isset($invoiceData[$field])) {
                throw new Exception("Campo requerido faltante: {$field}");
            }
        }

        // Validar que el total sea mayor a 0
        if (($invoiceData['totales']['totalPagar'] ?? 0) <= 0) {
            throw new Exception("El total a pagar debe ser mayor a 0");
        }

        // Validar que tenga al menos un producto
        if (empty($invoiceData['productos'])) {
            throw new Exception("La factura debe tener al menos un producto");
        }

        return true;
    }

    /**
     * Procesa múltiples facturas de forma segura
     * 
     * @param array $invoicesData
     * @return array Resultados de todas las facturas
     */
    public function processBatchInvoices(array $invoicesData): array
    {
        $results = [];
        $rateLimitDelay = 1; // 1 segundo entre requests

        foreach ($invoicesData as $index => $invoiceData) {
            try {
                echo "\n📋 Procesando factura " . ($index + 1) . " de " . count($invoicesData) . "\n";

                $this->validateInvoiceData($invoiceData);
                $result = $this->emitInvoiceWithRetry($invoiceData);

                $results[] = [
                    'success' => true,
                    'data' => $result,
                    'invoice' => $invoiceData['serie'] . '-' . $invoiceData['correlativo']
                ];

                // Rate limiting para evitar saturar la API
                if ($index < count($invoicesData) - 1) {
                    sleep($rateLimitDelay);
                }

            } catch (Exception $e) {
                $results[] = [
                    'success' => false,
                    'error' => $e->getMessage(),
                    'invoice' => ($invoiceData['serie'] ?? 'N/A') . '-' . ($invoiceData['correlativo'] ?? 'N/A')
                ];
            }
        }

        return $results;
    }
}

5. Aplicación principal con manejo elegante de errores

<?php
// script.php

require_once 'vendor/autoload.php';

use FacturacionSunat\Services\InvoiceService;
use FacturacionSunat\Models\Invoice;
use Dotenv\Dotenv;

class InvoiceApp
{
    private InvoiceService $invoiceService;
    private Invoice $invoice;

    public function __construct()
    {
        // Cargar variables de entorno
        if (file_exists('.env')) {
            $dotenv = Dotenv::createImmutable(__DIR__);
            $dotenv->load();
        }

        $this->invoiceService = new InvoiceService();
        $this->invoice = new Invoice();
    }

    public function run(): void
    {
        echo "🏁 Iniciando proceso de facturación electrónica...\n\n";

        try {
            // Generar factura de ejemplo
            $invoiceData = $this->invoice->generateSampleInvoice();

            echo "📋 Datos de la factura:\n";
            echo "   Serie: {$invoiceData['serie']}-{$invoiceData['correlativo']}\n";
            echo "   Cliente: {$invoiceData['cliente']['razonSocial']}\n";
            echo "   Monto: S/ {$invoiceData['totales']['totalPagar']}\n\n";

            // Validar y emitir factura
            $this->invoiceService->validateInvoiceData($invoiceData);
            $result = $this->invoiceService->emitInvoiceWithRetry($invoiceData);

            // Mostrar resultado
            echo "\n🎉 ¡FACTURA EMITIDA EXITOSAMENTE!\n";

        } catch (Exception $e) {
            $this->handleError($e);
        }
    }

    /**
     * Maneja errores de manera elegante
     */
    private function handleError(Exception $error): void
    {
        echo "\n❌ ERROR EN LA EMISIÓN\n";
        echo str_repeat('═', 50) . "\n";
        echo "💥 Mensaje: {$error->getMessage()}\n";

        // Errores comunes y soluciones
        $message = $error->getMessage();
        if (strpos($message, 'token') !== false) {
            echo "💡 Solución: Verifica tu token de Billme\n";
        } elseif (strpos($message, '400') !== false) {
            echo "💡 Solución: Revisa los datos de la factura\n";
        } elseif (strpos($message, 'conexión') !== false || strpos($message, 'timeout') !== false) {
            echo "💡 Solución: Revisa tu conexión a internet\n";
        } elseif (strpos($message, 'Campo requerido') !== false) {
            echo "💡 Solución: Completa todos los campos obligatorios\n";
        }

        echo str_repeat('═', 50) . "\n";
    }

    /**
     * Demo de facturación masiva
     */
    public function runBatchDemo(): void
    {
        echo "🔥 DEMO: Facturación masiva\n\n";

        // Crear múltiples facturas de ejemplo
        $invoicesData = [];
        for ($i = 1; $i <= 3; $i++) {
            $invoice = new Invoice();
            $data = $invoice->generateSampleInvoice();
            $data['cliente']['razonSocial'] = "CLIENTE EJEMPLO {$i}";
            $data['totales']['totalPagar'] = 100 * $i;
            $data['totales']['totalConImpuestos'] = 100 * $i;
            $invoicesData[] = $data;
        }

        try {
            $results = $this->invoiceService->processBatchInvoices($invoicesData);

            echo "\n📊 RESUMEN DE PROCESAMIENTO:\n";
            echo str_repeat('═', 50) . "\n";

            $successful = array_filter($results, fn($r) => $r['success']);
            $failed = array_filter($results, fn($r) => !$r['success']);

            echo "✅ Exitosas: " . count($successful) . "\n";
            echo "❌ Fallidas: " . count($failed) . "\n";

            if (!empty($failed)) {
                echo "\n❌ Facturas fallidas:\n";
                foreach ($failed as $failure) {
                    echo "   - {$failure['invoice']}: {$failure['error']}\n";
                }
            }

            echo str_repeat('═', 50) . "\n";

        } catch (Exception $e) {
            $this->handleError($e);
        }
    }
}

// 🚀 Ejecutar la aplicación
try {
    $app = new InvoiceApp();

    // Factura individual
    $app->run();

    // Descomentar para probar facturación masiva
    // echo "\n" . str_repeat('-', 60) . "\n";
    // $app->runBatchDemo();

} catch (Exception $e) {
    echo "💥 Error fatal: {$e->getMessage()}\n";
    exit(1);
}

6. Archivo de configuración de entorno

# .env
BILLME_TOKEN=your-token-here
BILLME_ENV=sandbox
MAX_RETRIES=3
RATE_LIMIT_MS=1000

🎯 Ejecutar el código

# Instalar dependencias
composer install

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tu token de Billme

# Ejecutar el script
php script.php

🔥 Casos de uso avanzados

1. Integración con Laravel

<?php
// app/Services/SunatInvoiceService.php

namespace App\Services;

use FacturacionSunat\Services\InvoiceService;
use App\Models\Invoice as InvoiceModel;
use Illuminate\Support\Facades\Log;

class SunatInvoiceService
{
    private InvoiceService $invoiceService;

    public function __construct()
    {
        $this->invoiceService = new InvoiceService();
    }

    public function processInvoice(InvoiceModel $invoice): bool
    {
        try {
            $invoiceData = $this->mapInvoiceModelToArray($invoice);
            $result = $this->invoiceService->emitInvoice($invoiceData);

            // Actualizar modelo
            $invoice->update([
                'status' => 'emitted',
                'sunat_response' => $result,
                'pdf_url' => $result['linkPdf'] ?? null
            ]);

            Log::info("Factura emitida: {$invoice->serie}-{$invoice->correlativo}");
            return true;

        } catch (\Exception $e) {
            $invoice->update([
                'status' => 'failed',
                'error_message' => $e->getMessage()
            ]);

            Log::error("Error emitiendo factura: " . $e->getMessage());
            return false;
        }
    }

    private function mapInvoiceModelToArray(InvoiceModel $invoice): array
    {
        // Mapear tu modelo a la estructura requerida por Billme
        return [
            'serie' => $invoice->serie,
            'correlativo' => $invoice->correlativo,
            'fechaEmision' => $invoice->fecha_emision->format('Y-m-d'),
            // ... resto de campos
        ];
    }
}

2. API REST para facturación

<?php
// api/invoice.php

require_once '../vendor/autoload.php';

use FacturacionSunat\Services\InvoiceService;

header('Content-Type: application/json');

try {
    $method = $_SERVER['REQUEST_METHOD'];

    if ($method === 'POST') {
        $input = json_decode(file_get_contents('php://input'), true);

        if (!$input) {
            throw new Exception('Datos de factura inválidos');
        }

        $invoiceService = new InvoiceService();
        $invoiceService->validateInvoiceData($input);
        $result = $invoiceService->emitInvoice($input);

        http_response_code(200);
        echo json_encode([
            'success' => true,
            'data' => $result,
            'message' => 'Factura emitida exitosamente'
        ]);

    } else {
        http_response_code(405);
        echo json_encode([
            'success' => false,
            'message' => 'Método no permitido'
        ]);
    }

} catch (Exception $e) {
    http_response_code(400);
    echo json_encode([
        'success' => false,
        'message' => $e->getMessage()
    ]);
}

3. Comando de Artisan para Laravel

<?php
// app/Console/Commands/ProcessPendingInvoices.php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Models\Invoice;
use App\Services\SunatInvoiceService;

class ProcessPendingInvoices extends Command
{
    protected $signature = 'invoices:process-pending';
    protected $description = 'Procesa facturas pendientes de emisión';

    public function handle(SunatInvoiceService $invoiceService)
    {
        $pendingInvoices = Invoice::where('status', 'pending')->get();

        if ($pendingInvoices->isEmpty()) {
            $this->info('No hay facturas pendientes');
            return;
        }

        $this->info("Procesando {$pendingInvoices->count()} facturas...");

        $bar = $this->output->createProgressBar($pendingInvoices->count());

        foreach ($pendingInvoices as $invoice) {
            $success = $invoiceService->processInvoice($invoice);

            if ($success) {
                $this->line("✅ {$invoice->serie}-{$invoice->correlativo}");
            } else {
                $this->line("❌ {$invoice->serie}-{$invoice->correlativo}");
            }

            $bar->advance();
            sleep(1); // Rate limiting
        }

        $bar->finish();
        $this->newLine();
        $this->info('Procesamiento completado');
    }
}

🤝 Conclusión

¡Felicidades! Acabas de automatizar uno de los procesos más tediosos para cualquier developer peruano. Con este setup puedes:

✅ Emitir facturas desde cualquier aplicación

✅ Integrar con tus sistemas existentes

✅ Escalar sin límites (casi)

✅ Olvidarte de procesos manuales

💬 ¿Te funcionó?

Si implementaste este tutorial:

👍 Dale like si te sirvió
💬 Comparte tu experiencia en los comentarios
🔄 Compártelo con otros devs que necesiten esto
🐙 Sube tu versión a GitHub y comparte el repo

¿Tienes dudas? Comenta abajo y te ayudo a resolverlas.

📚 Referencias útiles

Documentación oficial de Billme

Tags: #php #sunat #facturacion #api #peru #automation #fintech

🚀 Automatiza tu Facturación Electrónica en Perú: De Manual a API en 10 minutos con Node.js

Luis Dev — Tue, 24 Jun 2025 00:06:27 +0000

¿Sigues emitiendo facturas manualmente? Si eres desarrollador en Perú, probablemente has sufrido con los procesos manuales de facturación de SUNAT. ¡Hay una mejor manera! Te muestro cómo automatizar todo el proceso con menos de 50 líneas de código.

📋 Lo que vas a aprender

✅ Configurar facturación electrónica desde código
✅ Integrar SUNAT con Node.js usando APIs modernas
✅ Manejar errores y validaciones como un pro
✅ Optimizar el flujo para aplicaciones en producción
✅ Casos de uso reales y mejores prácticas

Tiempo estimado: 10-15 minutos | Nivel: Intermedio

🎯 El problema que todos enfrentamos

Como desarrolladores, constantemente necesitamos integrar sistemas de facturación en nuestras aplicaciones. El proceso tradicional implica:

😤 Llenar formularios web manualmente
⏰ Perder tiempo en tareas repetitivas
🐛 Errores humanos en la captura de datos
🔄 Falta de automatización en workflows

La solución: Una API que maneje todo esto por nosotros.

🛠️ Tecnologías que usaremos

// Stack técnico
const stack = {
  runtime: "Node.js 18+",
  API: "Billme",
  method: "REST API",
  format: "JSON",
  auth: "Token-based"
};

🚀 Setup inicial (2 minutos)

Prerrequisitos

Node.js 18 o superior
Cuenta gratuita en Billme
RUC de prueba

1. Crear cuenta de testing

# Paso 1: Registrarse en Billme
# Paso 2: Crear empresa de prueba
# Paso 3: Obtener token de sandbox

💡 Pro tip: Billme tiene ambiente de pruebas gratuito, perfecto para desarrollo y testing.

Sigue su documentación oficial para el setup inicial.

💻 Implementación paso a paso

Estructura del proyecto

facturacion-sunat/
├── src/
│   ├── config/
│   │   └── billme.js
│   ├── services/
│   │   └── invoiceService.js
│   ├── utils/
│   │   └── validator.js
│   └── script.js
└── package.json

1. Configuración base

// config/billme.js
const config = {
  baseURL: 'https://www.api.billmeperu.com/api/v1',
  endpoints: {
    invoice: '/Emission/EnviarBoletaFactura'
  },
  token: process.env.BILLME_TOKEN || 'your-token-here'
};

export default config;

2. Servicio de facturación (¡La magia sucede aquí!)

// services/invoiceService.js
import config from '../config/billme.js';

class InvoiceService {
  constructor() {
    this.baseURL = config.baseURL;
    this.token = config.token;
  }

  /**
   * Emite una factura electrónica a SUNAT
   * @param {Object} invoiceData - Datos de la factura
   * @returns {Promise<Object>} Respuesta de SUNAT
   */
  async emitInvoice(invoiceData) {
    const url = `${this.baseURL}${config.endpoints.invoice}`;

    try {
      console.log('🚀 Emitiendo factura a SUNAT...');

      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'token': this.token,
          'Accept': 'application/json'
        },
        body: JSON.stringify(invoiceData)
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(`Error ${response.status}: ${errorData.message || 'Error desconocido'}`);
      }

      const result = await response.json();

      console.log('✅ Factura emitida exitosamente');
      console.log(`📄 Serie: ${invoiceData.serie}-${invoiceData.correlativo}`);
      console.log(`💰 Monto: S/ ${invoiceData.totales.totalPagar}`);

      return result;

    } catch (error) {
      console.error('❌ Error al emitir factura:', error.message);
      throw error;
    }
  }

  /**
   * Genera datos de factura de ejemplo
   * @returns {Object} Estructura de factura válida
   */
  generateSampleInvoice() {
    return {
      tipoOperacion: "010",
      serie: "F001", 
      correlativo: this.generateCorrelativo(),
      fechaEmision: new Date().toISOString().split('T')[0],
      horaEmision: "00:00:00",
      fechaVencimiento: new Date().toISOString().split('T')[0],
      codigoTipoOperacion: "0101",
      codigoTipoDocumento: "01",
      moneda: "PEN",
      montoCredito: 0,
      formaPago: "Contado",
      igv: 18.00,
      icbper: 0,
      cuotas: [],

      // Datos del emisor (tu empresa)
      emisor: {
        codigoTipoDocumento: "6",
        numDocumento: "20123456721",
        razonSocial: "TU EMPRESA SAC",
        nombreComercial: "TU EMPRESA",
        ubigeo: "150101", // Lima
        ciudad: "LIMA",
        distrito: "LIMA", 
        provincia: "LIMA",
        direccion: "AV. EJEMPLO 123, LIMA"
      },

      // Datos del cliente
      cliente: {
        codigoTipoDocumento: "1", // DNI
        numDocumento: "12345678",
        razonSocial: "CLIENTE EJEMPLO",
        nombreComercial: "CLIENTE EJEMPLO",
        ubigeo: "",
        ciudad: "",
        distrito: "",
        provincia: "",
        direccion: ""
      },

      // Cálculos automáticos
      totales: {
        totalOpGravadas: 100.00,
        totalOpInafectas: 0,
        totalOpExoneradas: 0,
        totalImpuestos: 18.00,
        totalSinImpuestos: 100.00,
        totalConImpuestos: 118.00,
        totalPagar: 118.00,
        totalDescuentoGlobal: 0,
        totalDescuentoProductos: 0
      },

      // Productos/servicios
      productos: [{
        unidades: 1,
        codigoUnidad: "NIU", // Unidad
        nombre: "Desarrollo de Software",
        moneda: "PEN",
        precioUnitario: 100.00,
        precioLista: "118.00",
        montoSinImpuesto: 100.00,
        montoImpuestos: 18.00,
        montoTotal: 100.00,
        montoIcbper: 0,
        factorIcbper: 0,
        montoDescuento: 0,
        codigoTipoPrecio: "01",
        impuestos: [{
          monto: 18.00,
          idCategoria: "S",
          porcentaje: 18,
          codigoAfectacionIgv: "10",
          codigoInterTributo: "VAT",
          nombreTributo: "IGV",
          codigoTributo: "1000"
        }],
        id: "DEV001",
        codigoClasificacion: "531117"
      }]
    };
  }

  /**
   * Genera correlativo único
   * @returns {string} Correlativo con formato
   */
  generateCorrelativo() {
    const timestamp = Date.now().toString().slice(-5);
    return timestamp.padStart(8, '0');
  }
}

export default InvoiceService;

3. Script principal con manejo robusto de errores

// script.js
import InvoiceService from './services/invoiceService.js';

class InvoiceApp {
  constructor() {
    this.invoiceService = new InvoiceService();
  }

  async run() {
    console.log('🏁 Iniciando proceso de facturación electrónica...\n');

    try {
      // Generar factura de ejemplo
      const invoiceData = this.invoiceService.generateSampleInvoice();

      console.log('📋 Datos de la factura:');
      console.log(`   Serie: ${invoiceData.serie}-${invoiceData.correlativo}`);
      console.log(`   Cliente: ${invoiceData.cliente.razonSocial}`);
      console.log(`   Monto: S/ ${invoiceData.totales.totalPagar}\n`);

      // Emitir factura
      const result = await this.invoiceService.emitInvoice(invoiceData);

      // Mostrar resultado
      this.displayResult(result);

    } catch (error) {
      this.handleError(error);
    }
  }

  /**
   * Muestra el resultado de la emisión
   * @param {Object} result - Respuesta de la API
   */
  displayResult(result) {
    console.log('\n🎉 ¡FACTURA EMITIDA EXITOSAMENTE!');
    console.log('═'.repeat(50));
    console.log(`📋 Número: ${result.numeroFactura || 'N/A'}`);
    console.log(`📅 Fecha: ${result.fechaEmision || 'N/A'}`);
    console.log(`🔗 Link PDF: ${result.linkPdf || 'Generando...'}`);
    console.log(`✅ Estado: ${result.estado || 'Procesado'}`);
    console.log('═'.repeat(50));
  }

  /**
   * Maneja errores de manera elegante
   * @param {Error} error - Error ocurrido
   */
  handleError(error) {
    console.log('\n❌ ERROR EN LA EMISIÓN');
    console.log('═'.repeat(50));
    console.log(`💥 Mensaje: ${error.message}`);

    // Errores comunes y soluciones
    if (error.message.includes('token')) {
      console.log('💡 Solución: Verifica tu token de Billme');
    } else if (error.message.includes('400')) {
      console.log('💡 Solución: Revisa los datos de la factura');
    } else if (error.message.includes('network') || error.message.includes('fetch')) {
      console.log('💡 Solución: Revisa tu conexión a internet');
    }

    console.log('═'.repeat(50));
  }
}

// 🚀 Ejecutar la aplicación
const app = new InvoiceApp();
app.run();

🎯 Ejecutar el código

# Instalar dependencias (si usas package.json)
npm install

# Ejecutar el script
node script.js

Resultado esperado:

🏁 Iniciando proceso de facturación electrónica...

📋 Datos de la factura:
   Serie: F001-00012345
   Cliente: CLIENTE EJEMPLO  
   Monto: S/ 118.00

🚀 Emitiendo factura a SUNAT...
✅ Factura emitida exitosamente
📄 Serie: F001-00012345
💰 Monto: S/ 118.00

🎉 ¡FACTURA EMITIDA EXITOSAMENTE!
══════════════════════════════════════════════════
📋 Número: F001-00012345
📅 Fecha: 2025-06-23
✅ Estado: Aceptado por SUNAT
══════════════════════════════════════════════════

🔥 Casos de uso avanzados

1. Facturación masiva

// Procesar múltiples facturas
const invoices = [
  { cliente: 'Cliente A', monto: 100 },
  { cliente: 'Cliente B', monto: 250 },
  { cliente: 'Cliente C', monto: 500 }
];

for (const invoice of invoices) {
  await processInvoice(invoice);
  await new Promise(resolve => setTimeout(resolve, 1000)); // Rate limiting
}

2. Integración con base de datos

// Ejemplo con MongoDB
const pendingInvoices = await Invoice.find({ status: 'pending' });

for (const invoice of pendingInvoices) {
  try {
    const result = await invoiceService.emitInvoice(invoice.data);
    await Invoice.updateOne(
      { _id: invoice._id }, 
      { status: 'emitted', sunatResponse: result }
    );
  } catch (error) {
    await Invoice.updateOne(
      { _id: invoice._id }, 
      { status: 'error', error: error.message }
    );
  }
}

3. Webhook para notificaciones

// Notificar cuando se emita una factura
app.post('/webhook/invoice-emitted', (req, res) => {
  const { invoiceId, status, pdfUrl } = req.body;

  // Enviar email al cliente
  sendEmailToClient(invoiceId, pdfUrl);

  // Actualizar sistema interno
  updateInvoiceStatus(invoiceId, status);

  res.json({ received: true });
});

⚡ Optimizaciones para producción

1. Variables de entorno

# .env
BILLME_TOKEN=your-production-token
BILLME_ENV=production
MAX_RETRIES=3
RATE_LIMIT_MS=1000

2. Rate limiting y reintentos

class RobustInvoiceService extends InvoiceService {
  async emitInvoiceWithRetry(invoiceData, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await this.emitInvoice(invoiceData);
      } catch (error) {
        if (attempt === maxRetries) throw error;

        console.log(`⚠️ Intento ${attempt} falló, reintentando...`);
        await this.delay(1000 * attempt); // Backoff exponencial
      }
    }
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

🎯 Próximos pasos

Una vez que domines lo básico, puedes expandir tu sistema:

📧 Envío automático de facturas por email
📊 Dashboard de reportes y analytics
🔄 Sincronización con sistemas contables
📱 API REST para tu frontend
🤖 Chatbot para consulta de facturas

🤝 Conclusión

¡Felicidades! Acabas de automatizar uno de los procesos más tediosos para cualquier developer peruano. Con este setup puedes:

✅ Emitir facturas desde cualquier aplicación

✅ Integrar con tus sistemas existentes

✅ Escalar sin límites (casi)

✅ Olvidarte de procesos manuales

¿Qué sigue? Te reto a integrar esto en tu próximo project. Las posibilidades son infinitas.

💬 ¿Te funcionó?

Si implementaste este tutorial:

👍 Dale like si te sirvió
💬 Comparte tu experiencia en los comentarios
🔄 Compártelo con otros devs que necesiten esto
🐙 Sube tu versión a GitHub y comparte el repo

¿Tienes dudas? Comenta abajo y te ayudo a resolverlas.

📚 Referencias útiles

Tags: #nodejs #javascript #sunat #facturacion #api #peru #automation #fintech

🧾 Cómo Automatizar la Facturación Electrónica SUNAT en 5 Minutos con Python

Luis Dev — Sun, 22 Jun 2025 17:47:01 +0000

¿Sabías que puedes enviar facturas directamente a SUNAT con solo 20 líneas de código Python? En este tutorial aprenderás a crear un sistema completo de facturación electrónica que ahorrará horas de trabajo manual a tu empresa.

🇵🇪 ¿Por qué la Facturación Electrónica es Obligatoria en Perú?

Desde 2010, SUNAT ha implementado gradualmente la facturación electrónica obligatoria para diferentes tipos de empresas. Si tu empresa tiene ingresos anuales superiores a 150 UIT, debes emitir comprobantes electrónicos.

📊 Beneficios de Automatizar tu Facturación:

⚡ 95% menos tiempo en emisión de comprobantes
🔒 100% cumplimiento normativo con SUNAT
💰 Ahorro de costos en papel y almacenamiento
📈 Mejor control de inventarios y finanzas
🚀 Integración directa con tu sistema existente

🛠️ Arquitectura de la Solución

┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│   Tu Sistema    │───▶│  BillMe API  │───▶│    SUNAT    │
│    (Python)     │    │  (Gateway)   │    │ (Oficial)   │
└─────────────────┘    └──────────────┘    └─────────────┘

Usaremos BillMe como gateway porque:

✅ Certificado por SUNAT
✅ API REST simple
✅ Manejo automático de XML y validaciones
✅ Entorno de pruebas gratuito

🚀 Setup Inicial: Creando tu Cuenta de Prueba

Paso 1: Registro en BillMe

Ve a billmeperu.com
Crea una cuenta gratuita
Sigue la documentación oficial

Paso 2: Crear Empresa de Prueba

1. Login → Empresas → Agregar
2. Completa datos ficticios para testing
3. Copia el token de la empresa 🔑

💻 Implementación en Python

📦 Dependencias Necesarias

pip install requests python-dotenv

🔧 Estructura del Proyecto

facturacion_sunat/
├── .env                 # Variables de entorno
├── main.py             # Script principal
├── config.py           # Configuración
├── models.py           # Modelos de datos
└── billme_client.py    # Cliente API

🗂️ Código Principal

# main.py - Sistema completo de facturación electrónica
import os
import requests
import json
from datetime import datetime, date
from typing import Dict, List, Optional
from dataclasses import dataclass, asdict
from dotenv import load_dotenv

# Cargar variables de entorno
load_dotenv()

@dataclass
class Emisor:
    """Datos del emisor (tu empresa)"""
    codigo_tipo_documento: str = "6"  # RUC
    num_documento: str = ""
    razon_social: str = ""
    nombre_comercial: str = ""
    ubigeo: str = ""
    ciudad: str = ""
    distrito: str = ""
    provincia: str = ""
    direccion: str = ""

@dataclass
class Cliente:
    """Datos del cliente"""
    codigo_tipo_documento: str  # 1=DNI, 6=RUC
    num_documento: str
    razon_social: str
    nombre_comercial: str = ""
    ubigeo: str = ""
    ciudad: str = ""
    distrito: str = ""
    provincia: str = ""
    direccion: str = ""

@dataclass
class Impuesto:
    """Estructura de impuestos (IGV, ISC, etc.)"""
    monto: float
    id_categoria: str = "S"  # S=Sujeto, E=Exonerado, I=Inafecto
    porcentaje: float = 18.0
    codigo_afectacion_igv: str = "10"
    codigo_inter_tributo: str = "VAT"
    nombre_tributo: str = "IGV"
    codigo_tributo: str = "1000"

@dataclass
class Producto:
    """Producto o servicio a facturar"""
    unidades: float
    codigo_unidad: str = "NIU"  # Unidad de medida
    nombre: str = ""
    moneda: str = "PEN"
    precio_unitario: float = 0.0
    precio_lista: str = "0.00"
    monto_sin_impuesto: float = 0.0
    monto_impuestos: float = 0.0
    monto_total: float = 0.0
    monto_icbper: float = 0.0
    factor_icbper: float = 0.0
    monto_descuento: float = 0.0
    codigo_tipo_precio: str = "01"
    impuestos: List[Impuesto] = None
    id: str = ""
    codigo_clasificacion: str = ""

    def __post_init__(self):
        if self.impuestos is None:
            # Calcular IGV automáticamente
            igv_monto = round(self.precio_unitario * 0.18, 2)
            self.monto_sin_impuesto = self.precio_unitario
            self.monto_impuestos = igv_monto
            self.monto_total = self.precio_unitario
            self.precio_lista = f"{self.precio_unitario + igv_monto:.2f}"

            self.impuestos = [Impuesto(
                monto=igv_monto,
                porcentaje=18.0
            )]

@dataclass
class Totales:
    """Totales de la factura"""
    total_op_gravadas: float = 0.0
    total_op_inafectas: float = 0.0
    total_op_exoneradas: float = 0.0
    total_impuestos: float = 0.0
    total_sin_impuestos: float = 0.0
    total_con_impuestos: float = 0.0
    total_pagar: float = 0.0
    total_descuento_global: float = 0.0
    total_descuento_productos: float = 0.0

class FacturacionSUNAT:
    """Cliente principal para facturación electrónica"""

    def __init__(self, token: str, base_url: str = None):
        self.token = token
        self.base_url = base_url or "https://www.api.billmeperu.com/api/v1"
        self.session = requests.Session()
        self.session.headers.update({
            'Content-Type': 'application/json',
            'token': self.token,
            'Accept': 'application/json'
        })

    def _calcular_totales(self, productos: List[Producto]) -> Totales:
        """Calcula automáticamente los totales de la factura"""
        total_sin_impuestos = sum(p.monto_sin_impuesto * p.unidades for p in productos)
        total_impuestos = sum(p.monto_impuestos * p.unidades for p in productos)

        return Totales(
            total_op_gravadas=total_sin_impuestos,
            total_impuestos=total_impuestos,
            total_sin_impuestos=total_sin_impuestos,
            total_con_impuestos=total_sin_impuestos + total_impuestos,
            total_pagar=total_sin_impuestos + total_impuestos
        )

    def emitir_factura(
        self,
        serie: str,
        correlativo: str,
        emisor: Emisor,
        cliente: Cliente,
        productos: List[Producto],
        fecha_emision: date = None,
        forma_pago: str = "Contado"
    ) -> Dict:
        """
        Emite una factura electrónica a SUNAT

        Args:
            serie: Serie de la factura (ej: F001)
            correlativo: Correlativo (ej: 00000123)
            emisor: Datos de tu empresa
            cliente: Datos del cliente
            productos: Lista de productos/servicios
            fecha_emision: Fecha de emisión (hoy por defecto)
            forma_pago: Forma de pago

        Returns:
            Respuesta de la API con el resultado
        """
        if fecha_emision is None:
            fecha_emision = date.today()

        # Calcular totales automáticamente
        totales = self._calcular_totales(productos)

        # Construir payload
        data = {
            "tipoOperacion": "010",
            "serie": serie,
            "correlativo": correlativo,
            "fechaEmision": fecha_emision.strftime("%Y-%m-%d"),
            "horaEmision": datetime.now().strftime("%H:%M:%S"),
            "fechaVencimiento": fecha_emision.strftime("%Y-%m-%d"),
            "codigoTipoOperacion": "0101",
            "codigoTipoDocumento": "01",  # Factura
            "moneda": "PEN",
            "montoCredito": 0,
            "formaPago": forma_pago,
            "igv": totales.total_impuestos,
            "icbper": 0,
            "cuotas": [],
            "emisor": asdict(emisor),
            "cliente": asdict(cliente),
            "totales": asdict(totales),
            "productos": [asdict(p) for p in productos]
        }

        return self._enviar_comprobante(data)

    def emitir_boleta(
        self,
        serie: str,
        correlativo: str,
        emisor: Emisor,
        cliente: Cliente,
        productos: List[Producto],
        fecha_emision: date = None
    ) -> Dict:
        """Emite una boleta de venta electrónica"""
        # Similar a factura pero con código de documento "03"
        data = self._construir_payload_boleta(serie, correlativo, emisor, cliente, productos, fecha_emision)
        return self._enviar_comprobante(data)

    def _enviar_comprobante(self, data: Dict) -> Dict:
        """Envía el comprobante a la API de BillMe"""
        url = f"{self.base_url}/Emission/EnviarBoletaFactura"

        try:
            print(f"🚀 Enviando comprobante {data['serie']}-{data['correlativo']}...")

            response = self.session.post(url, json=data, timeout=30)
            response.raise_for_status()

            result = response.json()

            if response.status_code == 200:
                print("✅ Comprobante enviado exitosamente!")
                print(f"📄 Número: {data['serie']}-{data['correlativo']}")
                print(f"💰 Total: S/ {data['totales']['totalPagar']}")

            return result

        except requests.exceptions.Timeout:
            raise Exception("⏰ Timeout: La API tardó mucho en responder")
        except requests.exceptions.HTTPError as e:
            if response.status_code == 401:
                raise Exception("🔐 Token inválido o expirado")
            elif response.status_code == 400:
                raise Exception(f"📋 Datos inválidos: {response.text}")
            else:
                raise Exception(f"❌ Error HTTP {response.status_code}: {response.text}")
        except requests.exceptions.RequestException as e:
            raise Exception(f"🌐 Error de conexión: {str(e)}")

# Ejemplos de uso prácticos
def ejemplo_factura_simple():
    """Ejemplo 1: Factura simple para servicios"""

    # Configurar cliente
    token = os.getenv('BILLME_TOKEN', 'tu-token-aqui')
    cliente_api = FacturacionSUNAT(token)

    # Datos del emisor (tu empresa)
    mi_empresa = Emisor(
        num_documento="20123456789",
        razon_social="MI EMPRESA SAC",
        nombre_comercial="MI EMPRESA",
        ubigeo="150101",
        ciudad="LIMA",
        distrito="LIMA",
        provincia="LIMA",
        direccion="AV. PRINCIPAL 123"
    )

    # Datos del cliente
    cliente = Cliente(
        codigo_tipo_documento="1",  # DNI
        num_documento="12345678",
        razon_social="JUAN PÉREZ LÓPEZ"
    )

    # Producto/servicio
    productos = [
        Producto(
            unidades=1,
            nombre="Desarrollo de Sistema Web",
            precio_unitario=1000.00,
            id="SERV001"
        )
    ]

    # Emitir factura
    try:
        resultado = cliente_api.emitir_factura(
            serie="F001",
            correlativo="00000123",
            emisor=mi_empresa,
            cliente=cliente,
            productos=productos
        )

        print("🎉 Factura emitida exitosamente!")
        return resultado

    except Exception as e:
        print(f"❌ Error: {e}")
        return None

def ejemplo_factura_multiple_productos():
    """Ejemplo 2: Factura con múltiples productos"""

    token = os.getenv('BILLME_TOKEN')
    cliente_api = FacturacionSUNAT(token)

    # Múltiples productos
    productos = [
        Producto(
            unidades=2,
            nombre="Laptop Dell Inspiron",
            precio_unitario=1500.00,
            id="LAP001"
        ),
        Producto(
            unidades=1,
            nombre="Mouse Inalámbrico",
            precio_unitario=50.00,
            id="MOU001"
        ),
        Producto(
            unidades=3,
            nombre="Cable HDMI",
            precio_unitario=25.00,
            id="CAB001"
        )
    ]

    # ... resto del código similar

def ejemplo_integracion_base_datos():
    """Ejemplo 3: Integración con base de datos"""

    # Simulación de datos desde BD
    pedidos_pendientes = [
        {
            'id': 1001,
            'cliente_ruc': '20567890123',
            'cliente_nombre': 'EMPRESA CLIENTE SAC',
            'productos': [
                {'nombre': 'Servicio de Consultoría', 'precio': 2000.00, 'cantidad': 1}
            ]
        }
    ]

    cliente_api = FacturacionSUNAT(os.getenv('BILLME_TOKEN'))

    for pedido in pedidos_pendientes:
        # Convertir datos de BD a objetos del sistema
        cliente = Cliente(
            codigo_tipo_documento="6",  # RUC
            num_documento=pedido['cliente_ruc'],
            razon_social=pedido['cliente_nombre']
        )

        productos = [
            Producto(
                unidades=item['cantidad'],
                nombre=item['nombre'],
                precio_unitario=item['precio']
            ) for item in pedido['productos']
        ]

        # Emitir factura automáticamente
        try:
            resultado = cliente_api.emitir_factura(
                serie="F001",
                correlativo=f"{pedido['id']:08d}",
                emisor=mi_empresa,  # Definir globalmente
                cliente=cliente,
                productos=productos
            )
            print(f"✅ Pedido {pedido['id']} facturado exitosamente")

        except Exception as e:
            print(f"❌ Error en pedido {pedido['id']}: {e}")

if __name__ == "__main__":
    print("🧾 Sistema de Facturación Electrónica SUNAT")
    print("=" * 50)

    # Verificar token
    if not os.getenv('BILLME_TOKEN'):
        print("⚠️  Configura tu BILLME_TOKEN en el archivo .env")
        exit(1)

    # Ejecutar ejemplos
    print("\n1️⃣ Ejemplo: Factura Simple")
    ejemplo_factura_simple()

    print("\n2️⃣ Ejemplo: Factura Múltiples Productos")
    # ejemplo_factura_multiple_productos()

    print("\n3️⃣ Ejemplo: Integración con Base de Datos")
    # ejemplo_integracion_base_datos()

📁 Archivo de Configuración

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    BILLME_TOKEN = os.getenv('BILLME_TOKEN')
    BILLME_API_URL = os.getenv('BILLME_API_URL', 'https://www.api.billmeperu.com/api/v1')

    # Configuración de empresa por defecto
    EMPRESA_RUC = os.getenv('EMPRESA_RUC')
    EMPRESA_RAZON_SOCIAL = os.getenv('EMPRESA_RAZON_SOCIAL')

    # Validaciones
    @classmethod
    def validate(cls):
        if not cls.BILLME_TOKEN:
            raise ValueError("❌ BILLME_TOKEN es requerido")
        if not cls.EMPRESA_RUC:
            raise ValueError("❌ EMPRESA_RUC es requerido")

🔐 Archivo .env

# Variables de entorno
BILLME_TOKEN=tu-token-real-de-billme
BILLME_API_URL=https://www.api.billmeperu.com/api/v1

# Datos de tu empresa
EMPRESA_RUC=20123456789
EMPRESA_RAZON_SOCIAL=MI EMPRESA SAC
EMPRESA_DIRECCION=AV. PRINCIPAL 123, LIMA

🚀 Ejecución

# Instalar dependencias
pip install requests python-dotenv

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus datos reales

# Ejecutar
python main.py

📊 Casos de Uso Avanzados

🔄 Automatización Completa

# scheduler.py - Automatizar facturación diaria
import schedule
import time
from main import FacturacionSUNAT, ejemplo_integracion_base_datos

def facturar_pedidos_pendientes():
    """Ejecutar facturación automática cada día"""
    print("🕐 Iniciando facturación automática...")
    ejemplo_integracion_base_datos()

# Programar ejecución diaria a las 9:00 AM
schedule.every().day.at("09:00").do(facturar_pedidos_pendientes)

while True:
    schedule.run_pending()
    time.sleep(60)

📈 Dashboard de Facturación

# dashboard.py - Métricas de facturación
import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime, timedelta

class DashboardFacturacion:
    def __init__(self, cliente_api):
        self.cliente = cliente_api
        self.facturas_emitidas = []

    def generar_reporte_mensual(self):
        """Genera reporte de facturación mensual"""
        df = pd.DataFrame(self.facturas_emitidas)

        # Métricas clave
        total_facturado = df['total'].sum()
        cantidad_facturas = len(df)
        promedio_factura = df['total'].mean()

        print(f"📊 REPORTE MENSUAL DE FACTURACIÓN")
        print(f"💰 Total Facturado: S/ {total_facturado:,.2f}")
        print(f"📄 Facturas Emitidas: {cantidad_facturas}")
        print(f"📈 Promedio por Factura: S/ {promedio_factura:,.2f}")

        return {
            'total_facturado': total_facturado,
            'cantidad_facturas': cantidad_facturas,
            'promedio_factura': promedio_factura
        }

🛡️ Mejores Prácticas de Seguridad

1. 🔐 Manejo Seguro de Tokens

# ❌ MAL: Token hardcodeado
token = "abc123"

# ✅ BIEN: Token desde variable de entorno
token = os.getenv('BILLME_TOKEN')

2. 🚨 Validación de Datos

def validar_ruc(ruc: str) -> bool:
    """Valida formato de RUC peruano"""
    if len(ruc) != 11 or not ruc.isdigit():
        return False

    # Algoritmo de validación RUC SUNAT
    factor = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2]
    suma = sum(int(ruc[i]) * factor[i] for i in range(10))
    digito = (11 - (suma % 11)) % 11

    return digito == int(ruc[10])

3. 📝 Logging y Auditoría

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('facturacion.log'),
        logging.StreamHandler()
    ]
)

def log_factura_emitida(serie, correlativo, total):
    logging.info(f"Factura emitida: {serie}-{correlativo} por S/ {total}")

⚡ Optimizaciones de Performance

1. 🔄 Pool de Conexiones

from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry_strategy = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("http://", adapter)
session.mount("https://", adapter)

2. ⚡ Procesamiento Asíncrono

import asyncio
import aiohttp

async def emitir_facturas_lote(facturas):
    """Emite múltiples facturas en paralelo"""
    async with aiohttp.ClientSession() as session:
        tasks = [
            emitir_factura_async(session, factura) 
            for factura in facturas
        ]
        return await asyncio.gather(*tasks)

🎯 Conclusión

Con este sistema en Python has logrado:

✅ Automatizar completamente la facturación electrónica
✅ Reducir errores humanos en el proceso
✅ Cumplir normativas SUNAT automáticamente
✅ Integrar fácilmente con sistemas existentes
✅ Escalar para miles de facturas diarias

🚀 Próximos Pasos

Integrar con tu ERP/CRM existente
Implementar webhooks para notificaciones
Crear dashboard web con Flask/Django
Añadir más tipos de comprobantes (notas de crédito, etc.)
Implementar facturación recurrente

🤝 ¿Te Gustó Este Tutorial?

👏 Dale like si te fue útil
💬 Comenta tus casos de uso
🔄 Comparte con otros desarrolladores
⭐ Sígueme para más tutoriales de Python

Happy Coding! 🐍✨

¿Tienes dudas o quieres que cubra algún tema específico? ¡Déjame un comentario!

Cómo emitir comprobantes de pago a SUNAT con NodeJS

Luis Dev — Sat, 21 Jun 2025 01:34:17 +0000

En este post vamos a crear un pequeño script que pueda emitir facturas usando una API que recibe un JSON con los datos de la factura y la registre directamente en SUNAT. Para eso usaremos Billme que nos permitirá emitir la factura mediante una simple petición POST usando su API.

Creación de una empresa de prueba

Primero crearemos una cuenta gratuita en Billme para poder obtener el token que nos permitirá hacer el código de prueba. Para esto seguiremos la guía de su documentación.

Luego de tener una cuenta registraremos una empresa de prueba para poder obtener el token que nos permitirá usar su sandbox y probar la emisión en un entorno de prueba. Para esto dentro de la plataforma de Billme nos dirigimos a la opción de Empresas > Agregar. Completamos los datos requeridos y tendremos lista nuestra empresa de prueba. Ahora podemos hacer click en el siguiente ícono
para poder ver el token que nos permitirá comunicarnos con la API.

Factura de ejemplo

Para este ejemplo simularemos una factura con los siguientes datos:

Cantidad de productos: 1
Tipo: Factura
Serie: F001
Correlativo: 00321
Moneda: PEN
Tipo Pago: Contado
Monto: 100
Aplica IGV: Sí

Desarrollo del script

Para el script utilizaremos NodeJS con JavaScript. Utilizaremos la librería de fetch para realizar la petición HTTP. Nos ubicamos en una carpeta donde tendremos nuestro script y creamos el archivo llamado script.js.

// Función que realiza la petición hacia la API
async function sendBillingToBillme() {
  const url = "https://www.api.billmeperu.com/api/v1/Emission/EnviarBoletaFactura";
  const token = 'tu-token-aqui';

  const data = {
   "tipoOperacion":"010",
   "serie":"F001",
   "correlativo":"00321",
   "fechaEmision":"2025-06-20",
   "horaEmision":"00:00:00",
   "fechaVencimiento":"2025-06-20",
   "codigoTipoOperacion":"0101",
   "codigoTipoDocumento":"01",
   "moneda":"PEN",
   "montoCredito":0,
   "formaPago":"Contado",
   "igv":15.25,
   "icbper":0,
   "cuotas":[],
   "emisor":{
      "codigoTipoDocumento":"6",
      "numDocumento":"20123456721",
      "razonSocial":"EMISOR SAC",
      "nombreComercial":"EMISOR SAC",
      "ubigeo":"200610",
      "ciudad":"PIURA",
      "distrito":"PIURA",
      "provincia":"PIURA",
      "direccion":"DIRECCION EJEMPLO, CALLE 1"
   },
   "cliente":{
      "codigoTipoDocumento":"1",
      "numDocumento":"72314572",
      "razonSocial":"RAZON SOCIAL CLIENTE",
      "nombreComercial":"NOMBRE COMERCIAL CLIENTE",
      "ubigeo":"",
      "ciudad":"",
      "distrito":"",
      "provincia":"",
      "direccion":""
   },
   "totales":{
      "totalOpGravadas":84.75,
      "totalOpInafectas":0,
      "totalOpExoneradas":0,
      "totalImpuestos":15.25,
      "totalSinImpuestos":84.75,
      "totalConImpuestos":100,
      "totalPagar":100,
      "totalDescuentoGlobal":0,
      "totalDescuentoProductos":0
   },
   "productos":[
      {
         "unidades":1,
         "codigoUnidad":"NIU",
         "nombre":"Zapatillas fútbol",
         "moneda":"PEN",
         "precioUnitario":84.75,
         "precioLista":"100.00",
         "montoSinImpuesto":84.75,
         "montoImpuestos":15.25,
         "montoTotal":84.75,
         "montoIcbper":0,
         "factorIcbper":0,
         "montoDescuento":0,
         "codigoTipoPrecio":"01",
         "impuestos":[
            {
               "monto":15.25,
               "idCategoria":"S",
               "porcentaje":18,
               "codigoAfectacionIgv":"10",
               "codigoInterTributo":"VAT",
               "nombreTributo":"IGV",
               "codigoTributo":"1000"
            }
         ],
         "id":"Z001",
         "codigoClasificacion":"531117"
      }
   ]
};

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'token': token,
        'Accept': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    console.log('Respuesta de la emisión:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

Ahora crearemos la función principal de nuestro script que invocará a la función que envía la factura usando Billme.

async function main() {  
  // Enviar la factura
  console.log('Emitiendo factura...');
  await sendBillingToBillme();
}

// Ejecutar el script
if (require.main === module) {
  main();
}

Luego, desde la consola nos colocamos en la ruta donde tenemos nuestro script y ejecutamos el siguiente comando: node script.js

Finalmente, con esto veremos por consola el resultado del envío de nuestra factura. El código de nuestro script luciría así:

// Función que realiza la petición hacia la API
async function sendBillingToBillme() {
  const url = "https://www.api.billmeperu.com/api/v1/Emission/EnviarBoletaFactura";
  const token = 'tu-token-aqui';

  const data = {
   "tipoOperacion":"010",
   "serie":"F001",
   "correlativo":"00321",
   "fechaEmision":"2025-06-20",
   "horaEmision":"00:00:00",
   "fechaVencimiento":"2025-06-20",
   "codigoTipoOperacion":"0101",
   "codigoTipoDocumento":"01",
   "moneda":"PEN",
   "montoCredito":0,
   "formaPago":"Contado",
   "igv":15.25,
   "icbper":0,
   "cuotas":[],
   "emisor":{
      "codigoTipoDocumento":"6",
      "numDocumento":"20123456721",
      "razonSocial":"EMISOR SAC",
      "nombreComercial":"EMISOR SAC",
      "ubigeo":"200610",
      "ciudad":"PIURA",
      "distrito":"PIURA",
      "provincia":"PIURA",
      "direccion":"DIRECCION EJEMPLO, CALLE 1"
   },
   "cliente":{
      "codigoTipoDocumento":"1",
      "numDocumento":"72314572",
      "razonSocial":"RAZON SOCIAL CLIENTE",
      "nombreComercial":"NOMBRE COMERCIAL CLIENTE",
      "ubigeo":"",
      "ciudad":"",
      "distrito":"",
      "provincia":"",
      "direccion":""
   },
   "totales":{
      "totalOpGravadas":84.75,
      "totalOpInafectas":0,
      "totalOpExoneradas":0,
      "totalImpuestos":15.25,
      "totalSinImpuestos":84.75,
      "totalConImpuestos":100,
      "totalPagar":100,
      "totalDescuentoGlobal":0,
      "totalDescuentoProductos":0
   },
   "productos":[
      {
         "unidades":1,
         "codigoUnidad":"NIU",
         "nombre":"Zapatillas fútbol",
         "moneda":"PEN",
         "precioUnitario":84.75,
         "precioLista":"100.00",
         "montoSinImpuesto":84.75,
         "montoImpuestos":15.25,
         "montoTotal":84.75,
         "montoIcbper":0,
         "factorIcbper":0,
         "montoDescuento":0,
         "codigoTipoPrecio":"01",
         "impuestos":[
            {
               "monto":15.25,
               "idCategoria":"S",
               "porcentaje":18,
               "codigoAfectacionIgv":"10",
               "codigoInterTributo":"VAT",
               "nombreTributo":"IGV",
               "codigoTributo":"1000"
            }
         ],
         "id":"Z001",
         "codigoClasificacion":"531117"
      }
   ]
};

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'token': token,
        'Accept': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    console.log('Respuesta de la emisión:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

async function main() {  
  // Enviar la factura
  console.log('Emitiendo factura...');
  await sendBillingToBillme();
}

// Ejecutar el script
if (require.main === module) {
  main();
}

Listo! Con este script de ejemplo puedes hacer pruebas y luego integrarlo a tus sistemas para que puedas emitir tus comprobantes electrónicos usando sólo una API. Happy coding ;)