Factuplan

SDK oficial de Factuplan para JavaScript y TypeScript. Emite facturas electronicas en Ecuador (SRI) desde tu aplicacion.

Instalacion

npm install factuplan

Inicio rapido

import { Factuplan } from 'factuplan';

const factuplan = new Factuplan('tu-api-key');

// Crear una factura
const invoice = await factuplan.invoices.create({
  emissionPointId: 'ep_...',
  customer: {
    identificationType: 'RUC',
    identification: '1790016919001',
    legalName: 'Empresa ABC S.A.',
    email: '[email protected]',
  },
  items: [
    {
      code: 'SERV-001',
      description: 'Servicio de consultoria',
      quantity: 1,
      unitPrice: 100.00,
      taxType: 'IVA_RATE',
    },
  ],
});

console.log(invoice.accessKey); // Clave de acceso SRI

Recursos

Clientes

// Crear cliente
const customer = await factuplan.customers.create({
  identificationType: 'RUC',
  identification: '1790016919001',
  legalName: 'Empresa ABC S.A.',
  email: '[email protected]',
});

// Listar clientes (paginado)
const { data, meta } = await factuplan.customers.list({ page: 1, limit: 20 });

// Obtener cliente por ID
const customer = await factuplan.customers.get('customer-id');

// Actualizar cliente
await factuplan.customers.update('customer-id', { phone: '0991234567' });

// Eliminar cliente
await factuplan.customers.delete('customer-id');

Productos

// Crear producto
const product = await factuplan.products.create({
  code: 'PROD-001',
  name: 'Laptop Dell XPS',
  unitPrice: 1200.00,
  taxType: 'IVA_RATE',
  type: 'PRODUCT',
});

// Listar productos (paginado)
const { data, meta } = await factuplan.products.list({ page: 1, limit: 20 });

// Obtener producto por ID
const product = await factuplan.products.get('product-id');

// Actualizar producto
await factuplan.products.update('product-id', { unitPrice: 1150.00 });

// Eliminar producto
await factuplan.products.delete('product-id');

Facturas

// Crear factura
const invoice = await factuplan.invoices.create({
  emissionPointId: 'ep_...',
  customer: {
    identificationType: 'CEDULA',
    identification: '1712345678',
    legalName: 'Juan Perez',
    email: '[email protected]',
    saveToContacts: true,
  },
  items: [
    {
      code: 'SERV-001',
      description: 'Desarrollo web',
      quantity: 10,
      unitPrice: 50.00,
      discount: 25.00,
      taxType: 'IVA_RATE',
    },
  ],
  paymentMethod: 'TRANSFER',
  additionalInfo: {
    'Orden de compra': 'OC-2024-001',
  },
});

// Consultar estado
const status = await factuplan.invoices.getStatus('invoice-id');
console.log(status.status); // 'AUTHORIZED', 'PENDING', etc.

// Descargar XML autorizado
const { url } = await factuplan.invoices.downloadXml('invoice-id');

// Descargar PDF (RIDE)
const { url } = await factuplan.invoices.downloadPdf('invoice-id');

Importar factura ya autorizada por el SRI

Si tienes una factura que ya fue autorizada directamente por el SRI (no a través de Factuplan), puedes importarla para almacenarla en tu cuenta y generar el PDF (RIDE):

const result = await factuplan.invoices.importByAccessKey({
  accessKey: '1512202501095019440700120010020000000116488711218',
});

console.log(result.id);         // ID interno del comprobante
console.log(result.accessKey);  // Clave de acceso SRI
console.log(result.sequential); // Número secuencial
console.log(result.status);     // 'AUTHORIZED'
console.log(result.total);      // Total del comprobante

// El PDF se genera automáticamente. Descárgalo una vez listo:
const { url } = await factuplan.invoices.downloadPdf(result.id);

Nota: Este método no envía el comprobante al SRI ni envía correo al cliente. Solo importa y genera el PDF.

Firmar y autorizar XML (Modo B)

Si ya tienes tu XML generado (sin firmar), puedes enviarlo para que Factuplan lo firme con tu certificado y lo autorice ante el SRI:

import { readFileSync } from 'fs';

// Leer XML sin firmar
const xml = readFileSync('./factura.xml', 'utf-8');

// Firmar y autorizar
const result = await factuplan.invoices.signAndAuthorize({ xml });

console.log(result.accessKey); // Clave de acceso SRI
console.log(result.status);    // Estado del comprobante

// Consultar estado de autorizacion
const status = await factuplan.invoices.getStatus(result.id);

// Descargar XML autorizado
const { url } = await factuplan.invoices.downloadXml(result.id);

Solo firmar XML (Modo C)

Firma el XML con tu certificado sin enviarlo al SRI:

const { signedXml } = await factuplan.invoices.signOnly({ xml });

Validar XML

Valida la estructura de un XML sin procesarlo:

const { valid, errors } = await factuplan.invoices.validateXml({ xml });
if (!valid) {
  console.log('Errores:', errors);
}

Verificar autorizacion

Consulta el estado de autorizacion de un comprobante por su clave de acceso:

const result = await factuplan.invoices.verify('0104202601099337815000110010010000000011234567890');
console.log(result.authorized);           // true/false
console.log(result.authorizationNumber);   // Numero de autorizacion

Uso y certificado

// Consultar uso de la API
const usage = await factuplan.usage();
console.log(`${usage.used}/${usage.quota} facturas este mes`);

// Estado del certificado de firma
const cert = await factuplan.certificateStatus();
console.log(`Expira en ${cert.daysUntilExpiry} dias`);

Configuracion

const factuplan = new Factuplan('tu-api-key', {
  baseUrl: 'https://api-rest.factuplan.com.ec/api/v1', // default
  timeout: 30000, // 30s default
});

Manejo de errores

import { Factuplan, FactuplanError, AuthenticationError, RateLimitError } from 'factuplan';

try {
  await factuplan.invoices.create({ /* ... */ });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // API key invalida (401)
  } else if (error instanceof RateLimitError) {
    // Limite de peticiones excedido (429)
  } else if (error instanceof FactuplanError) {
    console.error(error.message);    // Mensaje de error
    console.error(error.statusCode); // Codigo HTTP
    console.error(error.code);       // Codigo de error interno
    console.error(error.details);    // Detalles adicionales
  }
}

Tipos de identificacion

| Tipo | Descripcion | |------|-------------| | RUC | Registro Unico de Contribuyentes (13 digitos) | | CEDULA | Cedula de identidad (10 digitos) | | PASSPORT | Pasaporte | | FINAL_CONSUMER | Consumidor final (9999999999999) |

Tipos de impuesto

| Tipo | Descripcion | |------|-------------| | IVA_RATE | IVA 15% (tarifa vigente) | | IVA_0 | IVA 0% | | NOT_TAXABLE | No objeto de impuesto | | EXEMPT | Exento de IVA |

Requisitos

• Node.js 18+ (usa fetch nativo)
• API key de Factuplan

Licencia

MIT