Ir al contenido
Facturalo

SDKs oficiales

Librerías oficiales de Facturalo para Node.js y PHP: emiten comprobantes y guías, consultan documentos, RUC y DNI, trabajan el SIRE y verifican webhooks sin armar la petición HTTP a mano.

Los SDKs son clientes delgados sobre la API REST v3. Son solo para tu servidor: usan el token de la empresa (sk_test_... en demo, sk_live_... en producción), así que nunca los importes en el navegador.

Node.js1.1.0

@facturalo-pe/node · npm. Node 18 o superior, con tipos de TypeScript.

Ver paquete
PHP1.1.0

facturalo-pe/facturalo-php · Composer. PHP 8.1 o superior, funciona con Laravel.

Ver paquete

Qué cubren

Hay dos clientes, según el token. Los métodos tienen los mismos nombres que la API y son iguales en Node y PHP.

  • FacturaloClient (token de empresa): documentos (enviar, generarXml, consultar, buscar, listar, anular, reenviar, eventos, eliminar, descargar), guias (enviar, consultar, consultarTicket, eventos, listar, descargar), consultas (RUC, DNI, tipo de cambio, placa, SOAT, licencia), webhooks (listar, reenviar) y sire.ventas / sire.compras.
  • FacturaloCuentaClient (token de usuario user_sk_...): empresas (crear, actualizar, tokens, webhook y eventos) y establecimientos. Útil si tu software da de alta las empresas de tus clientes.
  • Webhooks: verificación de la firma X-Facturalo-Firma en tiempo constante, sobre el cuerpo crudo.

Cómo se comportan

Un rechazo de SUNAT no lanza excepción: vuelve con estado: "RECHAZADA" y el motivo en sunat. Las excepciones son para errores de la petición (validación, token, red). Sin idempotencyKey, los POST de envío no se reintentan solos. Con idempotencyKey, el SDK puede reintentar de forma segura ante 429/5xx; en el servidor la clave evita duplicados (ver Idempotencia).
npmbash
npm install @facturalo-pe/node
Emitir una facturats
import { FacturaloClient } from "@facturalo-pe/node";

const facturalo = new FacturaloClient({ token: process.env.FACTURALO_TOKEN! });

const envio = await facturalo.documentos.enviar({
  sunatTransaccion: "0101",
  tipoComprobante: "01",
  serie: "F001",
  correlativo: "1",
  fechaEmision: "2026-10-30",
  moneda: "PEN",
  formaPago: "CONTADO",
  cliente: {
    tipoDocumento: "6",
    numeroDocumento: "20000000001",
    denominacion: "EMPRESA S.A.C.",
    direccion: "AV. LIMA 123 - LIMA",
  },
  items: [
    { unidadMedida: "NIU", descripcion: "SERVICIO", cantidad: 1, precioUnitario: 118, tipoIgv: "10" },
  ],
}, { idempotencyKey: "orden-1042" });

if (envio.estado === "ACEPTADA") {
  console.log(envio.enlaces.pdf);
} else {
  console.log(envio.sunat?.codigo, envio.sunat?.mensaje);
}
Recibir un webhook (Express)ts
import express from "express";
import { construirEventoWebhook } from "@facturalo-pe/node";

app.post("/webhooks/facturalo", express.raw({ type: "application/json" }), (req, res) => {
  const evento = construirEventoWebhook(
    req.body,
    req.header("X-Facturalo-Firma"),
    process.env.FACTURALO_WEBHOOK_SECRET!,
  );
  // evento.evento, evento.documento, evento.sunat, evento.enlaces
  res.sendStatus(200);
});

Cada página de la referencia muestra su ejemplo con el SDK en las pestañas Node y PHP. El código está en GitHub: facturalo-node y facturalo-php.

Siguiente