FactuSmart — SDK de Python

SDK oficial del API de facturación electrónica de FactuSmart (SUNAT, Perú): facturas, boletas, notas de crédito/débito, guías de remisión (GRE 2.0) y anulaciones.

• Python 3.8 o superior.
• Cero dependencias: solo librería estándar (urllib).
• Con type hints (py.typed).
• Documentación completa del API: https://factusmart.pe/api-facturacion-electronica/docs

Instalar

pip install factusmart

Uso en 10 líneas

import factusmart

fs = factusmart.Cliente(api_key="TU_API_KEY", base_url="https://TU_URL_BASE/api/v1/issuer", ruc="20123456789")

calc = factusmart.calcular_comprobante([
    {"descripcion": "Servicio de consultoría", "cantidad": 1, "valor_unitario": 100, "afectacion": "10"},
])

r = fs.comprobantes.emitir({
    "codigo_tipo_documento": "01",
    "datos_del_cliente_o_receptor": {"codigo_tipo_documento_identidad": "6", "numero_documento": "20555555555"},
    "items": calc["items"], "totales": calc["totales"],
})

print(r["aceptado_por_sunat"], r["serie_numero"])

base_url no es igual para todas las cuentas: cada cuenta vive en un servidor distinto. Cópiala de tu panel de integrador (pestaña Configuración, "URL base de la API").

Opciones del cliente

Si falta api_key o base_url, el cliente lanza ValueError al crearse.

Métodos

Los datos se envían y se reciben tal cual los define el API (claves en español con guion bajo). Todos los métodos que operan sobre un RUC aceptan ruc= para cambiar el del constructor (en GET va como ?ruc=; en POST va en el cuerpo, y si tú ya pusiste ruc en los datos, se respeta el tuyo).

Filtros de comprobantes.listar: estado, desde, hasta (YYYY-MM-DD), limite (1 a 100) y antes_de (pasa el siguiente_cursor de la página anterior).

Guardar el PDF:

with open("comprobante.pdf", "wb") as f:
    f.write(fs.comprobantes.descargar(r["external_id"], "pdf"))

Lo que comprobantes.emitir completa por ti

Solo si no lo mandas:

• numero_documento: "#" (FactuSmart asigna el correlativo). Si mandas tu propio número, se respeta.
• fecha_de_emision y hora_de_emision: fecha y hora de Perú (America/Lima), no la de tu servidor.
• codigo_tipo_moneda: "PEN".
• codigo_tipo_operacion: "0101" en facturas y boletas (en notas no aplica).

guias.emitir completa igual numero_documento, fecha_de_emision y hora_de_emision.

Calcular IGV y totales

El API espera los importes ya calculados. calcular_comprobante lo hace por ti: recibe cada ítem con descripcion, cantidad, valor_unitario (sin IGV) y afectacion, y devuelve {"items": [...], "totales": {...}} listo para enviar.

Opcionales por ítem: codigo_interno (recomendado: el SKU de tu sistema) y unidad_de_medida (por defecto NIU; usa ZZ para servicios).

Redondea a 2 decimales por ítem con decimal.Decimal y ROUND_HALF_UP, así da exactamente los mismos números que los SDK de PHP y Node.

La regla de oro: revisa aceptado_por_sunat

Un HTTP 200 significa que FactuSmart generó tu comprobante, no que SUNAT lo aceptó. SUNAT puede estar caída o rechazarlo: recibirás estado: "01" con aceptado_por_sunat: False y el motivo en sunat["descripcion"].

Eso NO es una excepción. El SDK te devuelve la respuesta tal cual y tú decides:

r = fs.comprobantes.emitir(datos)
if not r["aceptado_por_sunat"]:
    print("SUNAT no lo aceptó todavía:", r.get("sunat"), r.get("accion_requerida"))
    # corrige y reintenta gratis con: fs.comprobantes.reenviar(r["external_id"])

Mira también entorno ("prueba" o "produccion") y tiene_validez_fiscal.

Errores

Todas las excepciones están en factusmart.errores (y también en factusmart) y heredan de FactuSmartError, que trae:

• status: código HTTP (None si fue un error de red),
• mensaje: el mensaje del API, en español,
• respuesta: el cuerpo completo de la respuesta.

from factusmart import errores

try:
    r = fs.comprobantes.emitir(datos)
except errores.ErrorDeValidacion as e:
    print("Datos inválidos:", e.mensaje)   # no se cobró el crédito
except errores.SinCreditos:
    print("Recarga créditos")
except errores.FactuSmartError as e:
    print("Error", e.status, e.mensaje)

Reintentos e idempotencia

• comprobantes.emitir siempre manda el header Idempotency-Key: la tuya (idempotency_key="id-de-tu-venta") o un UUID v4 generado. La misma clave se usa en todos los reintentos de esa llamada, así un reintento nunca emite dos veces ni cobra dos veces. Si llamas dos veces con la misma clave, recibes la misma respuesta.
• Se reintenta solo ante: error de red/timeout, HTTP 429, 502, 503 y 504, con espera creciente (1 s, 2 s, 4 s…), hasta max_reintentos veces. Ante un límite de peticiones se respeta el header Retry-After o el "Espera N segundos" del mensaje.
• En emitir, el HTTP 409 ("ya hay una emisión en curso con esa Idempotency-Key") también se reintenta con la misma clave.
• Se reintentan las consultas (GET) y rucs.crear (el API es idempotente por RUC).
• Nunca se reintentan solas: anulaciones.crear, guias.emitir, comprobantes.reenviar, comprobantes.consultar_sunat y rucs.activar.

Pruebas (para quien mantiene el SDK)

python -m unittest discover -s tests -v

• test_unitarios.py y test_calculo.py no usan red.
• test_contrato.py lee openapi.yaml (variable FACTUSMART_OPENAPI) y falla si algún operationId no tiene método en el SDK.
• test_integracion.py va contra el API local (FACTUSMART_TEST_BASE_URL, FACTUSMART_TEST_API_KEY, FACTUSMART_TEST_RUC; FACTUSMART_INTEGRACION=0 para saltarlas). Gasta 2 créditos por corrida. Se niega a correr contra factusmart.pe.

Licencia

MIT. Ver LICENSE.