Para programadores · Perú
Ya está hecho, probado contra producción, y es tuyo por S/ 200.
Descarga comprobantes en XML, PDF y CDR, el buzón electrónico, las declaraciones del PDT 621, los recibos por honorarios emitidos y recibidos, la casilla de SUNAFIL, el SIRE, y las consultas de RUC, DNI, domicilio fiscal y establecimientos anexos — con la ficha RUC en PDF.
Todo por HTTP, sin navegador, listo para incorporar al sistema de tu cliente. Con las trampas que no están documentadas en ningún lado y que te pueden costar semanas.
Si estás aquí, probablemente te pasó esto
No son casos raros. Son los cuatro puntos donde se atasca cualquiera que intente integrarse con SUNAT por primera vez, y ninguno está explicado en su documentación. Cada uno cuesta días, y tú tienes un cliente esperando.
Tienes tu client_id, el token se genera bien, y aun así cada consulta
de comprobantes responde 401. Muchos concluyen que SUNAT no lo permite y se rinden.
Lo que pasa: tu aplicación no tiene habilitado el recurso
consultacpe. Sí se puede activar, y se hace por API —
una sola petición que casi nadie conoce.
Guía completa del error 401 →
Copias el ejemplo, mandas usuario y clave correctos, y SUNAT rechaza la petición sin explicar nada.
Lo que pasa: el campo username va con el RUC y el
usuario SOL concatenados, sin separador. No es un dato que esté
escrito en ninguna parte.
Lo ves en el portal, está en tu SIRE, pero la API insiste en que no hay nada.
Lo que pasa: el último parámetro de la URL define desde qué rol consultas. Elegir el equivocado no da un error de permisos: da un 404, que parece otra cosa completamente distinta.
Funciona, luego no, luego otra vez sí. Sin patrón. Empiezas a dudar de tu código.
Lo que pasa: SUNAT devuelve error 500 en cerca de la mitad de las peticiones. Lo medimos con 720 llamadas reales: la tasa es idéntica con 1 petición a la vez que con 10. No es tu servidor, no es tu concurrencia. Es SUNAT.
Qué incluye
No son ejemplos ni documentación: es código que corre. Cada módulo se verificó contra cuentas reales, y lo que no está verificado se declara como tal.
Facturas, boletas y notas: metadata en JSON ya parseada, XML, PDF y CDR. Con el detalle de que en compras el ZIP del XML ya trae el CDR adentro, así te ahorras un tercio de las peticiones.
Habilita consultacpe y los demás recursos en la aplicación del
contribuyente, sin abrir el navegador. Incluye la unión con los permisos existentes:
ese PUT reemplaza la lista completa y sin eso borras permisos en
producción.
Notificaciones y mensajes con su estado de leído, el documento en HTML autocontenido, los adjuntos y el acto administrativo enlazado — la Orden de Pago o la Esquela de verdad, no solo la constancia de depósito. Cómo descargar el buzón por API →
Las declaraciones presentadas por período, sus dos PDF —constancia y detalle—, el desglose por tributo y las 48 casillas del formulario ya separadas. Cargables a tu sistema sin OCR. Cómo descargar el PDT 621 por API →
Emitidos y recibidos, con su PDF y su XML firmado. Sirve para personas naturales y para empresas, que son las que retienen el 8%. Un año completo en una sola consulta. Guía de recibos por honorarios →
Propuestas de ventas y compras, más el flujo asíncrono completo de exportación: solicitar el ticket, consultar su estado y bajar el reporte.
La casilla electrónica: notificaciones de fiscalización, cobranza, acciones previas y alertas. Sin credenciales nuevas — SUNAFIL delega el login en SUNAT, con la misma clave SOL.
RUC, DNI, domicilio fiscal, establecimientos anexos, catálogos y tipo de cambio. Más la ficha RUC en PDF. Directamente usables en una web de cara al usuario.
Lo que de verdad estás comprando
El código se puede escribir. Lo que cuesta semanas es descubrir esto, porque no está en ningún manual y cada una falla de una forma que apunta al lado equivocado:
aud del token, como texto JSON dentro del JWT. El campo apis llega en null: leerlo a él te dice que no tienes permisos aunque los tengas.indEstado = 0 es no leído y 1 es leído. Va al revés de lo que parece, y si lo inviertes muestras toda la bandeja al contrario.Todos no filtra: responde correctamente con la lista vacía, y parece que la empresa nunca declaró.500 no significa que el comprobante no exista. Si tu sistema los marca como perdidos, vas a descartar documentos que sí están.Cada una de estas se descubrió ejecutando contra SUNAT, no leyendo documentación — porque no la hay. Están explicadas en el documento técnico que viene incluido.
Demostración
El recorrido completo contra SUNAT real: configurar credenciales, habilitar los permisos, generar el token y bajar un comprobante con su XML, PDF y CDR. El video está grabado paso a paso para que se vea cada petición; en el proyecto todo esto ya viene automatizado.
Clic para reproducir
Qué llega a tu correo
QUE-CONTIENE-ESTA-ENTREGA.md por dónde empezar
ENTREGA-PARA-COMPRADOR.md cómo autentica SUNAT y dónde están las trampas
README.md instalar y correr algo en 5 minutos
PROMPT-PARA-TU-IA.md pégalo en tu asistente y que lo integre por ti
scripts/ 29 scripts ejecutables, uno por módulo
src/ librería sin dependencias de producción
docs/ contrato de integración y arquitectura
tests/ 73 pruebas, corren sin conexión
ejemplos/ salidas reales con datos anonimizadosPrecio
1. Me escribes por WhatsApp diciendo que lo quieres. 2. Te paso el número de Yape y confirmas el pago. 3. Te envío el archivo al momento.
Respondo yo, no un bot. Lima, Perú.
Preguntas frecuentes
Se consulta el endpoint consultacpe de api-cpe.sunat.gob.pe
indicando RUC del emisor, tipo de documento, serie, correlativo y el origen de la
consulta. El sufijo de la URL define el archivo: /01 para PDF,
/02 para XML y /03 para CDR. Sin sufijo devuelve la metadata
en JSON, ya parseada.
Antes hay que generar un token OAuth2 y tener habilitado el recurso
consultacpe en la aplicación registrada, que es el paso que traba a casi
todo el mundo. En compras conviene saber que el ZIP del XML ya trae el CDR
adentro, así te ahorras un tercio de las peticiones.
Sí, y sin navegador. El buzón usa un mecanismo distinto al de comprobantes: no va con token OAuth2 sino con una sesión de portal, que aquí se abre por HTTP en aproximadamente un segundo.
Tiene dos bandejas separadas, notificaciones y mensajes, y de cada una se baja el documento, sus adjuntos y el acto administrativo enlazado en el cuerpo, que es la Orden de Pago o la Esquela de verdad y no solo la constancia de depósito.
Un aviso importante: pedir el detalle de un mensaje lo marca como leído en SUNAT y eso no se puede deshacer, así que la sincronización debe listar sin abrir.
Sí. Las declaraciones van por e-plataformaunica.sunat.gob.pe y exigen una
cabecera idCache, que es la llave de una sesión de portal y no un token
OAuth2. Ese idCache no se pide a ningún endpoint: viene incrustado en el
menú que devuelve el propio login, y además hay que darlo de alta antes de consultar o
todo responde 401.
Con eso se obtienen las declaraciones presentadas por período, sus dos PDF —constancia y detalle—, el desglose por tributo y las 48 casillas del formulario ya separadas, que para cargar datos en un sistema contable sirven más que el PDF.
Sí, en las dos direcciones: los que el contribuyente emitió y los que le emitieron. Los emitidos aplican a personas naturales; los recibidos sirven también para empresas, que son las que retienen el 8%.
De cada recibo se baja el PDF y el XML firmado, más un listado con la descripción del servicio y los importes ya separados. Los formularios del portal limitan la búsqueda a seis meses o a 32 días, pero esa validación es del navegador: por HTTP se puede pedir un año completo en una sola consulta.
Sí, y no hace falta pedirle nada nuevo al cliente: SUNAFIL no tiene login propio, delega en SUNAT y se entra con la misma clave SOL.
Hay dos diferencias que rompen si se copia el flujo de SUNAT: usa un
client_id propio, y el RUC y el usuario van en campos separados en vez de
concatenados. Se recorren las seis bandejas —fiscalización, cobranza, acciones previas,
alertas de formalización, alertas SST y orientaciones— con su estado de leído y sus
documentos.
Un archivo comprimido con el proyecto completo: el código de los ocho módulos, la documentación técnica de cómo autentica SUNAT y dónde están las trampas, ejemplos de las salidas reales con datos anonimizados, y un prompt listo para pegar en tu asistente de código para que te ayude a integrarlo.
Se descomprime, se instala con npm install y funciona.
Un solo pago te sirve para todos los proyectos que hagas. No se cobra por cliente final ni por instalación. Si eres desarrollador y atiendes a varias empresas, lo usas en todas.
El conector está en Node.js con TypeScript, pero se invoca como un proceso desde cualquier lenguaje. Recibe los datos por variables de entorno, deja los archivos en una carpeta y devuelve un código de salida que distingue si el error fue transitorio o si necesita intervención.
Desde PHP son tres líneas con proc_open. El README trae el ejemplo.
No. Todo funciona con peticiones HTTP puras, incluido el login del portal SOL, que se resuelve en aproximadamente un segundo.
No hace falta Chromium ni xvfb, corre en un VPS pequeño y consume unos
300 MB menos de memoria por cliente que una solución con navegador.
SUNAT cambia cosas y va a volver a hacerlo. El proyecto se entrega tal cual, con el código y la documentación completa para que puedas adaptarlo: el comentario de cada módulo explica cómo se descubrió cada flujo, qué endpoint se usa y qué falla si se cambia.
No incluye soporte personalizado ni mantenimiento por el precio indicado. Prefiero decirlo antes que después.
No. Solo el RUC, usuario y clave SOL de cada contribuyente. Con eso se obtienen el
client_id y el client_secret desde el propio portal de
SUNAT, y el conector incluye el módulo que habilita los permisos de API necesarios.
No hacen falta trámites ni convenios previos.
S/ 200, un solo pago, licencia para todos tus proyectos. Te paso el Yape y te envío el archivo al momento. Si tienes una duda técnica antes de comprar, pregúntala: la respondo yo.
Escribir al +51 972 309 300Lima, Perú · Horario de oficina