Documentación del API · ConsultadeRUC.pe

Autenticación

El API es cerrada. Cree su cuenta, elija un plan y genere un token desde el panel de usuario. El token se muestra una sola vez: guárdelo. Envíelo en cada consulta en la cabecera Authorization.

Un token sin plan activo recibe 403. El plan Gratis se activa solo al verificar el correo; los de pago los activa la pasarela al confirmar el cobro. Las cuotas y los precios de cada plan están en Precios.

Cabeceras

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Consultar un RUC

GET /api/v1/ruc/{ruc}

Devuelve la ficha completa del contribuyente tal como la publica SUNAT. El RUC debe tener 11 dígitos, empezar por 10, 15, 16, 17 o 20 y llevar un dígito verificador válido; si no, se responde 422 sin consultar los datos.

Parámetros

ruc string · en la ruta · requerido

11 dígitos con dígito verificador válido.

Cabeceras de límite

X-RateLimit-Limit 20000

Consultas mensuales que incluye el plan.

X-RateLimit-Remaining 7520

Consultas que quedan en el mes en curso.

Retry-After 37

Sólo en el 429 de ráfaga: segundos hasta el reintento.

Petición

curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     https://consultaderuc.pe/api/v1/ruc/20536066528

Respuesta

200 OK

{
  "success": true,
  "data": {
    "ruc": "20536066528",
    "razon_social": "INTIMEDIA  S.A.C.",
    "estado": "ACTIVO",
    "condicion_domicilio": "HABIDO",
    "direccion": "CAL. GERMAN SCHEREIBER NRO. 276 URB. SANTA ANA",
    "ubigeo": "150131",
    "departamento": "Lima",
    "provincia": "Lima",
    "distrito": "San Isidro",
    "detalle_direccion": {
      "tipo_via": "CAL.",
      "nombre_via": "GERMAN SCHEREIBER",
      "codigo_zona": "URB.",
      "tipo_zona": "SANTA ANA",
      "numero": "276",
      "interior": null,
      "lote": null,
      "departamento": null,
      "manzana": null,
      "kilometro": null
    },
    "locales_anexos_total": 0,
    "perfil": {
      "tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
      "actividad_economica": "OTRAS ACTIVIDADES DE INFORMATICA",
      "actividad_economica_secundaria": null,
      "actividad_economica_ciiu4": "OTRAS ACTIVIDADES DE TECNOLOGIA DE LA INFORMACION Y DE SERVICIOS INFORMATICOS",
      "nro_trabajadores": 3,
      "tipo_facturacion": "MANUAL",
      "tipo_contabilidad": "MANUAL/COMPUTARIZADO",
      "comercio_exterior": "IMPORTADOR/EXPORTADOR",
      "periodo": "202607"
    },
    "agente_igv": {
      "fecha_corte": "2026-08-27",
      "designaciones": []
    },
    "comprobantes_electronicos": {
      "fecha_corte": "2026-08-27",
      "tipos": [
        { "tipo": "factura", "descripcion": "Factura electrónica", "primera_emision": "2018-09-20" },
        { "tipo": "boleta_venta", "descripcion": "Boleta de venta electrónica", "primera_emision": "2018-09-20" }
      ]
    },
    "sistemas_emision": {
      "fecha_corte": "2026-08-27",
      "sistemas": [
        {
          "sistema": "sistemas_del_contribuyente",
          "descripcion": "Desde sistemas del contribuyente",
          "incorporacion": "autorizado desde",
          "desde": "2018-09-20"
        }
      ]
    },
    "obligado_see_ose": { "listados": [] }
  },
  "padron": { "actualizado_el": "2026-09-03" }
}

Campos que pueden venir en null

perfil es null cuando SUNAT no publica ese perfil para el RUC (le falta a unos 5 millones de contribuyentes). direccion es null si SUNAT no publica ninguna parte de la dirección, y departamento/provincia/distrito lo son si SUNAT publica un ubigeo que aún no está en el catálogo (el código sí se devuelve). En las personas naturales (RUC que empiezan por 10, 15 y 17) no mostramos el domicilio: direccion, ubigeo, departamento/provincia/distrito y cada campo de detalle_direccion vienen siempre en null, locales_anexos_total en 0 y /anexos devuelve una lista vacía. Dentro de perfil, cada campo individual es null cuando SUNAT lo reporta como «NO DISPONIBLE»; las claves siempre están presentes para que el contrato JSON sea estable.

