Guía técnica · SUNAT · Perú
Error 401 en consultacpe:
el token está bien, falta el permiso.
La causa real y la solución exacta, probadas contra el servicio de SUNAT.
Generas el token OAuth2, responde 200, lo guardas — y cada consulta de
comprobantes devuelve 401 Unauthorized. No es tu código ni tus credenciales.
Es un permiso que falta y que SUNAT no explica en ningún lado. Aquí está el porqué y el
cómo.
La causa
Tu aplicación no tiene habilitado consultacpe
El token OAuth2 se genera bien, pero no incluye el recurso
/v1/contribuyente/consultacpe. Por eso cada llamada a comprobantes rebota
con 401, aunque el login sea correcto. El error parece de autenticación, pero el
problema está en los permisos de la aplicación registrada, no en el
token.
Es el punto donde se rinde casi todo el mundo: muchos concluyen que SUNAT no permite consultar comprobantes por API y abandonan. Sí se permite — solo hay que activar el recurso, y se hace por API con una sola petición.
Cómo se resuelve
El recurso se habilita por API — pero con cuidado
consultacpe se activa con una petición al servicio de control de acceso de
SUNAT: le indicas a tu aplicación que ese recurso queda habilitado, y a partir de ahí el
token empieza a incluir el permiso. En concepto es simple. En la práctica hay tres
detalles que no están documentados y que hacen perder días — o, peor, permisos en
producción:
- La operación reemplaza la lista completa de recursos, no agrega. Si la haces "a lo directo" habilitando solo
consultacpe, borras todos los demás permisos que la aplicación ya tenía. Hay que leer primero lo que hay y enviar la unión — un paso que casi nadie sabe que existe hasta que rompe algo. - Falta un identificador en el envío y SUNAT crea una aplicación nueva en vez de actualizar la tuya, dejándote con dos y ninguna bien.
- Al verificar, un campo del token engaña. Después de habilitar, si consultas los permisos por donde parece lógico, te dice que tienes cero — aunque sí los tengas. Los permisos reales están en otro lugar del token, y hay que pedir uno nuevo para verlos. Ese solo detalle cuesta una tarde entera.
Si no quieres pelear con esto
Ya está resuelto, y con todo lo demás de SUNAT
Este 401 es solo el primero de los muros. Después vienen el token que no se genera, el
404 que parece que el comprobante no existe, y el 500 que SUNAT
devuelve la mitad de las veces. Todo eso está resuelto y probado en un proyecto listo
para incorporar a tu sistema:
- Onboarding de permisos automático: habilita
consultacpey los demás recursos con la unión correcta, sin borrar nada. - Comprobantes: XML, PDF y CDR, con la metadata ya parseada.
- Buzón electrónico, PDT 621, recibos por honorarios, SIRE, SUNAFIL y ficha RUC.
- Sin navegador: login en 1 segundo, corre en cualquier VPS. Se invoca desde PHP, Python, Java o lo que uses.
S/ 200, un solo pago, licencia para todos tus proyectos. Te ahorra las semanas que cuesta descubrir todo esto por tu cuenta.
Preguntas frecuentes
Lo que todo el mundo pregunta sobre el 401
¿Por qué la API de SUNAT me devuelve 401 en consultacpe si el token se genera bien?
Porque tu aplicación registrada no tiene habilitado el recurso
consultacpe. El token OAuth2 se genera correctamente, pero no incluye ese
permiso, así que cada consulta de comprobantes rebota con 401 Unauthorized. La solución
no está en el login: hay que habilitar el recurso en la aplicación, no reintentar el
token.
¿Cómo se habilita el recurso consultacpe en la aplicación de SUNAT?
Se habilita por API, con una petición al servicio de control de acceso de SUNAT que le indica a tu aplicación qué recursos quedan permitidos. El detalle crítico que no está documentado: esa operación reemplaza la lista completa de recursos, no agrega. Por eso hay que leer primero los recursos que ya tienes y enviarlos junto con el nuevo, o los pierdes.
¿Por qué después de habilitar consultacpe perdí otros permisos que ya tenía?
Porque la operación de control de acceso de SUNAT reemplaza la lista completa
de recursos, no agrega. Si habilitas solo consultacpe, borras
todos los demás. Es la trampa que hace perder permisos en producción: hay que leer los
recursos actuales y enviar la unión de esos más el nuevo.
¿Cómo confirmo que consultacpe ya quedó habilitado?
Pide un token nuevo y revisa los permisos que trae. Cuidado con una lectura falsa que cuesta horas: hay un campo del token que parece contener los permisos pero viene vacío, y los reales están en otro lugar. Además el token viejo conserva los permisos anteriores hasta que caduca, así que hay que pedir uno nuevo para ver el cambio.
¿Lo quieres resuelto hoy?
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.