Factuplan: Facturación Electrónica con su API y SDK en TypeScript

La facturación electrónica puede ser un proceso complejo a nivel de cumplimiento y validación tributaria. Factuplan simplifica enormemente este flujo ofreciendo una API REST moderna y robusta que te permite emitir comprobantes electrónicos de forma rápida, segura y validada directamente desde tu propio sistema SaaS o E-commerce.

La Evolución de Factuplan: De un Sistema Completo a una API Especializada

Factuplan ha pasado por dos versiones principales. La primera versión fue construida junto con refine.dev. El problema con refine.dev era que tenía una plantilla a la cual nos teníamos que adaptar mucho, lo que resultó en un formato no muy usable para el usuario final. Además, en esa versión manejábamos el control del inventario, y descubrimos que muchos de nuestros clientes no necesitaban ni usaban esa funcionalidad.

En la versión actual, decidimos simplificar y enfocarnos en el núcleo del negocio. Solo dejamos Factuplan para generar facturas electrónicas, notas de crédito y guías de remisión. Para la creación y refactorización de esta nueva arquitectura (V2), utilizamos intensivamente Claude (IA generativa), lo cual nos permitió acelerar drásticamente el ciclo de desarrollo. Al finalizar, abrimos una API para nuestros clientes que deseen crear sus propias aplicaciones (como gestión de inventario, e-commerce, etc.) de modo que solo tengan que conectarse para emitir las facturas.

El Poder del SDK Oficial para JavaScript y TypeScript

Para los desarrolladores modernos, interactuar con APIs directamente mediante peticiones HTTP en crudo puede volverse tedioso y propenso a errores de formato. Una de las mayores ventajas de Factuplan es que cuenta con un SDK oficial diseñado nativamente para el ecosistema de JS/TS, el cual se puede descargar e instalar directamente desde npm. Para comenzar a utilizarlo y conectarse a la API de emisión de facturas, los clientes únicamente necesitan generar su propia API KEY. Esto agiliza la integración en entornos como Node.js, NestJS, Express o incluso en funciones Serverless como AWS Lambda o Vercel Functions.

import { Factuplan } from '@factuplan/sdk';

// Inicializamos el cliente de Factuplan de forma segura
const factuplan = new Factuplan({
  apiKey: process.env.FACTUPLAN_API_KEY,
  environment: 'sandbox' // O 'production' según el entorno
});

export async function emitirComprobante() {
  try {
    // Creación de la factura con fuerte tipado
    const factura = await factuplan.invoices.create({
      customer: {
        identification: '0999999999001',
        identificationType: 'RUC',
        name: 'Cliente Corporativo S.A.',
        email: 'contabilidad@cliente.com'
      },
      items: [
        {
          description: 'Suscripción Anual Plataforma SaaS',
          quantity: 1,
          unitPrice: 120.00,
          taxes: [
            { type: 'IVA', percentage: 15 }
          ]
        }
      ],
      paymentMethods: [
        { code: 'TARJETA_CREDITO', amount: 138.00 }
      ]
    });
    
    console.log('✅ Factura autorizada por el SRI:', factura.accessKey);
    return factura;
  } catch (error) {
    console.error('❌ Error al emitir la factura:', error);
    throw error;
  }
}