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:
| Endpoint | Cuándo usarlo |
|---|---|
| RUC | Lo básico para facturar: razon_social, estado, condicion y el objeto domiciliado con dirección, distrito, provincia, departamento y ubigeo. |
| RUC detallado | Agrega ubicacion (con codUbigeo), contacto (teléfonos registrados) y correos. Un guion - indica que el dato no está registrado. |
| RUC completo | La 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
- Crea tu cuenta gratis en miapi.cloud; el plan gratuito te permite probar sin tarjeta.
- Copia tu token desde el panel admin.miapi.cloud.
- 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}
curl -X GET "https://miapi.cloud/v1/ruc/20000000001" \
-H "Authorization: Bearer TU_TOKEN"const respuesta = await fetch("https://miapi.cloud/v1/ruc/20000000001", {
method: "GET",
headers: {
"Authorization": "Bearer TU_TOKEN"
},
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/v1/ruc/20000000001");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN"
],
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.get(
"https://miapi.cloud/v1/ruc/20000000001",
headers={
"Authorization": "Bearer TU_TOKEN"
},
timeout=30,
)
print(respuesta.json()) {
"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}
curl -X GET "https://miapi.cloud/v1/ruc/det/20000000001" \
-H "Authorization: Bearer TU_TOKEN"const respuesta = await fetch("https://miapi.cloud/v1/ruc/det/20000000001", {
method: "GET",
headers: {
"Authorization": "Bearer TU_TOKEN"
},
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/v1/ruc/det/20000000001");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN"
],
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.get(
"https://miapi.cloud/v1/ruc/det/20000000001",
headers={
"Authorization": "Bearer TU_TOKEN"
},
timeout=30,
)
print(respuesta.json()) {
"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}
curl -X GET "https://miapi.cloud/v1/ruc/completo/20000000001" \
-H "Authorization: Bearer TU_TOKEN"const respuesta = await fetch("https://miapi.cloud/v1/ruc/completo/20000000001", {
method: "GET",
headers: {
"Authorization": "Bearer TU_TOKEN"
},
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/v1/ruc/completo/20000000001");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN"
],
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.get(
"https://miapi.cloud/v1/ruc/completo/20000000001",
headers={
"Authorization": "Bearer TU_TOKEN"
},
timeout=30,
)
print(respuesta.json()) {
"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
curl -X POST "https://miapi.cloud/v1/ruc/masivo" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"rucs":["20000000001","20000000002"]}'const respuesta = await fetch("https://miapi.cloud/v1/ruc/masivo", {
method: "POST",
headers: {
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"rucs": [
"20000000001",
"20000000002"
]
}),
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/v1/ruc/masivo");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"rucs" => [
"20000000001",
"20000000002"
]
]),
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.post(
"https://miapi.cloud/v1/ruc/masivo",
headers={
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
json={
"rucs": [
"20000000001",
"20000000002"
]
},
timeout=30,
)
print(respuesta.json()) {
"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ódigo | Qué significa |
|---|---|
401 | Token ausente, mal escrito o inválido. Revisa la cabecera Authorization: Bearer TU_TOKEN. |
404 / 422 | El 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. |
429 | Alcanzaste el límite de consultas de tu plan o enviaste demasiadas peticiones seguidas. Espera o amplía tu plan. |
5xx | La 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
-
API DNI
Obtén nombres, apellidos y domicilio a partir de un DNI de 8 dígitos y valida la identidad de tus clientes desde tu propio sistema, uno por uno o en lote.
-
API Validar Comprobante
Comprueba ante SUNAT si una factura, boleta o nota que recibiste está aceptada, y consulta los comprobantes emitidos y recibidos de tu RUC desde tu sistema.
-
API Facturación Electrónica
Emite facturas y boletas electrónicas desde tu propio software: envías los datos en JSON, generamos y firmamos el XML y lo enviamos a SUNAT.
Empieza gratis hoy
Crea tu cuenta gratis, copia tu token y haz tu primera consulta en minutos. Sin tarjeta de crédito.