Guía de Integración & Documentación API
Integra la API de Consulta de RUC (SUNAT) y DNI (RENIEC) en tus aplicaciones de forma simple y eficiente. Respuestas estandarizadas en formato JSON, altísima velocidad con Redis y soporte multi-lenguaje.
Respuestas cacheadas ultra rápidas (< 5ms)
También soporta el parámetro token en el body JSON.
Codificación UTF-8 con códigos de error claros en español.
Ejemplos de Integración por Lenguaje
Consulta unificada (RUC o DNI) con la fachada Http de Laravel:
use Illuminate\Support\Facades\Http; $token = 'TU_API_KEY_AQUI'; $response = Http::withToken($token) ->post("https://tu-dominio.com/api/v1/consulta", [ 'documento' => '20606224274' // 11 dígitos para RUC u 8 dígitos para DNI ]); if ($response->successful()) { $resultado = $response->json(); if ($resultado['success']) { echo $resultado['tipo'] === 'ruc' ? $resultado['razon_social'] : $resultado['nombre_completo']; } } else { $error = $response->json()['error']; echo "Error [" . $error['code'] . "]: " . $error['message']; }
Detalle de Endpoints y Estructura de Datos
Endpoint inteligente unificado. Detecta automáticamente si el parámetro ingresado corresponde a un RUC (11 dígitos) o DNI (8 dígitos).
{
"success": true,
"tipo": "ruc",
"ruc": "20606224274",
"razon_social": "EMPRESA EJEMPLO S.A.C.",
"estado": "ACTIVO",
"condicion": "HABIDO",
"ubigeo": "150101",
"direccion": "AV. JAVIER PRADO ESTE NRO. 123",
"execution_time_ms": 2.15
}
{
"success": true,
"tipo": "dni",
"dni": "70654321",
"nombres": "JUAN CARLOS",
"apellido_paterno": "PEREZ",
"apellido_materno": "RODRIGUEZ",
"nombre_completo": "JUAN CARLOS PEREZ RODRIGUEZ",
"codigo_verificacion": "9",
"execution_time_ms": 1.84
}
Consulta directa al Padrón Reducido SUNAT. Retorna todos los datos detallados del contribuyente incluyendo desagregado de vías, zonas y departamento.
Consulta de personas por DNI contra el padrón interno con fallback en tiempo real hacia RENIEC.
Gestión y Códigos de Error Estandarizados
HTTP Status CodesCuando ocurre un inconveniente con la solicitud, la API responde con un código HTTP correspondiente y la siguiente estructura JSON uniforme:
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Se requiere un Token de API válido en Authorization: Bearer o X-API-KEY."
}
}
| Código HTTP | Código Error (code) |
Descripción / Causa |
|---|---|---|
| 401 Unauthorized | UNAUTHORIZED | No se envió la cabecera de autenticación o el token está ausente. |
| 401 Unauthorized | INVALID_TOKEN | El Token de API proporcionado es incorrecto, fue inhabilitado o ha expirado. |
| 403 Forbidden | SUBSCRIPTION_EXPIRED | La suscripción o licencia del usuario asociado al token se encuentra vencida o inactiva. |
| 429 Too Many Requests | QUOTA_EXCEEDED | Se ha consumido la totalidad de consultas permitidas en el plan mensual. |
| 400 Bad Request | INVALID_DOCUMENT / INVALID_RUC / INVALID_DNI | El formato del número de RUC (11 dígitos) o DNI (8 dígitos) es inválido. |
| 404 Not Found | NOT_FOUND | El número de documento consultado no figura en el padrón de SUNAT o RENIEC. |
| 500 Internal Error | SERVER_ERROR | Error interno de servidor durante el procesamiento de la consulta. |