agente_igv es null sólo si todavía no se ha cargado ninguna relación de agentes: no se sabe, y no se disfraza de negativa. Con la relación cargada, designaciones vacío significa que el RUC no es agente de retención ni de percepción a esa fecha de corte. comprobantes_electronicos y sistemas_emision siguen la misma regla.

⚠️ obligado_see_ose.listados vacío no significa que el RUC no esté obligado a usar un OSE: SUNAT publica listados anuales de nuevos obligados, sin bajas y sin el grupo original. Sólo la presencia en un listado es una afirmación.

Vigencia de los datos

padron.actualizado_el es la fecha de la última importación completa de los datos publicados por SUNAT. El bloque perfil lleva su propio periodo (AAAAMM), que es el del perfil publicado por SUNAT.

locales_anexos_total es el número de establecimientos anexos declarados (0 en la mayoría de los RUC). El detalle de cada local se pide aparte, en /api/v1/ruc/{ruc}/anexos.

agente_igv sale de la relación de agentes de retención y percepción del IGV que SUNAT publica cada mes, y lleva su propia fecha_corte. Cada designación trae tipo (retencion, percepcion_venta_interna o percepcion_hidrocarburos), descripcion, desde (AAAA-MM-DD) y resolucion, que SUNAT publica vacía en unos pocos agentes de percepción por hidrocarburos.

comprobantes_electronicos.tipos son los comprobantes que el contribuyente ha emitido alguna vez, con la fecha de la primera emisión (primera_emision, que puede ser null): no dice que siga emitiéndolos ni que esté obligado. sistemas_emision son los sistemas de emisión electrónica a los que está afiliado o autorizado, con el texto de SUNAT en incorporacion. obligado_see_ose lista cada aparición en los listados de nuevos obligados de cpe.sunat.gob.pe, con su fecha y su norma.

Establecimientos anexos

GET /api/v1/ruc/{ruc}/anexos

Los locales que el contribuyente declara ante SUNAT además de su domicilio fiscal (sucursales, almacenes, oficinas administrativas). Vienen paginados porque no son pocos: hay contribuyentes con más de dos mil locales. Cada página cuenta una consulta de la cuota.

Parámetros

ruc string · en la ruta · requerido

Mismo formato que en la consulta por RUC; si no es válido se responde 422 sin consumir cuota.

page entero · opcional

Página a devolver. Por defecto 1.

per_page entero · opcional

Locales por página. Por defecto 20, máximo 50.

Lista vacía no es lo mismo que 404

Un RUC que existe en los datos publicados por SUNAT y no declara ningún local responde 200 con data: [] y meta.total: 0 — es el caso de la mayoría de los contribuyentes. El 404 se reserva para un RUC que no figura en los datos publicados por SUNAT.

El ubigeo es el del local y no tiene por qué coincidir con el del domicilio fiscal: para eso están los anexos.

Petición

curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     "https://consultaderuc.pe/api/v1/ruc/20100017491/anexos?page=1"

Respuesta

200 OK

{
  "data": [
    {
      "ubigeo": "120701",
      "departamento": "Junín",
      "provincia": "Tarma",
      "distrito": "Tarma",
      "direccion": "JR. LIMA NRO. 536",
      "detalle": {
        "tipo_via": "JR.",
        "nombre_via": "LIMA",
        "codigo_zona": null,
        "tipo_zona": null,
        "numero": "536",
        "kilometro": null,
        "interior": null,
        "lote": null,
        "departamento": null,
        "manzana": null
      }
    }
  ],
  "links": {
    "first": "https://consultaderuc.pe/api/v1/ruc/20100017491/anexos?page=1",
    "last":  "https://consultaderuc.pe/api/v1/ruc/20100017491/anexos?page=127",
    "prev": null,
    "next": "https://consultaderuc.pe/api/v1/ruc/20100017491/anexos?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 127,
    "path": "https://consultaderuc.pe/api/v1/ruc/20100017491/anexos",
    "per_page": 20,
    "to": 20,
    "total": 2540
  },
  "success": true,
  "padron": { "actualizado_el": "2026-09-03" }
}

