Buenas prácticas
Recomendaciones para integrar la API con seguridad, ahorrar créditos y resistir fallos: validación previa, caché, reintentos, límites, datos personales y cuidado del token.
Valida antes de consultar
- RUC: 11 dígitos, empieza en 10, 15, 16, 17 o 20 y el último dígito es un verificador (módulo 11).
- DNI: 8 dígitos, con los ceros a la izquierda.
- Ubigeo: 6 dígitos.
Si el formato está mal, la API responde 422 sin costo, pero te ahorras la llamada y la espera. Guías: Cómo validar un RUC con el dígito verificador y Validar RUC y DNI en frontend y backend.
Guarda en caché lo que cambia poco
- RUC y DNI: los datos de un contribuyente o de una persona cambian poco. En la mayoría de sistemas basta refrescarlos cada cierto tiempo o cuando el usuario lo pida.
- Tipo de cambio: es un valor por día. Consúltalo una vez y reutilízalo durante el día.
- Ubigeo: la tabla es estable. Guarda las listas de departamentos, provincias y distritos para tus formularios.
Ahorras créditos y tu sistema sigue respondiendo aunque la API esté fuera de alcance un momento. Guía: Caché de consultas RUC y DNI.
Reintentos y tiempos de espera
- Reintenta solo los errores 5xx y los de red, con una espera creciente y un tope de intentos.
- Nunca reintentes un 404 ni un 422: el resultado será el mismo.
- Define un timeout en tu cliente HTTP y trátalo como un error 5xx.
Guía: Manejo de errores y reintentos al consumir APIs.
Límites
No hay un tope de peticiones por segundo aparte de tu saldo de créditos. Aun así, consulta desde tu servidor y no desde cada navegador de tus usuarios, y evita bucles que repitan la misma consulta: cada 200 descuenta un crédito.
Datos personales
La consulta de DNI devuelve los nombres y apellidos de una persona, y la de representantes legales, los de quienes representan a una empresa. Úsalas con una finalidad legítima (validar la identidad de un cliente, completar un formulario con su consentimiento, debida diligencia), guarda solo lo necesario y protégelo según la Ley N.º 29733, Ley de Protección de Datos Personales. Guía: Ley de protección de datos personales para desarrolladores.
El token
- Guárdalo en el servidor, en variables de entorno o en un gestor de secretos; nunca en el frontend ni en el repositorio.
- Una clave por sistema o entorno. Rota sin cortes: crea la nueva, despliega y recién entonces revoca la anterior.
- Si se filtra, revócala de inmediato desde el panel.
Guía: Seguridad de tokens de API: buenas prácticas.
Prepárate para campos nuevos
Lee los campos de data por nombre, ignora los que no conozcas y trata null como "sin dato". Así tu integración no se rompe si una respuesta incorpora campos adicionales. La versión de la API va en la ruta (/v1).