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
  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');

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: { ... },
  items: [ ... ],
});

// Si solo tienes un punto de emisión activo, no necesitas enviarlo
const factura = await factuplan.invoices.create({
  customer: { ... },
  items: [ ... ],
});

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!);

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: {
      identificationType: cliente.identificationType,
      identification: cliente.identification,
      legalName: cliente.legalName,
      email: cliente.email,
    },
    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 autorización
  let estado;
  do {
    await new Promise((r) => setTimeout(r, 3000));
    estado = await factuplan.invoices.getStatus(factura.id);
  } while (!['COMPLETED', 'ERROR', 'REJECTED'].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);        // 'clx1234...'
console.log(creditNote.accessKey); // '0412202404...'
console.log(creditNote.status);    // 'PROCESSING'

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: PROCESSING | AUTHORIZED | COMPLETED | ERROR | REJECTED

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: 'AUTHORIZED',
  dateFrom: '2025-01-01',
  dateTo: '2025-12-31',
  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 — nuevo valor del secuencial
);

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',  // IVA | IVA_0 | NO_TAX | ICE | IRBPNR | IVA_EXEMPT
    },
  ],
  // additionalInfo: { Referencia: 'OC-4521' },  // opcional
});

console.log(debitNote.id);        // 'clx1234...'
console.log(debitNote.accessKey); // '0512202404...'
console.log(debitNote.status);    // 'PROCESSING'

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

const estado = await factuplan.debitNotes.getStatus('DEBIT_NOTE_ID');
// estado.status: PROCESSING | AUTHORIZED | COMPLETED | ERROR | REJECTED

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 — nuevo valor del secuencial
);

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);            // 'clx1234...'
console.log(withholding.accessKey);     // '0512202404...'
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: 'AUTHORIZED',
  dateFrom: '2026-01-01',
  dateTo: '2026-06-30',
  page: 1,
  limit: 20,
});

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

console.log(estado.status);              // 'AUTHORIZED'
console.log(estado.authorizationNumber); // Número de autorización SRI
console.log(estado.authorizationDate);   // Fecha de autorización

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 guia = await factuplan.waybills.create({
  emissionPointId: 'EMISSION_POINT_ID',
  customer: {
    identificationType: 'RUC',
    identification: '1790012345001',
    legalName: 'Empresa Destino S.A.',
    email: 'destino@empresa.com',
  },
  transporterRuc: '1790012345001',
  transporterName: 'Transportes del Norte S.A.',
  vehiclePlate: 'ABC-1234',
  departureAddress: 'Av. 10 de Agosto N23-45, Quito',
  transportStartDate: '2026-06-10',
  transportEndDate: '2026-06-11',
  items: [
    {
      code: 'PROD-001',
      description: 'Caja de mercadería',
      quantity: 10,
    },
  ],
  destinations: [
    {
      receiverIdentification: '0950194407001',
      receiverName: 'Cliente Final',
      address: 'Av. del Ejército 123, Guayaquil',
      transferReason: 'Venta de mercadería',
    },
  ],
});

console.log(guia.id);        // 'clx1234...'
console.log(guia.accessKey); // '0606202604...'
console.log(guia.status);    // 'PROCESSING'

const { data: guias, meta } = await factuplan.waybills.list({
  status: 'AUTHORIZED',
  dateFrom: '2026-01-01',
  dateTo: '2026-06-30',
  page: 1,
  limit: 20,
});

const estado = await factuplan.waybills.getStatus('WAYBILL_ID');

console.log(estado.status);              // 'AUTHORIZED'
console.log(estado.authorizationNumber); // Número de autorización SRI
console.log(estado.authorizationDate);   // Fecha de autorización

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

const voided = await factuplan.waybills.void('WAYBILL_ID', 'Emitida por error');

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

const uso = await factuplan.usage();

console.log(uso.requestsUsed, '/', uso.requestsLimit);
console.log('Costo estimado: $' + uso.estimatedCost);

const cert = await factuplan.certificateStatus();

console.log(cert.valid);       // true = vigente
console.log(cert.expiresAt);   // Fecha de vencimiento (ISO 8601)
console.log(cert.taxpayerId);  // RUC del titular
console.log(cert.commonName);  // Nombre en el certificado

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,   // nuevo secuencial
);

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

import { readFileSync } from 'fs';

const p12 = readFileSync('./mi-firma.p12');
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.supplier?.legalName); // proveedor que te emitió la factura
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);
  }
}

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

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.