API de RUC
La ficha del contribuyente, del padrón oficial de SUNAT
Estado, condición, ubigeo y actividad económica de 18.4 millones de contribuyentes, del padrón que SUNAT publica cada día. Cada respuesta dice de qué fecha es el dato.
curl https://nexoid.victorllerena.com/id/v1/ruc/20131312955 \
-H "Authorization: Bearer $NEXOID_TOKEN"{
"success": true,
"data": {
"ruc": "20131312955",
"tipo": "20",
"nombre": "SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA",
"estado": "ACTIVO",
"condicion": "HABIDO",
"ubigeo": "150131",
"distrito": "SAN BORJA",
"actividad_economica": "ADMINISTRACION PUBLICA"
},
"meta": { "origen": "padron_reducido_sunat", "fecha_dato": "2026-09-27" }
}Endpoints
GET /id/v1/ruc/{ruc}
La ficha de un RUC · desde el plan gratis
GET /id/v1/ruc/buscar?q=…
Búsqueda por razón social, solo empresas · desde Micro
POST /id/v1/ruc/batch
Hasta 100 RUC por petición, con Idempotency-Key · desde Micro
GET /id/v1/proveedor/{ruc}
El alta de proveedor: la ficha, los padrones de SUNAT, si está inhabilitado por el Estado y avisos, en una consulta · desde el plan gratis
Los RUC que empiezan en 10, 15 o 17 son personas naturales. Su nombre es un dato de identidad y exige un contrato de tratamiento de datos: sin él, la consulta responde 403. La búsqueda por razón social solo devuelve empresas.
Qué devuelve
| Campo | Qué es | De dónde sale | Presente en |
|---|---|---|---|
| ruc | El RUC consultado | Padrón reducido · SUNAT, diario | siempre |
| tipo | 20 es persona jurídica | Padrón reducido · SUNAT, diario | siempre |
| nombre | La razón social | Padrón reducido · SUNAT, diario | siempre |
| estado | ACTIVO, BAJA DE OFICIO, SUSPENSIÓN TEMPORAL… | Padrón reducido · SUNAT, diario | siempre |
| condicion | HABIDO o NO HABIDO | Padrón reducido · SUNAT, diario | siempre |
| ubigeo | Código INEI de seis dígitos | Padrón reducido · SUNAT, diario y Padrón de datos abiertos · SUNAT, mensual | 82.6 % de las fichas |
| departamento · provincia · distrito | Los nombres del ubigeo | Catálogo de ubigeo · INEI | con el ubigeo |
| tipo_contribuyente | Sociedad anónima, EIRL… | Padrón de datos abiertos · SUNAT, mensual | 72.8 % |
| sistema_emision | Cómo emite sus comprobantes | Padrón de datos abiertos · SUNAT, mensual | 70.1 % |
| actividad_economica | Su actividad principal | Padrón de datos abiertos · SUNAT, mensual | 52.8 % |
| comercio_exterior | Si importa, exporta o las dos cosas, como lo escribe SUNAT | Padrón de datos abiertos · SUNAT, mensual | 72.7 % |
| nro_trabajadores | Cuántos trabajadores declaró: 0 es cero, null es que no lo trae | Padrón de datos abiertos · SUNAT, mensual | 3.3 % |
| direccion | El domicilio fiscal, cuando SUNAT lo publica | Padrón reducido · SUNAT, diario | 13.2 % |
| es_agente_retencion | Si es agente de retención del IGV: al pagarte, te retiene el 3 % | Padrón de agentes de retención · SUNAT | siempre, con su fecha |
| es_buen_contribuyente | Si está en el régimen de buenos contribuyentes | Relación de buenos contribuyentes · SUNAT | siempre, con su fecha |
| meta.fecha_dato · meta.origen | De qué padrón y de qué día sale la ficha | NexoID | siempre |
| meta.fecha_padrones | De qué día es cada lista de SUNAT de los dos campos de arriba | NexoID | siempre |
Preguntas frecuentes
¿Qué es el alta de proveedor?
Una consulta que junta lo que un área de compras revisa antes de dar de alta a una empresa: la ficha, si es agente de retención o buen contribuyente según SUNAT, si está inhabilitada para contratar con el Estado según el OSCE, si ya la vigilas, y avisos en palabras simples. Cuesta lo mismo que una ficha, y es solo para empresas (RUC 20).
¿Es una consulta en vivo a SUNAT?
No. Es el padrón oficial que SUNAT publica cada día, descargado cada madrugada. Por eso responde rápido y por eso te decimos la fecha del dato en meta.fecha_dato.
¿Por qué la dirección viene tan pocas veces?
Porque el padrón público de SUNAT la trae completa solo en el 13.2 % de los contribuyentes. No la inventamos ni la completamos con otra fuente: el departamento, la provincia y el distrito sí vienen en el 82.6 %.
¿Qué pasa con un RUC que no existe?
Responde 404 con encontrado: false, y esa consulta no se cobra.
¿Puedo consultar muchos RUC a la vez?
Sí: POST /ruc/batch acepta hasta 100 por petición. Con la cabecera Idempotency-Key, si repites el mismo lote recibes la misma respuesta sin consultar dos veces.