Ir al contenido
AppsSDAR

Facturación electrónica SUNAT desde tu propio sistema

Por 10 min de lectura Pagos y normativa peruana

Cuando un sistema web empieza a cobrar, tarde o temprano alguien pregunta quién emite la boleta. Hay dos caminos fáciles: hacerla a mano en el portal de SUNAT, o pagar a un tercero que te venda la emisión. Hay un tercero que casi nadie considera: emitir tú mismo desde tu propio sistema, directo a SUNAT, con software libre y sin costo por comprobante. Es el camino que montamos para facturar desde nuestros propios sistemas, y esta nota cuenta cómo funciona por dentro y dónde están las trampas.

No es asesoría tributaria. Qué comprobante te toca emitir, a qué régimen perteneces y cuándo eres obligado lo decide tu contador y las normas de SUNAT. Aquí va la parte técnica.

Los sistemas de emisión: elige antes de programar

SUNAT llama "sistemas de emisión electrónica" a las vías autorizadas para emitir comprobantes. En su portal de comprobantes de pago electrónicos describe, entre otros, estos:

  • SEE-SOL: emites desde el portal de SUNAT (Operaciones en Línea) con tu Clave SOL, sin software propio y sin certificado digital. Es la vía manual: descripción en cpe.sunat.gob.pe. No sirve para automatizar cobros de una app, porque no hay forma de llamarla desde tu código.
  • SEE-Del contribuyente: tu sistema genera el comprobante, lo firma con un certificado digital y lo envía a SUNAT. Es el que automatiza una app y el que usamos. Página oficial.
  • SEE-OSE: el comprobante pasa por un Operador de Servicios Electrónicos, un tercero autorizado. SUNAT mantiene la página de operadores.
  • SEE-SFS (Facturador SUNAT): una cuarta modalidad que menciona la Resolución de Superintendencia 114-2019/SUNAT junto a las otras dos. No la usamos y no la cubro aquí.

La regla práctica: si quieres emitir sin intervención humana desde tu sistema y sin intermediario, es SEE-Del contribuyente. Si prefieres delegar la operación a un operador, es SEE-OSE. Cambia quién se encarga del envío y de la entrega por medios electrónicos, no la obligación de emitir bien.

Qué hace realmente "emitir"

Aunque uses una librería, conviene saber la cadena completa, porque cada eslabón falla de forma distinta:

  1. Armar el XML en UBL 2.1. El comprobante es un documento XML con un formato estándar (UBL) y catálogos de SUNAT: tipo de documento, tipo de afectación del IGV, unidad de medida, tipo de operación.
  2. Firmarlo con tu certificado digital (XMLDSig). Sin firma válida, SUNAT lo rechaza.
  3. Enviarlo al servicio web de SUNAT con un usuario secundario de Clave SOL, con permiso de emisión electrónica.
  4. Leer la respuesta: el CDR (constancia de recepción). Si no lo guardas y lo interpretas, no sabes si el comprobante existe.

Las facturas se envían una por una y reciben su CDR al momento. Las boletas funcionan distinto: en SEE-Del contribuyente se informan a SUNAT en un resumen diario que agrupa las boletas de un mismo día y sus notas asociadas. SUNAT devuelve un CDR del resumen, aceptado o rechazado, y si es rechazado hay que generar un resumen nuevo con la información corregida (así lo explica la guía de operatividad de SUNAT). Los plazos de envío de cada documento los fija la norma y cambian con el tiempo; léelos ahí y en la resolución del sistema que uses, no en una nota de blog.

El certificado digital y su primera trampa

Para firmar necesitas un certificado digital. En nuestro caso usamos el certificado para comprobantes que SUNAT permite obtener sin costo; el flujo es: lo generas, registras la parte pública en el portal (Greenter pide el formato .cer) y guardas el archivo con la clave privada. Confirma en SUNAT qué certificados acepta hoy. La librería que veremos pide el certificado en formato PEM (clave privada y pública), así que un .p12 o .pfx hay que convertirlo.

Aquí nos costó horas. El .p12 que entrega SUNAT usa un cifrado antiguo (RC2-40 para el certificado, 3DES para la llave). Con OpenSSL 3 o con un PHP reciente la lectura falla con un error de algoritmo "unsupported". El síntoma es que el mismo archivo abre en un equipo viejo y no en el servidor nuevo. La conversión que lo resolvió:

openssl pkcs12 -legacy -in certificado.p12 -nodes -out cert.pem

Dos cuidados con el resultado. El PEM contiene la llave privada sin cifrar (-nodes), así que su sitio es un volumen del servidor de facturación, con permisos mínimos, y jamás un repositorio ni un hosting compartido. Y anota la fecha de vencimiento del certificado en tu monitoreo: un certificado vencido detiene la emisión de un día para otro, sin que cambie una línea de código.

