Skip to Content
SDKsNode.js / TypeScript

Node.js / TypeScript SDK

Disponible — paquete @factulink/node en npm. Tipos TypeScript nativos, compatible con Node.js 18+.

El SDK oficial de FactuLink para Node.js y TypeScript. Proporciona una interfaz tipada y ergonomica para todos los endpoints de la API.

Instalacion

npm install @factulink/node
# o con pnpm
pnpm add @factulink/node
# o con yarn
yarn add @factulink/node

Requiere Node.js 18+. Soporta CommonJS y ESM.

Quickstart

import FactuLink from '@factulink/node';
 
const fc = new FactuLink({
  apiKey: process.env.FC_API_KEY!, // sk_test_... o sk_live_...
});
 
// Emitir un CFDI
const { data: cfdi } = await fc.cfdis.create({
  tipo: 'I',
  receptor: {
    rfc: 'XAXX010101000',
    nombre: 'Cliente de Prueba',
    regimen_fiscal: '601',
    domicilio_fiscal: '06600',
    uso_cfdi: 'G03',
  },
  conceptos: [
    {
      clave_prod_serv: '43211503',
      descripcion: 'Laptop',
      cantidad: 1,
      clave_unidad: 'H87',
      valor_unitario: 15000,
    },
  ],
});
 
console.log(cfdi.uuid);
// → "6128396f-c09c-4e3a-b4d7-8a5f2e1c9b3d"

Configuracion

const fc = new FactuLink({
  apiKey: 'sk_live_...',                   // Requerido
  baseUrl: 'https://api.factulink.com.mx', // URL de produccion
  timeout: 30_000,                         // Default 30s
  retries: 2,                              // Default 2 reintentos en 429/5xx
});

Recursos disponibles

RecursoMetodos
fc.cfdiscreate, list, get, cancel, downloadXml, downloadPdf, satStatus, validate, listAutoPaginate
fc.clientscreate, list, get, update, delete
fc.certificatesupload, list, get, update, delete
fc.catalogsproducts, units, taxRegimes, cfdiUsages, paymentForms, paymentMethods, currencies, countries
fc.webhookscreate, list, update, delete, deliveries, test
fc.aicreateFromText, confirmInvoice, copilot
fc.apiKeyscreate, list, revoke

Operaciones comunes

Descargar PDF / XML

const pdf = await fc.cfdis.downloadPdf(cfdi.uuid);
const xml = await fc.cfdis.downloadXml(cfdi.uuid);
 
import { writeFileSync } from 'node:fs';
writeFileSync('factura.pdf', pdf);

Cancelar CFDI

const { data: resultado } = await fc.cfdis.cancel(cfdi.uuid, {
  motivo: '02',
});

Listar con paginacion

const { data: page } = await fc.cfdis.list({
  estado: 'timbrado',
  limit: 20,
});
 
console.log(page.items);
console.log(page.next_cursor);

Auto-paginacion (async iterator)

for await (const cfdi of fc.cfdis.listAutoPaginate({ estado: 'timbrado' })) {
  console.log(cfdi.uuid, cfdi.total);
}

Webhooks

const { data: webhook } = await fc.webhooks.create({
  url: 'https://tu-servidor.com/fc-webhook',
  events: ['cfdi.timbrado', 'cfdi.cancelado'],
});
 
console.log('Guarda este secret:', webhook.secret);
 
// Probar la entrega
await fc.webhooks.test(webhook.id);

Manejo de errores

El SDK exporta clases de error tipadas:

import FactuLink, {
  ApiError,
  AuthError,
  RateLimitError,
} from '@factulink/node';
 
try {
  await fc.cfdis.create(params);
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited — reintenta en ${err.retryAfter}s`);
  } else if (err instanceof AuthError) {
    console.log('API key invalida o expirada');
  } else if (err instanceof ApiError) {
    console.log(err.code, err.message, err.details);
  } else {
    throw err;
  }
}

El cliente reintenta automaticamente en errores 429 y 5xx (configurable con retries).

Ambientes

  • Sandbox: crea API Keys con prefijo sk_test_... desde el dashboard. Las llamadas usan timbrado simulado, no se envían al SAT y no consumen folios reales.
  • Produccion: usa API Keys con prefijo sk_live_.... Las llamadas timbran con el PAC autorizado y se registran ante el SAT.

El mismo baseUrl (https://api.factulink.com.mx) atiende ambos ambientes — el prefijo de la API Key determina cual usar.

Codigo fuente

Reportes de bugs y feature requests bienvenidos en el repo.

Last updated on
OverviewPHP / Laravel