Documentación para desarrolladores

1. Autenticación

Incluye tu API Key en el header X-API-Key en cada petición. Obtén una desde el panel (regístrate gratis → Dashboard → API Keys) o por API:

# 1) Registro (S/. 5.00 de saldo inicial)
curl -X POST https://apivalidape.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"tu@correo.com","password":"TuClave123!"}'
# → { "success": true, "data": { "user": {...}, "accessToken": "eyJ..." } }

# 2) Crear API Key (con el accessToken del paso anterior)
curl -X POST https://apivalidape.com/api/v1/auth/api-keys \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name":"mi-integracion"}'
# → { "success": true, "data": { "key": "vapi_xxxxxxxxxxxx", ... } }

Guarda la key apenas la crees: por seguridad solo se muestra una vez. Debes verificar tu correo antes de crear keys o consumir servicios.

2. Formato de respuesta

Todas las respuestas vienen en un sobre estándar:

{ "success": true, "data": { /* ... */ }, "meta": { "timestamp": "..." } }

Los servicios que descuentan saldo agregan usage:

{ "success": true, "data": {...}, "usage": { "cost": 0.08, "balanceRemaining": 4.92 }, "meta": {...} }

Errores: 400 datos inválidos/saldo insuficiente · 401 API Key inválida · 404 no encontrado · 429 rate limit.

3. Límites y precios

• Rate limit: 60 req/min por defecto (configurable por plan).
• Saldo: los servicios de consulta descuentan de tu saldo prepago.

4. Consulta DNI

curl https://apivalidape.com/api/v1/dni/44443333 -H "X-API-Key: vapi_xxx"

{ "success": true, "data": {
  "dni": "44443333", "nombres": "LISMELI",
  "apellidoPaterno": "ROMAINA", "apellidoMaterno": "SILVA",
  "nombreCompleto": "ROMAINA SILVA LISMELI"
}, "usage": { "cost": 0.08, "balanceRemaining": 4.92 } }

5. Consulta RUC

curl https://apivalidape.com/api/v1/ruc/20131312955 -H "X-API-Key: vapi_xxx"

{ "success": true, "data": {
  "ruc": "20131312955", "razonSocial": "...", "estado": "ACTIVO",
  "condicion": "HABIDO", "direccion": "...", "ubigeo": "150130"
}, "usage": { "cost": 0.08, "balanceRemaining": 4.84 } }

6. Tipo de cambio

Cotización oficial del dólar (compra/venta SBS/SUNAT, fuente BCRP). Gratis. En fin de semana/feriado devuelve el último día hábil.

# Hoy
curl https://apivalidape.com/api/v1/exchange-rate -H "X-API-Key: vapi_xxx"
# Por fecha (YYYY-MM-DD)
curl https://apivalidape.com/api/v1/exchange-rate/2026-06-20 -H "X-API-Key: vapi_xxx"

{ "success": true, "data": {
  "moneda": "USD", "fecha": "2026-06-20", "fechaSolicitada": "2026-06-20",
  "compra": 3.377, "venta": 3.386, "fuente": "bcrp"
} }

7. Ubigeo / Ubicación

Gratuito. Perú (departamento → provincia → distrito) e internacional (país → estado → ciudad).

curl https://apivalidape.com/api/v1/location/departments -H "X-API-Key: vapi_xxx"
curl https://apivalidape.com/api/v1/location/departments/{departmentId}/provinces -H "X-API-Key: vapi_xxx"
curl https://apivalidape.com/api/v1/location/countries/PE/states -H "X-API-Key: vapi_xxx"

8. Bancos y cajas

Catálogo gratuito por país y tipo (bank, caja_municipal, financiera, wallet…).

curl "https://apivalidape.com/api/v1/banks?country=PE&type=caja_municipal" -H "X-API-Key: vapi_xxx"
curl "https://apivalidape.com/api/v1/banks?search=interbank" -H "X-API-Key: vapi_xxx"

9. Validación de vouchers

curl -X POST https://apivalidape.com/api/v1/voucher/validate \
  -H "X-API-Key: vapi_xxx" -H "Content-Type: application/json" \
  -d '{ "image": "iVBORw0KGgo...", "type": "auto", "expectedAmount": 127.50 }'

Detecta y rechaza vouchers duplicados (por número de operación y hash de imagen). Soporta Yape, Plin y transferencias.

10. Firma digital (IOFE)

Firma de PDF conforme a la Ley Nº 27269 con principio de No Custodia. Flujo de 3 pasos: /signature/prepare → /signature/complete/:id → /signature/verify.

11. Ejemplos por lenguaje

Node.js / TypeScript

const res = await fetch('https://apivalidape.com/api/v1/ruc/20131312955', {
  headers: { 'X-API-Key': process.env.VALIDAPI_KEY },
});
const { data } = await res.json();

Python

import requests
r = requests.get("https://apivalidape.com/api/v1/dni/44443333", headers={"X-API-Key": KEY})
data = r.json()["data"]

PHP

$ch = curl_init("https://apivalidape.com/api/v1/ruc/20131312955");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: vapi_xxx"]]);
$data = json_decode(curl_exec($ch), true)["data"];

12. Buenas prácticas

• Guarda tu API Key como secreto (variables de entorno); nunca en el frontend.
• Cachea de tu lado los datos que no cambian seguido (ubigeo, bancos, tipo de cambio).
• Maneja el 429 con reintentos espaciados (backoff).
• Restringe tu API Key por IP desde el panel.
• Verifica success antes de usar data.

¿Dudas? Escríbenos a soporte@apivalidape.com.