Greenter y Lycet: no escribas el XML a mano

Greenter es una librería PHP de código abierto que genera el XML UBL 2.0 y 2.1 según la norma de SUNAT, lo firma, lo envía a los servicios web y procesa el CDR. Pide PHP 7.4 o superior con las extensiones soap y openssl. Un envío completo, según su guía de inicio, es esto:

$see = new See();
$see->setCertificate(file_get_contents(__DIR__.'/certificate.pem'));
$see->setService(SunatEndpoints::FE_BETA);
$see->setClaveSOL('20000000001', 'MODDATOS', 'moddatos');

$result = $see->send($invoice);   // genera XML, firma, envía, procesa CDR

if (!$result->isSuccess()) {
    // no se pudo hablar con SUNAT: es un error de conexión o de servicio
    echo $result->getError()->getCode();
}
$cdr = $result->getCdrResponse();

Las credenciales de ese ejemplo (RUC 20000000001, usuario MODDATOS) son las públicas del ambiente de pruebas de SUNAT que documenta Greenter; no son de nadie.

Si tu sistema no está en PHP, como los nuestros que son Node, no necesitas reescribir nada: Lycet es una API REST (licencia MIT) construida sobre Greenter y Symfony precisamente para aplicaciones en otros lenguajes. Se levanta con Docker y se autentica con un token como parámetro de la URL. Tu sistema le manda el comprobante en JSON y Lycet hace el resto.

Cómo lo desplegamos

Lycet no publica una imagen lista en Docker Hub: se construye desde su Dockerfile. Estas fueron nuestras decisiones, todas por la misma razón, que el servicio que firma comprobantes es una pieza sensible y no debe estorbar a nada más:

  • El puerto solo en loopback: 127.0.0.1:8010:8000 en el compose. Los puertos que publica Docker se saltan el firewall del servidor, así que publicar en todas las interfaces dejaría la API de firma abierta a internet protegida únicamente por un token en la URL.
  • Límites de recursos: mem_limit: 512m, una CPU y dos workers de php-pm (por defecto son ocho). Con eso el contenedor ocupa unos 65 MB en reposo.
  • Red interna compartida con el servicio propio que llama a Lycet, de modo que nunca se accede por la red pública.
  • Versión de PHP: la imagen de Lycet salió sobre PHP 8.1, que ya no recibe parches de seguridad. Antes de producción reconstruimos sobre PHP 8.3.

Las llamadas tienen la forma /api/v1/<documento>/send, y también xml y pdf, donde el documento es invoice (factura y boleta), note, summary o voided. Resumen y baja son asíncronos: devuelven un ticket que se consulta luego en /status.

Beta primero, producción después

SUNAT mantiene un ambiente beta donde puedes probar el ciclo completo con las credenciales públicas de arriba y un certificado de prueba. Pasar a producción es cambiar tres cosas, según la guía de producción de Greenter: el endpoint (de FE_BETA a FE_PRODUCCION), tu usuario secundario de Clave SOL (la guía advierte que puede tardar hasta 24 horas en quedar activo) y tu certificado real, registrado en el portal.

En nuestras pruebas en beta aceptó, con código 0, una factura, un resumen diario con una boleta, una nota de crédito y una factura con su comunicación de baja. Lo que aprendimos de ese ambiente:

  • Beta es más permisivo que producción. Por ejemplo, un envío duplicado lo acepta, mientras que producción responde que el comprobante ya fue registrado. Ese camino de error solo se puede comprobar en producción, así que escríbelo con cuidado.
  • Un aviso no es un rechazo. Nuestro primer envío salió aceptado pero con la observación 4094, por haber puesto "-" como dirección del emisor. Los códigos de observación del CDR se corrigen en los envíos siguientes.
  • Antes de pasar a producción, vacía tu base. Cada prueba en beta consume correlativos y deja números en tu sistema que producción no conoce.

Leer el CDR sin engañarte

Que la llamada HTTP haya funcionado no significa que SUNAT aceptó el comprobante. Son dos preguntas distintas. La guía de Greenter clasifica el código del CDR así, y es la regla que seguimos:

  • 0: aceptado (pueden venir observaciones en las notas).
  • 2000 a 3999: rechazado.
  • 0100 a 1999: excepción; un CDR que no debería darse y se trata como error a revisar.

Un detalle que nos costó un susto: si el envío se corta antes de recibir la respuesta, tu sistema no sabe si SUNAT lo registró. Reintentar a ciegas puede dar el error de "ya registrado". Ante ese error, consulta primero el CDR del comprobante antes de darlo por fallido; de lo contrario queda fuera de tu registro de ventas algo que sí existe para SUNAT.

Lo que programamos alrededor

