xS

API SUNAT

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.

Endpoints Principales
POST /api/v1/consulta Unificado
GET /api/v1/ruc/{ruc} SUNAT
GET /api/v1/dni/{dni} RENIEC

Respuestas cacheadas ultra rápidas (< 5ms)

Autenticación
Header (Recomendado) Authorization: Bearer <API_KEY>
Header Alternativo / Query X-API-KEY: <API_KEY>

También soporta el parámetro token en el body JSON.

Estructura Estándar JSON
✓ Exitoso: {"success": true, ...}
✗ Error: {"success": false, "error": {"code": "...", "message": "..."}}

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:

¡Copiado!
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

POST /api/v1/consulta
Recomendado

Endpoint inteligente unificado. Detecta automáticamente si el parámetro ingresado corresponde a un RUC (11 dígitos) o DNI (8 dígitos).

Respuesta Éxito (RUC):
{
  "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
}
Respuesta Éxito (DNI):
{
  "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
}
GET / POST /api/v1/ruc/{ruc}

Consulta directa al Padrón Reducido SUNAT. Retorna todos los datos detallados del contribuyente incluyendo desagregado de vías, zonas y departamento.

GET / POST /api/v1/dni/{dni}

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 Codes

Cuando 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.