Guía rápida

Documentación de la API

Autenticación por API Key, endpoints REST o por parámetros, baja latencia y límites por plan.

Iniciar sesión Crear cuenta

Inicio rápido (3 pasos)

  1. Regístrate y obtén tu API Key en el panel.
  2. Incluye la API Key en X-API-KEY o como ?api_token=.
  3. Realiza tu primera llamada al endpoint deseado.
curl -H "X-API-KEY: TU_KEY" "https://peruapi.com/api/tipo_cambio"
Tip: si pruebas desde el navegador, usa la variante con ?api_token=.

Latencia y disponibilidad

Endpoints optimizados para respuesta rápida y consistencia de datos. Diseñados para integrarse con tus flujos de onboarding, facturación y conciliación contable sin fricción.

Autenticación

En cabecera HTTP (X-API-KEY):

GET /api/dni/12345678
X-API-KEY: TU_KEY

O mediante querystring:

GET /api.php?json=dni&id=12345678&api_token=TU_KEY

Seguridad

  • API Key única por usuario, con reset desde el panel.
  • Control por IP según plan (Free: 2 · Pro: 10 · Business: ilimitadas).
  • Registros de uso y trazabilidad de llamadas.

Parámetros permitidos

NombreDóndeTipo / ValidaciónObligatorioDescripción
X-API-KEY Cabecera Cadena (32–128), caracteres visibles Sí* API Key del usuario. Alternativa: ?api_token= en querystring.
api_token Query Cadena (32–128) Sí* Usar si no envías cabecera X-API-KEY.
json Query Enum: ruc | dni | tipo_cambio Depende Solo en el modo api.php por parámetros. En REST no se usa.
id Query RUC: 11 dígitos · DNI: 8 dígitos Depende Requerido para json=ruc y json=dni. No aplicable a tipo_cambio.
fecha Query Date · Formato: yyyy-mm-dd Depende** Requerido para json=tipo_cambio. No aplicable a ruc o dni.
*Es obligatorio proveer API Key ya sea en cabecera (X-API-KEY) o en query (?api_token=).
** Si no se envía, se asume la fecha del día (hoy).
En el modo REST (/api/ruc/{ruc}, /api/dni/{dni} y /api/tipo_cambio) no se usa json ni id por query.

Endpoints

RUC
GET /api/ruc/{ruc}?api_token=TU_KEY
GET /api.php?json=ruc&id={ruc}&api_token=TU_KEY
Respuesta (ejemplo):
{
  "ruc": "20100017491",
  "razon_social": "INTEGRATEL PERÚ S.A.A.",
  "estado": "ACTIVO",
  "condicion": "HABIDO",
  "direccion": "JR. DOMINGO MARTINEZ LUJAN NRO. 1130",
  "ubigeo": "150141",
  "departamento": "LIMA",
  "provincia": "LIMA",
  "distrito": "SURQUILLO",
  "fecha_actualizacion": "2025-09-02 03:18:59",
  "mensaje": "OK",
  "code": "200"
}
DNI
GET /api/dni/{dni}?api_token=TU_KEY
GET /api.php?json=dni&id={dni}&api_token=TU_KEY
Respuesta (ejemplo):
{
  "dni": "60012345",
  "cliente": "QUISPE PEREZ JULIO FERNANDO",
  "nombres": "JULIO FERNANDO",
  "apellido_paterno": "QUISPE",
  "apellido_materno": "PEREZ",
  "mensaje": "OK",
  "code": "200"
}
Tipo de cambio
GET /api/tipo_cambio?api_token=TU_KEY
GET /api.php?json=tipo_cambio&api_token=TU_KEY
Respuesta (ejemplo):
{
  "fecha": "27/03/2025",
  "compra": "3.764",
  "venta": "3.773",
  "moneda": "USD",
  "fuente": "SUNAT",
  "mensaje": "OK",
  "code": "200"
}

Ejemplo PHP (cURL)

<?php
$token = 'TU_KEY';
$ruc   = '20100017491';
$url   = 'https://peruapi.com/api/ruc/'.$ruc;

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['X-API-KEY: '.$token],
  CURLOPT_TIMEOUT        => 8
]);

$res = curl_exec($ch);
if ($res === false) { http_response_code(502); exit; }
curl_close($ch);
header('Content-Type: application/json; charset=utf-8');
echo $res;

Ejemplo cURL / JS

curl "https://peruapi.com/api/dni/60012345" \
  -H "X-API-KEY: TU_KEY"
// Browser/Node (fetch)
const res = await fetch("https://peruapi.com/api/tipo_cambio", {
  headers: { "X-API-KEY": "TU_KEY" }
});
const data = await res.json();
console.log(data);

Límites por plan

  • Free: 100/día · 1000/mes · 2 IPs · Rate-limit 30 rpm
  • Pro: 500/día · 10000/mes · 10 IPs · Rate-limit 150 rpm
  • Business: 5000/día · 100000/mes · IPs ilimitadas · Rate-limit 400 rpm
Consulta tu consumo en tiempo real desde el panel de control.

IPs autorizadas

La primera IP se asocia automáticamente al usar la API (si hay cupo libre). Puedes administrar la lista de IPs permitidas en tu panel según tu plan.

Respuestas y errores

200 · OK
{"mensaje":"OK","code":"200","...":"..."}
Todo correcto
La solicitud fue procesada y se devolvieron datos válidos.
400 · Parámetros inválidos
{"mensaje":"Parámetros inválidos","code":"400"}
¿Por qué puede fallar?
  • Faltan parámetros requeridos (json o id en api.php por query).
  • Formato inválido (RUC ≠ 11 dígitos, DNI ≠ 8 dígitos, json desconocido).
  • Se envía id cuando no aplica (p. ej. tipo_cambio).
401 · No autorizado
{"mensaje":"Token inválido o plan inactivo","code":"401"}
{"mensaje":"IP xxx.xxx.xxx.xxx no autorizada para este token","code":"401"}
¿Por qué puede fallar?
  • No se envió API Key (ni en X-API-KEY ni en ?api_token=).
  • API Key inválida o plan inactivo.
  • La IP de origen no está en tu allowlist y no hay cupos para autorregistro.
404 · No encontrado
{"mensaje":"No encontrado","code":"404"}
¿Por qué puede fallar?
  • El RUC/DNI no existe en el padrón local ni en la fuente de respaldo.
  • Actualización reciente aún no sincronizada.
  • Error temporal en la fuente externa sin datos válidos.
429 · Límite alcanzado
{"mensaje":"Cuota excedida (daily/monthly)","code":"429"}
¿Por qué puede fallar?
  • Superaste el límite diario o mensual de tu plan.
  • Uso concurrente desde varios sistemas con la misma API Key.
  • Procesos que no aplican caché en tu lado.
503 · Servicio no disponible
{"mensaje":"Service not available","code":"503"}
¿Por qué puede fallar?
  • La fuente externa (p. ej. SUNAT para tipo de cambio) no respondió.
  • Mantenimiento o incidente temporal del proveedor.
  • Timeouts de red; aplica reintentos con backoff.

Buenas prácticas

  • Configura timeouts y reintentos con backoff exponencial.
  • Evita llamadas repetitivas; aplica cacheo en tu sistema cuando sea posible.
  • Registra el request-id que uses y correlaciónalo con tus logs internos.
  • Respeta los límites por plan y monitorea el consumo desde el panel.
Crear cuenta Ver planes
¿Tienes dudas? Contáctanos · Revisa el estado del servicio