Checklist técnico para integrar facturación electrónica con SUNAT vía API

El primer request al OSE en sandbox suele funcionar en pocas horas. El primer rechazo en producción llega en los primeros días y generalmente apunta a un problema que estaba presente desde el inicio: un certificado no configurado correctamente, un campo del XML mal calculado o una lógica de fallback que nunca se probó. Este checklist cubre los ocho puntos que deben verificarse antes del despliegue a producción de una integración de facturación electrónica con SUNAT en Perú.

Cada punto incluye la verificación concreta que debe ejecutar el equipo de desarrollo, no solo una lista de conceptos. El orden sigue la secuencia lógica de la integración: desde la obtención del certificado hasta la conciliación de estados en producción.

Punto 1 — Certificado digital XAdES-BES

El certificado digital del emisor debe ser emitido por una Entidad de Certificación para el Estado Peruano (ECEP) acreditada por INDECOPI. Los certificados de entidades internacionales no son aceptados por SUNAT. Verificar: el certificado no está vencido, corresponde al RUC del emisor, la cadena de confianza es válida y no está en la lista de revocación (CRL) del emisor del certificado. Si el PSE firma en nombre del emisor (modelo de delegación), debe existir poder notarial o contrato de representación documentado.

Verificación rápida del certificado

Ejecutar en el entorno de integración: firmar un XML mínimo con el certificado del emisor y enviar al sandbox del OSE. Si el CDR devuelve ResponseCode 0 con ese XML mínimo, el certificado está correctamente configurado. Si el error es 2072 (certificado inválido) o 2073 (certificado revocado), el problema está en el certificado, no en el XML.

Punto 2 — Generación del XML UBL 2.1 con extensiones SUNAT

Validar el XML generado contra el esquema XSD oficial de SUNAT antes de enviarlo al OSE. SUNAT publica los XSD para cada tipo de comprobante en su portal de desarrolladores. Un XML que pasa la validación XSD local tiene alta probabilidad de ser aceptado por el OSE; un XML que falla localmente siempre será rechazado. Verificar especialmente: los namespaces del UBL 2.1, el bloque ext:UBLExtensions con la firma, y los campos obligatorios por tipo de comprobante (01, 03, 07, 08).

Los esquemas XSD oficiales por tipo de comprobante están publicados en el portal de SUNAT.

Cálculo del IGV y totales

El IGV en Perú es 18%. El campo TaxAmount debe coincidir exactamente con BaseAmount * 0.18 redondeado a dos decimales. El campo LineExtensionAmount de cada línea debe sumar al LegalMonetaryTotal/LineExtensionAmount del comprobante. Cualquier descuadre en los cálculos resulta en rechazo con código 3034 o similar. Validar los cálculos con al menos tres casos: línea única, múltiples líneas con redondeo y línea con descuento.

Punto 3 — Nomenclatura y empaquetado del archivo

El archivo ZIP debe nombrarse exactamente como: RUC-TipoDoc-Serie-Correlativo.zip. El XML dentro del ZIP debe tener exactamente el mismo nombre con extensión .xml. Errores comunes: correlativo con ceros de relleno insuficientes (debe ser 8 dígitos: 00000001), tipo de documento con formato incorrecto (debe ser 01, 03, 07 u 08 con dos dígitos), espacios o caracteres especiales en el nombre del archivo.

Punto 4 — Conexión y autenticación con el OSE

Los OSEs usan autenticación por credenciales SOL (Sistema de Operaciones en Línea de SUNAT) o por credenciales propias del OSE según su implementación. Verificar que las credenciales configuradas son las del emisor (RUC + clave SOL del emisor), no las del PSE. Un error común es usar las credenciales del PSE para emitir comprobantes de clientes, lo que resulta en rechazo por emisor no autorizado.

La administración de credenciales SOL del emisor se realiza desde el portal SOL de SUNAT.

Punto 5 — Manejo del CDR: estados y acciones

