Campos de la respuesta RUC
El contrato de DatosPerú publica ruc, razon_social, estado, condicion, direccion, departamento, provincia, distrito y ubigeo. Solo debes asumir la presencia de los campos marcados como obligatorios en OpenAPI; el resto puede depender de la fuente.
Conserva el RUC como una cadena de once dígitos. Un RUC con formato válido todavía puede no existir o no estar disponible en la fuente. Por eso debes distinguir validación de entrada, consulta exitosa y ausencia de resultados.
Estado, condición y domicilio no significan lo mismo
El estado del contribuyente y su condición son campos distintos. Si tu proceso necesita aceptar solo determinados estados, define la regla de negocio de forma explícita y permite revisar el resultado. No conviertas cualquier respuesta HTTP 200 en una aprobación automática de un proveedor.
El domicilio fiscal ayuda a completar información empresarial. No sustituye la confirmación de una dirección de entrega ni acredita que una persona tenga facultades para actuar por una empresa. Para otros datos empresariales existen endpoints separados.
Consultas empresariales relacionadas
El catálogo incluye representantes legales, establecimientos anexos, domicilio fiscal, deuda coactiva, trabajadores y búsqueda por razón social. Cada consulta tiene su propia ruta y esquema: usa el endpoint específico cuando necesites esos datos.
También puedes consultar el RUC asociado a un DNI mediante /api/v1/dni-ruc. No todas las personas tienen un resultado disponible; prepara tu aplicación para atender ese caso sin construir un RUC por suposición.
Integra desde PHP, Python, Node.js o tu ERP
Envía una solicitud POST /api/v1/ruc con el campo ruc y el token en la cabecera Authorization. Revisa tanto el código HTTP como success, y utiliza meta.request_id para identificar una consulta ante soporte. El contrato OpenAPI permite generar clientes o importar las operaciones en tus herramientas.
Para autocompletar un checkout o formulario HTML, usa el proxy del servidor y limita quién puede consultarlo. Evita disparar una consulta por cada tecla: valida los once dígitos y realiza la petición cuando la persona la solicite. DatosPerú no requiere publicar tu token en el navegador.
Preguntas frecuentes
¿Puedo buscar una empresa por razón social?
Sí, existe un endpoint separado en el catálogo. La consulta por RUC exige el número de once dígitos.
¿Cada campo está siempre disponible?
No. La cobertura depende de la fuente y los campos opcionales pueden faltar o ser nulos.
¿Es un servicio oficial de SUNAT?
DatosPerú es un servicio privado e independiente; sus consultas utilizan el proveedor JSON.pe.