Saltar al contenido principal
Consultas

API de consulta RUC para Perú

Consulta razón social, estado, condición y domicilio fiscal de cualquier RUC de 11 dígitos, con versiones detallada y completa de la ficha tributaria y consulta masiva.

Para qué sirve

  • Autocompletar razón social y dirección fiscal al emitir una factura.
  • Verificar que un proveedor esté ACTIVO y HABIDO antes de registrar su compra.
  • Saber si un cliente es agente de retención o percepción.
  • Depurar el maestro de clientes y proveedores de tu ERP en lote.
  • Validar empresas en el alta de un marketplace o plataforma B2B.

Tres niveles de detalle para un RUC

Elige el endpoint según cuánta información necesites; así cada llamada trae solo lo que vas a usar:

EndpointCuándo usarlo
RUCLo básico para facturar: razon_social, estado, condicion y el objeto domiciliado con dirección, distrito, provincia, departamento y ubigeo.
RUC detalladoAgrega ubicacion (con codUbigeo), contacto (teléfonos registrados) y correos. Un guion - indica que el dato no está registrado.
RUC completoLa ficha tributaria: tipo de contribuyente, nombre comercial, fechas de inscripción e inicio de actividades, actividades económicas, sistemas de emisión, comprobantes electrónicos autorizados, padrones y si es agente de retención o percepción.

La consulta masiva recibe un arreglo rucs y devuelve cantidad y resultados. Si un RUC no se pudo obtener, ese ítem trae un campo error y el resto de la lista se procesa con normalidad.

Cómo leer estado y condición

Son los dos campos que más se revisan. El estado indica si el RUC está vigente (ACTIVO) o no (por ejemplo, de baja o suspendido). La condición de domicilio indica si SUNAT pudo ubicar al contribuyente en su domicilio fiscal (HABIDO) o no (NO HABIDO, entre otras).

Antes de registrar una compra o pagar a un proveedor, es buena práctica comprobar que esté ACTIVO y HABIDO. En la ficha completa, campos como fecha_baja, padrones, agente_retencion y agente_percepcion te ayudan a aplicar el tratamiento tributario correcto; confirma con tu contador cómo aplicarlo en cada caso.

Cómo empezar

  1. Crea tu cuenta gratis en miapi.cloud; el plan gratuito te permite probar sin tarjeta.
  2. Copia tu token desde el panel admin.miapi.cloud.
  3. Envíalo en cada petición en la cabecera Authorization: Bearer TU_TOKEN, siempre por HTTPS.

Prueba con el RUC ficticio 20000000001 para ver la estructura de la respuesta. Luego llama a la API desde tu backend cuando el usuario termine de escribir los 11 dígitos y rellena razón social y dirección.

La cantidad de consultas disponibles depende de tu plan; revisa los planes en miapi.cloud/#planes. Si tienes dudas para integrarla, escríbenos por WhatsApp.

Buenas prácticas e integración con ERP y Excel

  • Valida el formato antes de consultar: 11 dígitos numéricos que empiecen con 10, 15, 16, 17 o 20. Si quieres ir más lejos, verifica también el dígito de control.
  • Usa caché con fecha: guarda la respuesta y vuelve a consultar cuando haya pasado un tiempo razonable o antes de una operación importante, porque el estado y la condición pueden cambiar.
  • Reintenta solo los 5xx con espera progresiva; un RUC inexistente no aparecerá por reintentar.
  • Depura en lote con la consulta masiva: exporta la columna de RUC desde Excel o tu ERP, consúltala por bloques y actualiza las fichas.

Guarda el token en el servidor, en una variable de entorno o en tu gestor de secretos. No lo pongas en el código de una página web ni en una app móvil: cualquiera podría leerlo y gastar tus consultas. Si sospechas que se filtró, genera uno nuevo desde el panel.

Si también facturas a personas naturales, complementa con la API de consulta DNI, y para emitir el comprobante usa la API de facturación electrónica.

Referencia de la API

Todas las peticiones llevan tu token en la cabecera Authorization: Bearer TU_TOKEN. Lo copias desde tu panel en admin.miapi.cloud después de crear tu cuenta gratis. Más detalles en la documentación.

Consulta de datos RUC

Consulta razón social, estado y condición de un RUC de 11 dígitos.

GET https://miapi.cloud/v1/ruc/{numero}

Petición
curl -X GET "https://miapi.cloud/v1/ruc/20000000001" \
  -H "Authorization: Bearer TU_TOKEN"
Respuesta de ejemplo (datos ficticios)
{
  "success": true,
  "datos": {
    "ruc": "20000000001",
    "razon_social": "EMPRESA DE EJEMPLO S.A.C.",
    "estado": "ACTIVO",
    "condicion": "HABIDO",
    "domiciliado": {
      "direccion": "AV. DE EJEMPLO 123",
      "distrito": "LIMA",
      "provincia": "LIMA",
      "departamento": "LIMA",
      "ubigeo": "150101"
    }
  }
}

Consulta RUC Detallado

Devuelve información ampliada del RUC, incluyendo ubicación y datos de contacto.

GET https://miapi.cloud/v1/ruc/det/{numero}

Petición
curl -X GET "https://miapi.cloud/v1/ruc/det/20000000001" \
  -H "Authorization: Bearer TU_TOKEN"