El sistema debe manejar los tres estados del CDR de forma diferenciada. Aceptado (ResponseCode 0): almacenar el CDR, marcar el comprobante como válido, notificar al emisor. Observado: almacenar el CDR, registrar el código de observación para revisión, el comprobante es válido aunque tiene advertencias. Rechazado: registrar el código de error, determinar si el número de serie es reutilizable, notificar al equipo técnico con el detalle del error. Un sistema que trata Rechazado como Observado expone al emisor a sanciones de SUNAT.

Punto 6 — Control de numeración y series

La numeración en Perú es por serie (F001, F002...) y correlativo secuencial. No se puede reutilizar un número de comprobante Aceptado. Un número Rechazado puede reutilizarse, pero esto debe manejarse explícitamente en la base de datos del PSE. El sistema debe tener un mecanismo de bloqueo optimista o transaccional para evitar que dos procesos concurrentes generen el mismo número de comprobante. En ambientes de alta concurrencia, esto es la fuente más común de rechazos por numeración duplicada.

Punto 7 — Fallback al canal directo de SUNAT

El canal de contingencia debe estar implementado y probado antes de salir a producción, no después de la primera caída del OSE. Verificar que el endpoint de SUNAT está configurado, que las credenciales SOL del emisor funcionan directamente contra SUNAT, y que el sistema detecta automáticamente el timeout del OSE (recomendado: 10-15 segundos) y redirige sin intervención manual. Probar el fallback desconectando manualmente el OSE en el entorno de staging.

Punto 8 — Almacenamiento y retención del CDR

SUNAT exige conservar el comprobante electrónico (XML firmado) y el CDR asociado por un mínimo de 5 años. El almacenamiento debe ser inmutable: una vez guardado el CDR de un comprobante Aceptado, no debe poder modificarse. Implementar un hash del XML y del CDR almacenados para detectar cualquier modificación posterior. El PSE debe proveer al emisor acceso a sus CDRs históricos ante una auditoría de SUNAT.

Preguntas frecuentes

¿Cuál es el timeout recomendado para detectar falla del OSE y activar el fallback?

Para integraciones de punto de venta o checkout donde el usuario espera la respuesta, 10 segundos es el máximo tolerable antes de activar el fallback. Para procesos batch en segundo plano, se puede esperar hasta 30 segundos antes de marcar el intento como fallido y redirigir. El timeout debe configurarse por tipo de operación, no ser un valor único global.

¿Cómo puedo probar el flujo completo en sandbox antes de ir a producción?

Usar el RUC de prueba 20000000001 con la clave SOL de homologación que provee SUNAT para el entorno de beta. La mayoría de OSEs tienen un endpoint de sandbox que acepta este RUC de prueba y devuelve CDRs firmados reales. Ejecutar los 8 puntos del checklist en sandbox antes de solicitar el cambio a producción: certificado con RUC real, XML válido, fallback probado, y al menos un caso de Rechazado intencional para verificar el manejo de errores.

¿Qué diferencia hay entre un error del OSE y un error de SUNAT en la respuesta?

Los errores del OSE son propios de cada operador y suelen tener códigos en el rango 0100-0999 según la implementación del OSE. Los errores de SUNAT aparecen en el CDR con códigos en el rango 1000-3999 definidos en el Anexo Técnico de SUNAT. Un error 2072 es siempre de SUNAT (certificado inválido); un error de conexión al endpoint del OSE es del OSE. El PSE debe manejar ambas categorías con rutas de reintento y escalación diferentes.

¿Es posible integrar sin implementar la firma XAdES-BES directamente?

Sí, si el PSE delega la firma al OSE. Algunos OSEs ofrecen un modelo donde el PSE envía el XML sin firmar y el OSE aplica la firma usando el certificado que el emisor depositó previamente. Este modelo simplifica la implementación del PSE pero requiere un acuerdo contractual que autorice al OSE a firmar en nombre del emisor. Verificar que el OSE que se va a usar ofrece este modelo antes de diseñar la integración sin módulo de firma propio.

Para el contexto del modelo de facturación electrónica en Perú, ver la guía para ISVs sobre SUNAT, OSE y UBL 2.1. Para diagnóstico detallado de rechazos, ver errores comunes al integrar con el webservice de SUNAT.