Buscar por nombre

GET /api/v1/buscar

Búsqueda por razón social sobre el índice de texto completo de razones sociales. Devuelve resultados por relevancia, paginados.

Parámetros

q string · requerido

Texto a buscar, entre 3 y 100 caracteres. Cada palabra se exige con comodín final (peru encuentra PERUANA).

page entero · opcional

Página a devolver. Por defecto 1.

per_page entero · opcional

Resultados por página. Por defecto 20, máximo 50.

Cómo se limpia el término

Los operadores del motor de texto completo (+ - < > ( ) ~ " * @) se descartan, igual que el resto de la puntuación. Si tras esa limpieza no queda ninguna palabra de al menos 3 letras, la respuesta es 200 con la lista vacía. Un q de 11 dígitos se busca como texto: para consultar un RUC use /api/v1/ruc/{ruc}.

meta incluye además el arreglo links con las páginas numeradas, tal como lo publica el paginador de Laravel.

Petición

curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     "https://consultaderuc.pe/api/v1/buscar?q=intimedia&page=1"

Respuesta

200 OK

{
  "data": [
    {
      "ruc": "20536066528",
      "razon_social": "INTIMEDIA  S.A.C.",
      "estado": "ACTIVO",
      "ubigeo": "150131",
      "departamento": "Lima",
      "provincia": "Lima",
      "distrito": "San Isidro"
    }
  ],
  "links": {
    "first": "https://consultaderuc.pe/api/v1/buscar?q=intimedia&page=1",
    "last":  "https://consultaderuc.pe/api/v1/buscar?q=intimedia&page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://consultaderuc.pe/api/v1/buscar",
    "per_page": 20,
    "to": 1,
    "total": 1
  },
  "success": true,
  "padron": { "actualizado_el": "2026-09-03" }
}

Códigos de error

Todos los errores devuelven JSON con la misma forma — {"success": false, "error": "…"} —, más los campos extra que aporte cada caso.

HTTP

error

Cuándo pasa

401

No autenticado

Falta la cabecera Authorization, o el token no existe o fue revocado.

403

Plan pendiente de activación

La cuenta no tiene plan, o el plan todavía no se ha activado.

404

RUC no encontrado

El RUC es válido pero no figura en los datos publicados por SUNAT. Consume una consulta.

422

(mensaje de validación)

RUC mal formado o «q» inválida. Añade «errores» con el detalle por campo. No consume cuota.

429

Cuota mensual agotada

Se agotó el plan del mes. Añade «plan», «cuota» y «periodo».

429

Demasiadas consultas por minuto

Se superó el límite de ráfaga. Añade «limite_por_minuto» y la cabecera Retry-After.

Ejemplo · 429

{
  "success": false,
  "error": "Cuota mensual agotada",
  "plan": "developer",
  "cuota": 20000,
  "periodo": "2026-09"
}

Cuotas y límites

La cuota es mensual y se reinicia el día 1 a las 00:00 (hora de Lima). Cada respuesta trae cuánto queda en X-RateLimit-Remaining. Al agotarla, el API responde 429 con el plan, la cuota y el período; el plan no se suspende y las consultas web siguen libres. Las cuotas de cada plan están en Precios.

Límite de ráfaga

Además de la cuota mensual hay un tope de 60 consultas por minuto y por token, para proteger el servicio. Al superarlo se responde 429 con Retry-After; esas consultas no descuentan cuota mensual.

Qué consume cuota

Cada consulta por RUC, cada página de anexos y cada búsqueda descuentan una unidad. Una consulta con el RUC mal formado (422) no consume: se responde antes de contar. Un RUC bien formado que no existe en los datos publicados por SUNAT (404) sí consume, porque obliga a buscar en la tabla.