SDKs para PHP, Node.js, Python, Java y C#

Instalar

npm install factusmart

Requisitos: Node.js 18+ (sin dependencias), PHP 8.1+ con ext-curl y ext-json, Python 3.8+ (solo librería estándar), Java 11+ (sin dependencias), .NET Framework 4.6.1+ / .NET Core 2.0+ / .NET 8 (netstandard2.0 y net8.0).

Tu primera factura en 10 líneas

Reemplaza TU_API_KEY y TU_URL_BASE por los de tu panel (pestaña Configuración). No hay un dominio único: cada cuenta vive en su servidor.

import { FactuSmart } from 'factusmart'

const fs = new FactuSmart({ apiKey: 'TU_API_KEY', baseUrl: 'https://TU_URL_BASE/api/v1/issuer', ruc: '20100070970' })

const { items, totales } = FactuSmart.calcularComprobante([
  { descripcion: 'Servicio de consultoría', cantidad: 1, valor_unitario: 100, afectacion: '10' },
])

const r = await fs.comprobantes.emitir({
  codigo_tipo_documento: '01',
  datos_del_cliente_o_receptor: { codigo_tipo_documento_identidad: '6', numero_documento: '20131312955' },
  items, totales,
})

console.log(r.aceptado_por_sunat, r.serie_numero)

• calcularComprobante (calcular_comprobante en Python) arma items y totales con IGV 18% y redondeo a 2 decimales. Afectación 10 gravado, 20 exonerado, 30 inafecto, 40 exportación.
• Si no los mandas, el SDK pone numero_documento: "#" (correlativo automático), la fecha y hora de Perú, codigo_tipo_operacion: "0101" y codigo_tipo_moneda: "PEN".
• El ruc del constructor es el emisor por defecto; lo puedes cambiar en cada llamada con la opción ruc.
• En C# todos los métodos son async (terminan en Async) y devuelven un JsonElement; en Java devuelven un Map. Los datos que mandas usan las mismas claves del API.

Métodos y endpoints

Un método por cada endpoint del API. Node.js, PHP y Java usan camelCase; Python, snake_case; C#, PascalCase con Async al final. El detalle de cada campo está en la Referencia del API.

En PHP se llaman con flecha: $fs->comprobantes->emitir(...). formato solo aplica al PDF: a4, a5, ticket (80 mm), ticket58, ticket50; sin él, el A4 de siempre. Ver Descargar PDF y Varios locales (anexos).

Errores

Todos heredan de FactuSmartError, que trae status (HTTP), mensaje (el message del API) y respuesta (el cuerpo completo). En PHP viven en FactuSmart\Excepciones; en C# la base se llama FactuSmartException.

import { FactuSmart, SinCreditos, ErrorDeValidacion, FactuSmartError } from 'factusmart'

try {
  const r = await fs.comprobantes.emitir(datos, { idempotencyKey: 'venta-000123' })
  if (!r.aceptado_por_sunat) {
    // No es excepción: el comprobante existe. Revisa r.estado, r.sunat y r.accion_requerida.
  }
} catch (e) {
  if (e instanceof SinCreditos) { /* sube de plan o pide créditos extra */ }
  else if (e instanceof ErrorDeValidacion) { console.error(e.mensaje) }
  else if (e instanceof FactuSmartError) { console.error(e.status, e.mensaje, e.respuesta) }
  else throw e
}

Decide por codigo y reintentable

Toda excepción trae también codigo (el código estable del API, ej. SIN_CREDITOS, DATOS_INVALIDOS) y reintentable (true si repetir la misma petición más tarde puede funcionar). Úsalos en vez de comparar mensaje, que puede cambiar de redacción. Si te llega un codigo que no conoces, guíate por reintentable. Catálogo completo en Códigos de error.

import { FactuSmartError } from 'factusmart'

try {
  await fs.comprobantes.emitir(datos, { idempotencyKey: 'venta-000123' })
} catch (e) {
  if (!(e instanceof FactuSmartError)) throw e
  if (e.codigo === 'SIN_CREDITOS') { /* sube de plan o pide créditos extra */ }
  else if (e.reintentable) { /* encola y vuelve a intentar más tarde */ }
  else { console.error(e.codigo, e.mensaje) /* corrige los datos */ }
}

Verificar webhooks

Si configuraste un webhook, cada aviso llega firmado en el header X-FactuSmart-Firma (HMAC-SHA256 del cuerpo con tu secreto whsec_…). Los SDK lo verifican con una sola función que devuelve true/false:

• Node.js: FactuSmart.verificarFirmaWebhook(cuerpoCrudo, firma, secreto)
• PHP: \FactuSmart\Cliente::verificarFirmaWebhook($cuerpoCrudo, $firma, $secreto)
• Python: factusmart.verificar_firma_webhook(cuerpo_crudo, firma, secreto)
• Java: FactuSmart.verificarFirmaWebhook(cuerpoCrudo, firma, secreto)
• C#: FactuSmartClient.VerificarFirmaWebhook(cuerpoCrudo, firma, secreto)

import express from 'express'
import { FactuSmart } from 'factusmart'

app.post('/webhooks/factusmart', express.raw({ type: 'application/json' }), (req, res) => {
  const firma = req.get('X-FactuSmart-Firma') || ''
  if (!FactuSmart.verificarFirmaWebhook(req.body, firma, process.env.FACTUSMART_WEBHOOK_SECRET)) {
    return res.sendStatus(401)
  }
  const aviso = JSON.parse(req.body.toString('utf8'))
  res.sendStatus(200)
})

Reintentos e idempotencia

• comprobantes.emitir siempre manda Idempotency-Key: la tuya si la pasas (idempotencyKey / idempotency_key, recomendado: el id de tu venta) o una generada. La misma clave se reusa en todos los reintentos, así un reintento nunca emite dos veces ni te cobra dos veces.
• Se reintenta solo ante error de red o timeout, límite de peticiones y respuestas 502, 503, 504, con espera creciente (1 s, 2 s, 4 s…). Por defecto hasta 3 veces (maxReintentos / max_reintentos).
• Un 409 al emitir («ya hay una emisión en curso con esa Idempotency-Key») también se reintenta con la misma clave.
• Nunca se reintentan solos: anulaciones.crear, guias.emitir, comprobantes.reenviar, comprobantes.consultarSunat y rucs.activar. Las consultas (GET) sí.
• Timeout por defecto: 60 segundos (SUNAT a veces tarda).

Más sobre el comportamiento del API en Evitar duplicados y Códigos de error.