Respuesta de ejemplo (datos ficticios)
{
  "datos": {
    "razon_social": "EMPRESA DE EJEMPLO S.A.C.",
    "estado": "ACTIVO",
    "condicion": "HABIDO",
    "ubicacion": {
      "codUbigeo": "150101",
      "direccion": "AV. DE EJEMPLO 123",
      "departamento": "LIMA",
      "provincia": "LIMA",
      "distrito": "LIMA"
    },
    "contacto": {
      "numTelefono1": "-",
      "numTelefono2": "-",
      "numTelefono3": "51900000000"
    },
    "correos": {
      "codCorreo1": "contacto@ejemplo.com",
      "codCorreo2": "-"
    }
  }
}

Consulta RUC Completo

Devuelve la ficha tributaria más completa disponible para un RUC.

GET https://miapi.cloud/v1/ruc/completo/{numero}

Petición
curl -X GET "https://miapi.cloud/v1/ruc/completo/20000000001" \
  -H "Authorization: Bearer TU_TOKEN"
Respuesta de ejemplo (datos ficticios)
{
  "success": true,
  "datos": {
    "ruc": "20000000001",
    "razon_social": "EMPRESA DE EJEMPLO S.A.C.",
    "tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
    "nombre_comercial": "EMPRESA DE EJEMPLO",
    "fecha_inscripcion": "01/01/2020",
    "fecha_inicio_actividades": "01/01/2020",
    "estado": "ACTIVO",
    "fecha_baja": "",
    "mensaje_estado": null,
    "condicion": "HABIDO",
    "domicilio_fiscal": {
      "direccion": "AV. DE EJEMPLO 123",
      "distrito": "LIMA",
      "provincia": "LIMA",
      "departamento": "LIMA"
    },
    "sistema_emision": "MANUAL/COMPUTARIZADO",
    "actividad_comercio_exterior": "SIN ACTIVIDAD",
    "sistema_contabilidad": "MANUAL/COMPUTARIZADO",
    "actividades_economicas": [
      "Principal    - 4520 - MANTENIMIENTO Y REPARACIÓN DE VEHÍCULOS AUTOMOTORES"
    ],
    "comprobantes_pago": [
      "NINGUNO"
    ],
    "sistema_emision_electronica": [
      "FACTURA PORTAL                      DESDE 01/01/2020"
    ],
    "emisor_electronico_desde": "01/01/2020",
    "comprobantes_electronicos": [
      "FACTURA (desde 01/01/2020)"
    ],
    "afiliado_PLE_desde": "-",
    "padrones": [
      "NINGUNO"
    ],
    "agente_retencion": "NO",
    "agente_percepcion": "NO"
  }
}

Consulta Masiva de RUC

Consulta varios RUC en una sola petición; los inválidos devuelven un error por ítem.

POST https://miapi.cloud/v1/ruc/masivo

Petición
curl -X POST "https://miapi.cloud/v1/ruc/masivo" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rucs":["20000000001","20000000002"]}'
Respuesta de ejemplo (datos ficticios)
{
  "success": true,
  "cantidad": 2,
  "resultados": [
    {
      "ruc": "20000000001",
      "razon_social": "EMPRESA DE EJEMPLO S.A.C.",
      "estado": "ACTIVO",
      "condicion": "HABIDO",
      "domiciliado": {
        "direccion": "AV. DE EJEMPLO 123",
        "distrito": "LIMA",
        "provincia": "LIMA",
        "departamento": "LIMA"
      }
    },
    {
      "ruc": "20000000002",
      "error": "No se pudieron obtener los datos del RUC."
    }
  ]
}

Errores frecuentes

CódigoQué significa
401Token ausente, mal escrito o inválido. Revisa la cabecera Authorization: Bearer TU_TOKEN.
404 / 422El RUC no tiene un formato válido o no se encontraron datos para él. Valida el número antes de consultar y no reintentes el mismo número.
429Alcanzaste el límite de consultas de tu plan o enviaste demasiadas peticiones seguidas. Espera o amplía tu plan.
5xxLa fuente oficial o nuestro servicio no respondió en ese momento. Reintenta con espera progresiva.

Preguntas frecuentes

¿La API RUC es oficial de SUNAT?

No. MiAPI Cloud es un servicio independiente que consulta fuentes públicas oficiales de SUNAT; no está afiliado a SUNAT.

¿Qué diferencia hay entre RUC, RUC detallado y RUC completo?

El básico trae razón social, estado, condición y domicilio. El detallado agrega ubicación, teléfonos y correos registrados. El completo devuelve la ficha tributaria con actividades económicas, sistemas de emisión, comprobantes electrónicos, padrones y agentes de retención o percepción.

¿Puedo consultar muchos RUC a la vez?

Sí. La consulta masiva recibe un arreglo de RUC y devuelve un resultado por cada uno; los que no se pudieron obtener traen un campo error.

¿Hay plan gratuito para la API RUC?

Sí, al registrarte en miapi.cloud tienes un plan gratuito para probar. Los límites dependen de cada plan; revísalos en miapi.cloud/#planes.

¿Cada cuánto debo volver a consultar un RUC?

Depende de tu proceso. Para autocompletar facturas basta con la caché; antes de pagar a un proveedor o de una operación importante conviene consultar de nuevo, porque el estado y la condición pueden cambiar.

APIs relacionadas

Empieza gratis hoy

Crea tu cuenta gratis, copia tu token y haz tu primera consulta en minutos. Sin tarjeta de crédito.