Factuplan SDK

const cliente = await factuplan.customers.create({
  identificationType: 'RUC',          // RUC | CEDULA | PASSPORT | FINAL_CONSUMER | EXTERIOR
  identification: '0000000000001',    // RUC=13 dígitos | CEDULA=10 dígitos
  legalName: 'Empresa Demo S.A.',
  email: 'contacto@empresa.com',      // opcional: sin correo no se le envía nada
  address: 'Guayaquil, Ecuador',      // opcional
  phone: '+593000000000',             // opcional — ej. +593 EC, +1 US, +44 UK
});

const { data: clientes, meta } = await factuplan.customers.list({
  page: 1,
  limit: 20,
  search: 'empresa',
});
console.log(meta.total, 'clientes encontrados');

const cliente = await factuplan.customers.get('id');

await factuplan.customers.update('id', { email: 'nuevo@email.com' });

await factuplan.customers.delete('id'); // no lo borra: lo desactiva (isActive: false) y su identificación sigue ocupada

const producto = await factuplan.products.create({
  code: 'SERV-001',
  auxiliaryCode: 'SERV-001',  // opcional — por defecto toma el mismo valor que code
  name: 'Servicio de consultoría',
  unitPrice: 150.00,
  type: 'SERVICE',          // PRODUCT | SERVICE
  taxType: 'IVA_RATE',      // IVA_0 | IVA_RATE | NOT_TAXABLE | EXEMPT
  description: 'Hora de consultoría técnica',
});

const { data: productos } = await factuplan.products.list({ search: 'consultoría' });

await factuplan.products.update('id', { unitPrice: 175.00 });

await factuplan.products.delete('id');

// Usar códigos SRI del establecimiento y punto de emisión
const factura = await factuplan.invoices.create({
  establishment: '001',
  emissionPoint: '001',
  customer, // el mismo cliente del ejemplo anterior
  items,    // las mismas líneas del ejemplo anterior
});

// Si solo tienes un punto de emisión activo, no necesitas enviarlo
const factura = await factuplan.invoices.create({
  customer, // el mismo cliente del ejemplo anterior
  items,    // las mismas líneas del ejemplo anterior
});

items: [
  {
    code: 'PROD-001',
    description: 'Producto con IVA reducido',
    quantity: 1,
    unitPrice: 100.00,
    taxType: 'IVA_RATE',
    tax: 5,  // IVA 5% en lugar del 15% por defecto
  },
]

import { Factuplan } from 'factuplan';

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: '0950194407001', // RUC del contribuyente con el que operas
});

async function crearFactura() {
  // 1. Buscar o crear cliente
  const { data: clientes } = await factuplan.customers.list({
    search: '0993378150001',
  });
  let cliente = clientes[0] ?? await factuplan.customers.create({
    identificationType: 'RUC',
    identification: '0993378150001',
    legalName: 'Mi Cliente S.A.',
    email: 'cliente@email.com',
  });

  // 2. Crear factura (sin emissionPointId → auto-detecta)
  const factura = await factuplan.invoices.create({
    customer: { customerId: cliente.id }, // un cliente guardado y activo
    items: [
      {
        code: 'PROD-001',
        description: 'Laptop Dell XPS 15',
        quantity: 1,
        unitPrice: 1500.00,
        taxType: 'IVA_RATE',
        tax: 15,
      },
    ],
    payments: [
      {
        method: '19',
        amount: 1725.00, // Total con IVA
        term: 6,
        timeUnit: 'meses',
      },
    ],
  });

  // 3. Esperar el resultado: COMPLETED es el final correcto; los demás son fallos o anulación
  let estado;
  do {
    await new Promise((r) => setTimeout(r, 3000));
    estado = await factuplan.invoices.getStatus(factura.id);
  } while (!['COMPLETED', 'ERROR', 'REJECTED', 'RETURNED', 'VOIDED'].includes(estado.status));

  if (estado.status === 'COMPLETED') {
    const { url } = await factuplan.invoices.downloadPdf(factura.id);
    console.log('PDF:', url);
  }
}

crearFactura();

const creditNote = await factuplan.creditNotes.create({
  invoiceAccessKey: '2312202301179214289100110010020000001231234567811',
  reason: 'Error en datos del cliente',
  items: [
    {
      code: 'SERV-001',
      description: 'Servicio de desarrollo web',
      quantity: 1,
      unitPrice: 100.00,
      taxType: 'IVA_RATE',
    },
  ],
});

console.log(creditNote.id);        // '019432a1-8f2c-...'
console.log(creditNote.accessKey); // '0412202404...'
console.log(creditNote.status);    // 'DRAFT'

const creditNote = await factuplan.creditNotes.get('CREDIT_NOTE_ID');