Lycet envía; no decide qué enviar ni cuándo. Esa lógica es tuya, y es donde se pierde plata si se hace mal:

  • Un servicio central, no una librería en cada sistema. Con un solo RUC hay un correlativo por serie. Si tres aplicaciones emiten en paralelo con la misma serie, duplican números. Tenemos un servicio con base propia y una serie distinta por producto; los sistemas le hablan por HTTP con su propia clave.
  • Idempotencia por transacción. Cada comprobante nace de un cobro, y el cobro puede confirmarse dos veces (lo contamos en cobrar con Izipay). Una restricción UNIQUE sobre el sistema y el id del cobro evita emitir dos comprobantes por un pago.
  • El correlativo dentro de la transacción de base de datos. Se toma con un UPDATE … RETURNING en la misma transacción que inserta el comprobante: si el insert falla, el número vuelve y no quedan huecos en la numeración.
  • Facturas al momento, boletas en lote. La boleta se firma al cobrar (para entregarla al cliente), queda "por resumir" y sale en el resumen diario de la noche. Cualquier reporte de ventas debe avisar cuántas boletas siguen esperando resumen.
  • Reintentos con espera creciente ante fallos de conexión o del servicio de SUNAT, y un estado distinto para "rechazado", que no se reintenta sino que se revisa a mano.
  • Hora de Lima. La fecha de emisión y el corte del resumen diario se calculan en la zona horaria de Perú, no en la del servidor; es el mismo problema de servidor en UTC, usuarios en Lima.

Anular: baja o nota de crédito

Hay dos mecanismos y no son intercambiables. La comunicación de baja es para documentos que no se entregaron al cliente; según SUNAT, en SEE-Del contribuyente la baja de una boleta se incluye en el resumen diario del día de emisión, y la de una factura es un trámite aparte que exige que ya haya sido informada y aceptada (operatividad). Si el cliente ya recibió el comprobante y hay que revertirlo, se emite una nota de crédito. Nosotros decidimos que toda anulación desde el panel sea una nota de crédito por anulación de la operación, porque funciona igual para cualquier caso y deja rastro; si tu operación tiene comprobantes no entregados, la baja también aplica. Consúltalo con tu contador.

Otras trampas con el síntoma exacto

  • El ubigeo es el de SUNAT, no el de RENIEC. Para un mismo distrito, el código de RENIEC y el del INEI que usa SUNAT pueden diferir. Si pones el equivocado, el comprobante sale con un distrito que no es el tuyo. Usa el catálogo de ubigeo de SUNAT.
  • La dirección sale cortada en el PDF. La plantilla de Greenter imprime solo el campo direccion del domicilio del emisor. Si lo llenas con el distrito aparte, el PDF muestra solo la calle. Pon la dirección completa en ese campo.
  • El logo no viaja en la petición. El filtro de imagen de la plantilla espera los bytes y les aplica base64; si mandas un base64 ya codificado, queda codificado dos veces y no se ve. El logo va como archivo en el servidor (Lycet también tiene un endpoint aparte para subirlo).
  • Solo el PDF lee los parámetros extra. Los datos adicionales que quieras imprimir (por ejemplo, qué producto de tu portafolio originó la venta) se pasan al endpoint pdf; no alteran el XML ya firmado.
  • El precio de tu sistema suele ser con IGV. Decide quién separa base e IGV. Entre nosotros lo hace el servicio de facturación (base = total / 1,18 redondeada, IGV = total − base), para que los sistemas no tengan que conocer la fórmula.

Cómo probarlo antes de confiar

  1. Emite en beta una factura, una boleta con su resumen y una nota de crédito, y verifica que cada CDR vuelva con código 0.
  2. Fuerza un rechazo (un dato inválido) y comprueba que tu sistema lo marca y no lo reintenta en bucle.
  3. Simula la pérdida de la respuesta y verifica que consultas el CDR antes de reintentar.
  4. Cobra dos veces el mismo id de transacción y confirma que sale un solo comprobante.
  5. Revisa el PDF y el XML con los datos reales del emisor antes del cambio.

Checklist antes de pasar a producción

  • Sistema de emisión elegido y confirmado con tu contador.
  • Usuario secundario de Clave SOL con permisos de emisión, ya activo.
  • Certificado convertido a PEM (con -legacy si hace falta), fuera de cualquier repositorio, con su vencimiento en el monitoreo.
  • Servicio de firma solo en loopback o red interna, con límites de memoria.
  • Base vaciada de las pruebas en beta.
  • Idempotencia por transacción y correlativo dentro de la transacción de base de datos.
  • Resumen diario programado y alerta si quedan boletas sin enviar.
  • Interpretación del CDR por rangos de código, con consulta antes de reintentar.
  • Todo conectado al monitoreo: un comprobante que no sale es una infracción que crece sola.

Emitir bien es aburrido a propósito: el día que deja de ser aburrido, suele ser porque se rompió el certificado, un duplicado o un resumen rechazado que nadie vio. Lo que se diseña es que alguien se entere.