Documentación
API Version 1.0.0

Introducción

Bienvenido a la documentación de RUC API FREE. Esta API proporciona acceso en tiempo real al padrón de contribuyentes SUNAT de Perú. Todos los endpoints requieren autenticación Bearer usando tu API_TOKEN del archivo .env.

Autenticación

Todas las solicitudes a la API requieren un encabezado Authorization con tu API_TOKEN definido en el archivo .env.

key Encabezado de Ejemplo 
Authorization: Bearer <your-api-token>

Endpoint de Consulta

Obtén información detallada de un contribuyente usando un número RUC válido de 11 dígitos.

GET /api/ruc/{ruc}

Ejemplo de Solicitud (cURL)

curl -X GET "http://localhost:8000/api/ruc/10452159428" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "ruc": "10452159428",
    "nombre_razon_social": "JUAN PEREZ",
    "estado_contribuyente": "ACTIVO",
    "condicion_domicilio": "HABIDO",
    "ubigeo": "150101",
    "direccion_completa": "AV. LOS OLIVOS 123"
  },
  "timestamp": "2026-07-06T12:00:00",
  "response_time": 0.015
}

Endpoints Adicionales

GET /api/stats

Obtén estadísticas de uso del sistema.

GET /api/status

Estado del sistema y la base de datos.

POST /api/export

Exporta datos de un RUC en formato JSON, CSV o TXT.

Códigos de Error

Código Descripción
401 Token Bearer inválido o ausente.
404 Número de RUC no encontrado en el padrón.
400 Entrada inválida, RUC mal formado o formato incorrecto.
500 Error interno del servidor.