console.log(creditNote.id);
console.log(creditNote.accessKey);
console.log(creditNote.status);
console.log(creditNote.total);

const estado = await factuplan.creditNotes.getStatus('CREDIT_NOTE_ID');
// estado.status: COMPLETED (listo) | ERROR | REJECTED | RETURNED | VOIDED
// Cualquier otro valor (DRAFT, GENERATING_XML, SIGNING, SENDING_SRI, RECEIVED_SRI, AUTHORIZED, GENERATING_PDF, SENDING_EMAIL, PROCESSING) es un paso intermedio: sigue consultando

if (estado.status === 'COMPLETED') {
  console.log(estado.authorizationNumber);
}

const { url: xmlUrl } = await factuplan.creditNotes.downloadXml('CREDIT_NOTE_ID');
const { url: pdfUrl } = await factuplan.creditNotes.downloadPdf('CREDIT_NOTE_ID');

const result = await factuplan.creditNotes.list({
  status: 'COMPLETED',
  dateFrom: '2025-01-01T00:00:00-05:00',
  dateTo: '2025-12-31T23:59:59-05:00',
  page: 1,
  limit: 20,
});

result.data.forEach((nc) => {
  console.log(nc.sequential, nc.total, nc.customer.legalName);
});

// result.meta: { total, page, limit, totalPages }

// Un solo método para todos los tipos de comprobante: vive en invoices
const result = await factuplan.invoices.signAndAuthorize({
  xml: xmlString, // XML de la nota de crédito, sin firmar
});

console.log(result.authorized);          // true | false
console.log(result.authorizationNumber); // número de autorización del SRI
console.log(result.authorizationDate);   // fecha de autorización
console.log(result.authorizedXml);       // XML autorizado (base64)

if (!result.authorized) {
  console.error(result.messages); // motivos del rechazo del SRI
}

const result = await factuplan.creditNotes.void(
  'CREDIT_NOTE_ID',
  'Error en los datos del cliente',
);

console.log(result.status);     // "VOIDED"
console.log(result.voidReason); // Motivo ingresado
console.log(result.message);    // Confirmación

const result = await factuplan.creditNotes.retry('CREDIT_NOTE_ID');

console.log(result.action);    // "reprocess" | "authorize" | "pdf"
console.log(result.accessKey); // Puede ser una clave NUEVA

const result = await factuplan.creditNotes.updateSequential(
  '001', // branchCode — código del establecimiento
  '001', // emissionCode — código del punto de emisión
  100,   // creditNoteSequential — último secuencial usado (la siguiente nota será la 101)
);

console.log(result.creditNoteSequential); // 100
console.log(result.updatedAt);            // '2026-06-08T12:00:00.000Z'

const debitNote = await factuplan.debitNotes.create({
  invoiceAccessKey: '2312202301179214289100110010020000001231234567811',
  reasons: [
    {
      description: 'Ajuste por flete no facturado',
      amount: 25.00,
      taxType: 'IVA_RATE',  // IVA_RATE (IVA 15 %) | IVA_0 | NOT_TAXABLE | EXEMPT
    },
  ],
  // additionalInfo: { Referencia: 'OC-4521' },  // opcional
});

console.log(debitNote.id);        // '019432a1-8f2c-...'
console.log(debitNote.accessKey); // '0512202405...'
console.log(debitNote.status);    // 'DRAFT'

const { data: debitNotes, meta } = await factuplan.debitNotes.list({
  status: 'COMPLETED',
  page: 1,
  limit: 20,
});

const estado = await factuplan.debitNotes.getStatus('DEBIT_NOTE_ID');
// Termina en COMPLETED. AUTHORIZED es un estado de paso: autorizada por el SRI, el PDF puede no estar listo.
// Fallos: ERROR | REJECTED | RETURNED. Anulada: VOIDED.
// En curso: DRAFT, PROCESSING, GENERATING_XML, SIGNING, SENDING_SRI, RECEIVED_SRI, GENERATING_PDF, SENDING_EMAIL.

if (estado.status === 'COMPLETED') {
  console.log(estado.authorizationNumber);
}

const { url: xmlUrl } = await factuplan.debitNotes.downloadXml('DEBIT_NOTE_ID');
const { url: pdfUrl } = await factuplan.debitNotes.downloadPdf('DEBIT_NOTE_ID');

// Un solo método para todos los tipos de comprobante: vive en invoices
const result = await factuplan.invoices.signAndAuthorize({
  xml: xmlString, // XML de la nota de débito, sin firmar
});

console.log(result.authorized);          // true | false
console.log(result.authorizationNumber); // número de autorización del SRI
console.log(result.authorizationDate);   // fecha de autorización
console.log(result.authorizedXml);       // XML autorizado (base64)

