Guía técnica · SUNAT · Perú
Notificaciones y mensajes, con sus documentos, en un segundo por cliente.
Casi todos automatizan el buzón SOL con Selenium o Playwright: lento, frágil, se cae solo y en un servidor necesita Chromium. Se puede hacer con HTTP puro, con login en un segundo — pero hay tres trampas que, si no las conoces, te hacen perder días o le borran datos a tu cliente. Aquí están.
Lo primero que hay que entender
Los comprobantes se descargan con un token OAuth2 (Bearer). El buzón no: usa una sesión de portal SOL — las mismas cookies que tendría un navegador tras iniciar sesión. Por eso el que intenta usar su token de comprobantes contra el buzón recibe siempre error: son dos mecanismos de autenticación distintos.
La buena noticia: esa sesión se abre por HTTP puro, sin navegador. Hay documentación por ahí que afirma que "el WAF de SUNAT lo bloquea y hace falta un navegador". Es falso. El login funciona por HTTP, y en aproximadamente un segundo.
El buzón tiene dos bandejas que se consultan por separado: notificaciones (las que tienen valor legal) y mensajes. No es la misma consulta con un filtro — son dos llamadas distintas.
Las tres trampas
Pedir el detalle de una notificación la marca como leída en SUNAT, de forma irreversible. No existe operación para volver a marcarla como no leída.
La consecuencia: si tu sincronización automática abre cada mensaje para leerlo, le borra al cliente el estado de "no leído" de toda su bandeja. El cron debe solo listar; el detalle, solo cuando una persona abre el mensaje de verdad.
El indicador de leído/no leído de SUNAT vale lo contrario de lo que cualquiera asumiría al verlo.
La consecuencia: si lo interpretas de la forma obvia, muestras toda la bandeja al revés — y no te das cuenta hasta que un cliente lo nota. Y ojo: ese estado de SUNAT es poco fiable, así que conviene llevar el "visto por tu equipo" en tu propio sistema.
Cada notificación trae la constancia de depósito (el acuse, ~85 KB) y, enlazado en el cuerpo, el acto administrativo de verdad: la Orden de Pago, la Esquela, la Resolución (104 a 364 KB).
La consecuencia: si solo guardas la constancia, archivas el sobre y tiras la carta. El documento que importa es el enlazado, y se baja con una petición distinta a la del adjunto.
Un detalle que casi nadie cuida
El HTML del cuerpo de una notificación trae las imágenes (el logo de SUNAT, las bandas)
por ruta relativa, y no declara su codificación. Guardado tal cual, se ve roto fuera del
portal y con las tildes cambiadas (ArtÃculo).
Para un archivo con valor legal eso importa: hay que incrustar las imágenes
como data: URI y forzar el charset, para que el documento quede
autocontenido y se abra idéntico dentro de cinco años, aunque SUNAT cambie sus rutas.
Si no quieres pelear con esto
El buzón es solo uno de ocho módulos de un proyecto listo para incorporar a tu sistema, probado contra SUNAT en producción:
S/ 200, un solo pago, licencia para todos tus proyectos.
Preguntas frecuentes
Sí. El buzón usa un mecanismo distinto al de comprobantes: no va con token OAuth2 sino con una sesión de portal SOL, que se abre por HTTP puro en aproximadamente un segundo, sin Chromium ni Selenium. Tiene dos bandejas separadas, notificaciones y mensajes, que se consultan por separado. De cada una se descarga el documento, sus adjuntos y el acto administrativo enlazado en el cuerpo.
Sí, y no se puede deshacer. Pedir el detalle de una notificación la marca como leída en SUNAT, sin vuelta atrás. Por eso la sincronización automática debe solo listar (sin abrir el detalle) para no borrarle al cliente el estado de no leído. El detalle se pide únicamente cuando una persona abre el mensaje de verdad.
Porque el indicador de leído del buzón vale lo contrario de lo que uno asumiría al verlo: el valor que parece leído significa no leído, y viceversa. Confundirlo hace que se muestre toda la bandeja al revés. Además, el estado de lectura de SUNAT es poco fiable, así que conviene llevar el estado de leído en tu propio sistema.
Trae ambos, y hay que distinguirlos. Cada notificación tiene la constancia de depósito (el acuse, ~85 KB) y, enlazado en el cuerpo, el acto administrativo de verdad: la Orden de Pago, la Esquela o la Resolución (104 a 364 KB). El documento importante es el segundo. El HTML del cuerpo se puede guardar autocontenido, con las imágenes incrustadas, para que se abra igual dentro de años sin depender de SUNAT.
S/ 200, un solo pago, licencia para todos tus proyectos. Te paso el Yape y te envío el proyecto al momento. Si tienes una duda técnica antes de comprar, pregúntala: la respondo yo.
Escribir al +51 972 309 300Lima, Perú · Respondo yo, no un bot.