Documentación técnica · Perú
La forma simple de integrarte con las APIs de SUNAT.
Todo lo que hace falta para integrarte con las APIs oficiales de SUNAT, probado contra el servicio real. Incluye 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.
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.
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.
Demostración
El recorrido completo: configurar credenciales, habilitar los permisos, generar el token y bajar un comprobante real con su XML, PDF y CDR.
Clic para reproducir
Qué recibes
El flujo OAuth2 completo, con scripts que guardan el token solo. Y la petición para
habilitar consultacpe en tu aplicación, con la advertencia de que ese
PUT reemplaza la lista completa de recursos en lugar de agregar.
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.
Búsqueda por fechas, descarga de XML y los datos de cabecera para el traslado.
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.
Consulta de declaraciones presentadas y descarga del PDF de la constancia. Incluye la explicación de por qué este módulo funciona distinto a todos los demás.
RUC, DNI, domicilio fiscal, establecimientos anexos, catálogos y tipo de cambio. Directamente usables en una web de cara al usuario.
{
"comprobantes": [{
"datosEmisor": {
"numRuc": "20112273922",
"desRazonSocialEmis": "TIENDAS DEL MEJORAMIENTO DEL HOGAR S.A.",
"desNomComercialEmis": "SODIMAC"
},
"codCpe": "01", "numSerie": "F925", "numCpe": 27044,
"fecEmision": "02/08/2026", "codMoneda": "PEN",
"informacionItems": [
{ "desItem": "Llave expansión Stanley 8", "mtoImpTotal": 42.9 },
{ "desItem": "Juego de llaves hexagonal", "mtoImpTotal": 21.9 }
]
}]
}
Fíjate en informacionItems: SUNAT entrega el detalle línea por línea
ya procesado. No hace falta abrir y parsear el XML para obtener los datos del
comprobante.
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 — ese segundo paso es el que
traba a casi todo el mundo.
Porque tu aplicación registrada no tiene habilitado el recurso
/v1/contribuyente/consultacpe. El token se genera bien, pero no incluye
ese permiso, así que cada consulta rebota.
Se activa con una petición PUT al endpoint de control de acceso de SUNAT.
Ojo con un detalle que cuesta caro: ese PUT reemplaza la lista
completa de recursos, no agrega. Hay que reenviar también los que ya tenías o
los pierdes.
El error más común está en el campo username: SUNAT espera el RUC y el
usuario SOL concatenados, sin separador ni espacios. Un RUC
20123456789 con usuario MODDATOS se envía como
20123456789MODDATOS.
El segundo error frecuente es el scope: tiene que ser el host de la API
que vas a consumir. El token de comprobantes no sirve para el SIRE.
No. Solo el RUC, usuario y clave SOL de la empresa. Con eso obtienes el
client_id y client_secret desde el propio portal de SUNAT,
en la opción Credenciales de API. No hay trámites ni convenios previos.
No. Las APIs oficiales de SUNAT no cobran por descarga. Los servicios de terceros que revenden este acceso sí cobran créditos por cada archivo, y además reciben la clave SOL de tus clientes en sus propios servidores.
Es comportamiento del propio servicio, no de tu código. En pruebas con 720 peticiones
reales, SUNAT devolvió 500 en cerca del 50% de los casos,
con la misma tasa usando una petición a la vez que diez en paralelo.
Con una política de reintentos adecuada se recupera el 100% de las descargas. Y algo
importante para tu diseño: un 500 no significa que el
comprobante no exista.
No. El token va atado al RUC del contribuyente. El parámetro de origen que en teoría
permite consultar cualquier comprobante devuelve 404 incluso con documentos
que sí existen — está probado y documentado. Cada empresa necesita sus propias
credenciales.
En ninguno y en todos. Es una colección de Postman: peticiones HTTP puras que puedes exportar a PHP, Node, Python, C#, Java o lo que uses. Postman te genera el código de cada petición en el lenguaje que elijas.
Parcialmente, y el material es honesto al respecto. Ese módulo de SUNAT usa un mecanismo de sesión distinto que no se puede replicar con el token normal. Está explicado con la razón técnica exacta y qué alternativas quedan.
Escríbeme por WhatsApp y te cuento qué incluye, el precio y cómo se entrega. Respondo yo, no un bot.
Escribir al +51 972 309 300Lima, Perú · Horario de oficina