if (!result.authorized) {
  console.error(result.messages); // motivos del rechazo del SRI
}

const voided = await factuplan.debitNotes.void('DEBIT_NOTE_ID', 'Emitida por error');

console.log(voided.status); // 'VOIDED'

const result = await factuplan.debitNotes.retry('DEBIT_NOTE_ID');

console.log(result.action);    // "reprocess" | "authorize" | "pdf"
console.log(result.accessKey); // Puede ser una clave NUEVA

const result = await factuplan.debitNotes.updateSequential(
  '001', // branchCode — código del establecimiento
  '001', // emissionCode — código del punto de emisión
  100,   // debitNoteSequential — último secuencial usado (la siguiente será la 101)
);

console.log(result.debitNoteSequential); // 100
console.log(result.updatedAt);           // '2026-06-08T12:00:00.000Z'

const withholding = await factuplan.withholdings.create({
  purchaseAccessKey: '0109202601179214673900110020010000000011234567815', // clave de la COMPRA
  codSustento: '01',         // Código de sustento (Tabla 5 del SRI)
  pagoLocExt: '01',          // '01' local | '02' exterior (opcional, default '01')
  fiscalPeriod: '09/2026',   // Período fiscal MM/AAAA (opcional; por defecto, el mes de la compra)
  taxes: [
    {
      taxType: 'IVA',             // 'RENTA' | 'IVA' | 'ISD'
      taxRateCode: '9',           // Código SRI (tabla 20): '9' = 10% de IVA
      taxRate: 10,                // Porcentaje de retención
      taxBase: 12.23,             // Base imponible
    },
    {
      taxType: 'RENTA',
      taxRateCode: '303',
      taxRate: 10,
      taxBase: 101.94,
    },
  ],
  additionalInfo: { observacion: 'Servicios profesionales' }, // opcional
});

console.log(withholding.id);            // '019432a1-8f2c-...'
console.log(withholding.accessKey);     // '0512202407...'
console.log(withholding.status);        // 'DRAFT'
console.log(withholding.totalWithheld); // Total retenido
console.log(withholding.purchaseId);    // Compra que sustenta la retención

const { data: withholdings, meta } = await factuplan.withholdings.list({
  status: 'COMPLETED',
  dateFrom: '2026-01-01T00:00:00-05:00',
  dateTo: '2026-06-30T23:59:59-05:00',
  page: 1,
  limit: 20,
});

const estado = await factuplan.withholdings.getStatus('WITHHOLDING_ID');

console.log(estado.status);              // 'COMPLETED' al terminar ('AUTHORIZED' es un estado de paso)
console.log(estado.authorizationNumber); // Número de autorización SRI

const { url: xmlUrl } = await factuplan.withholdings.downloadXml('WITHHOLDING_ID');
const { url: pdfUrl } = await factuplan.withholdings.downloadPdf('WITHHOLDING_ID');

// Un solo método para todos los tipos de comprobante: vive en invoices
const result = await factuplan.invoices.signAndAuthorize({
  xml: xmlString, // XML de la retención, sin firmar
});

console.log(result.authorized);          // true | false
console.log(result.authorizationNumber); // número de autorización del SRI
console.log(result.authorizationDate);   // fecha de autorización
console.log(result.authorizedXml);       // XML autorizado (base64)

if (!result.authorized) {
  console.error(result.messages); // motivos del rechazo del SRI
}

const voided = await factuplan.withholdings.void('WITHHOLDING_ID', 'Emitida por error');

console.log(voided.status); // 'VOIDED'

const result = await factuplan.withholdings.retry('WITHHOLDING_ID');

console.log(result.action);    // "reprocess" | "authorize" | "pdf"
console.log(result.accessKey); // Puede ser una clave NUEVA

const uso = await factuplan.usage();

console.log('Operaciones este mes:', uso.currentMonth.documents);
console.log('Costo estimado: $' + uso.currentMonth.cost);
console.log('Cuota propia de la API key:', uso.monthlyQuota ?? 'sin cuota');

const cert = await factuplan.certificates.status();

console.log(cert.hasCertificate);  // true = hay una firma cargada
console.log(cert.isExpired);       // true = la firma ya venció
console.log(cert.daysUntilExpiry); // Días que faltan para el vencimiento
console.log(cert.expiresAt);       // Fecha de vencimiento (ISO 8601)
console.log(cert.ruc);             // RUC que consta en el certificado
console.log(cert.legalName);       // Nombre del titular

const result = await factuplan.invoices.void(
  'ID_DEL_COMPROBANTE',
  'Error en los datos del cliente',
);

console.log(result.status);     // "VOIDED"
console.log(result.voidReason); // Motivo ingresado
console.log(result.message);    // Confirmación

const result = await factuplan.invoices.retry('ID_DEL_COMPROBANTE');

console.log(result.action);    // "reprocess" | "authorize" | "pdf"
console.log(result.status);    // Estado tras encolar el reintento
console.log(result.accessKey); // Clave de acceso vigente (puede ser NUEVA)

// Mismo método en el resto de comprobantes:
// factuplan.creditNotes.retry(id)
// factuplan.debitNotes.retry(id)
// factuplan.withholdings.retry(id)

const result = await factuplan.invoices.updateSequential(
  '001', // branchCode — código del establecimiento
  '001', // emissionCode — código del punto de emisión
  100,   // último secuencial usado: la próxima factura será la 000000101
);

console.log(result.invoiceSequential); // 100
console.log(result.updatedAt);         // ISO 8601

import { readFileSync } from 'fs';

const p12 = readFileSync('./mi-firma.p12');
// Si el RUC del certificado todavía no existe en tu workspace, usa un cliente creado sin la opción ruc
// (o con el RUC de un contribuyente que ya exista): el header x-taxpayer-ruc de un RUC desconocido se rechaza con 400.
const result = await factuplan.certificates.upload(p12, 'mi-contraseña');

console.log(result.ruc);       // RUC extraído del certificado
console.log(result.legalName); // Nombre legal
console.log(result.expiresAt); // Fecha de vencimiento
console.log(result.created);   // true si se creó un nuevo contribuyente

import { readFileSync } from 'fs';

const p12 = readFileSync('./mi-firma-renovada.p12');
const result = await factuplan.certificates.update(
  p12,
  'mi-contraseña',
  '0950194407001', // RUC del contribuyente a actualizar
);

console.log(result.updated);            // true
console.log(result.previousExpiresAt);  // vencimiento de la firma anterior
console.log(result.expiresAt);          // vencimiento de la firma nueva

const compra = await factuplan.purchases.register(
  '0509202601099234567800120020030000001231234567818',
);

console.log(compra.id);
console.log(compra.supplierId);          // proveedor creado o reutilizado; su nombre llega en purchases.get(compra.id)
console.log(compra.total);
console.log(compra.status);              // AUTHORIZED mientras se genera el PDF

const { data, meta } = await factuplan.purchases.list({
  status: 'COMPLETED',
  dateFrom: '2026-09-01',
  dateTo: '2026-09-30',
  page: 1,
  limit: 20,
});

console.log(meta.total, meta.totalPages);
for (const compra of data) {
  console.log(compra.sequential, compra.supplier?.legalName, compra.total);
}

const compra = await factuplan.purchases.get('019432a1-8f2c-7c3d-9a41-2b6e5d0f1a77');

console.log(compra.items?.length);
console.log(compra.withholdings); // [] si todavía no le emitiste retención

import { writeFileSync } from 'fs';

const pdf = await factuplan.purchases.getPdf(compra.id);
writeFileSync(pdf.filename, Buffer.from(pdf.base64, 'base64'));

const xml = await factuplan.purchases.getXml(compra.id);
writeFileSync(xml.filename, Buffer.from(xml.base64, 'base64'));

const result = await factuplan.purchases.retryPdf(compra.id);

console.log(result.success); // true
console.log(result.message); // "Estamos regenerando el PDF de la compra."

const result = await factuplan.purchases.delete(compra.id);

console.log(result.success); // true

const { unrestricted, taxpayers } = await factuplan.taxpayers.list();

if (unrestricted) {
  console.log('Esta API key puede operar con TODOS los contribuyentes');
} else {
  for (const t of taxpayers) {
    console.log(t.ruc, t.legalName, t.hasCertificate);
  }
}

// Si tu API key ya está restringida, usa un cliente creado sin la opción ruc (o con el RUC de un
// contribuyente ya vinculado): el header x-taxpayer-ruc de un RUC aún no vinculado se rechaza con 403.
const result = await factuplan.taxpayers.link('0950194407001');

console.log(result.linked);        // true
console.log(result.alreadyLinked); // false si acaba de vincularse
console.log(result.restrictedNow); // true si la llave pasó de "todos" a solo este
console.log(result.linkedCount);   // contribuyentes vinculados en total

// Usa un cliente creado sin la opción ruc (o con el RUC de un contribuyente que siga vinculado):
// el header x-taxpayer-ruc de un RUC que no está vinculado se rechaza con 403.
const result = await factuplan.taxpayers.unlink('0950194407001');

console.log(result.unlinked);        // true
console.log(result.alreadyUnlinked); // false si acaba de desvincularse
console.log(result.linkedCount);     // contribuyentes que siguen vinculados

// El contribuyente NO fue eliminado: sigue en tu workspace.