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. El TC vigente de un día es el cierre SBS del día hábil anterior (igual que SUNAT): la respuesta trae fechaCierre (la jornada) y fechaVigencia(el día para el que rige). 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 de vigencia (YYYY-MM-DD)
curl https://apivalidape.com/api/v1/exchange-rate/2026-06-24 -H "X-API-Key: vapi_xxx"

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

7. Países, regiones y ciudades

Catálogo internacional de ubicaciones (ISO 3166): países → regiones/estados → ciudades. Gratis con tu API Key. Útil para formularios de dirección, validación de datos geográficos y selectores en cascada.

# 1) Países disponibles
curl https://apivalidape.com/api/v1/location/countries -H "X-API-Key: vapi_xxx"

# 2) Regiones/estados de un país (código ISO, ej. PE, MX, CO, AR)
curl https://apivalidape.com/api/v1/location/countries/PE/states -H "X-API-Key: vapi_xxx"

# 3) Ciudades de una región/estado
curl "https://apivalidape.com/api/v1/location/states/{stateId}/cities" -H "X-API-Key: vapi_xxx"

También: /location/states?countryId=…, /location/cities?stateId=… o ?countryId=…, y los detalles por id en /location/countries/{id}, /states/{id} y /cities/{id}.

8. Ubigeo Perú

Jerarquía oficial del Perú: departamento → provincia → distrito (1 874 distritos). Gratis. Incluye validación de código de ubigeo.

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/provinces/{provinceId}/districts -H "X-API-Key: vapi_xxx"
curl "https://apivalidape.com/api/v1/location/validate-ubigeo?code=150101" -H "X-API-Key: vapi_xxx"

9. 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"

10. Validación de vouchers

# Tipos disponibles (claves para modelKey)
curl https://apivalidape.com/api/v1/voucher/models -H "X-API-Key: vapi_xxx"

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

Soporta Yape, Plin, POS y transferencias. La respuesta trae un estado (valid / suspicious / invalid / duplicate), un puntaje de confianza y el detalle de verificaciones (monto, destinatario, antigüedad, número de operación y similitud con vouchers previos).

Para validar que el pago sea a tu cuenta, configura los datos esperados (nombre/empresa/documento/banco/celular/cuenta del receptor) desde el dashboard, en Vouchers → Configuración, y pasa su configId en la petición. Detecta y rechaza duplicados por número de operación y por imagen (idéntica y casi-idéntica).

Para usar en producción (vía API Key) tu configuración debe estar validada: desde Vouchers → Solicitudes subes muestras reales del comprobante y las envías a revisión; una vez aprobada, ya puedes validar en producción con su configId. En el dashboard puedes probar antes, sin esa restricción.

11. Cobros Yape/Plin (checkout)

Cobra con tu Yape o Plin usando el checkout de ValidApi. El dinero va directo a tu cuenta: ValidApi no es pasarela, es un conciliador. El cliente paga, ingresa los datos de su pago (N° de operación, fecha y hora, titular) y ValidApi los compara con el aviso del banco que recibe tu cuenta. El resultado llega a tu sistema por webhook firmado.

1. En el dashboard, Cobros: datos del comercio, URL del webhook y tu Yape/Plin (número, titular y QR).
2. Tu backend crea el pedido con el monto exacto (API Key).
3. Tu web abre el widget (o redirige a checkoutUrl).
4. Tu backend recibe payment.paid y entrega el pedido.

# 1) Crear el pedido (idempotente por "reference")
curl -X POST https://apivalidape.com/api/v1/payments \
  -H "X-API-Key: vapi_xxx" -H "Content-Type: application/json" \
  -d '{ "amount": 49.90, "reference": "PED-10025", "description": "Polo básico", "mode": "test" }'

# → { "id": "pay_…", "status": "pending", "checkoutUrl": "https://apivalidape.com/pay/pay_…", "expiresAt": "…" }

# 2) Consultar el estado (o esperar el webhook)
curl https://apivalidape.com/api/v1/payments/pay_… -H "X-API-Key: vapi_xxx"

# Solo pedidos de prueba: simular el aviso del banco
curl -X POST https://apivalidape.com/api/v1/payments/pay_…/simulate -H "X-API-Key: vapi_xxx"

<!-- 3) Widget en tu web -->
<script src="https://apivalidape.com/checkout.js"></script>
<script>
  ValidApi.checkout({
    paymentId: 'pay_…',
    onPaid: () => mostrarGracias(),   // solo interfaz: la confirmación válida es el webhook
    onClose: (status) => {},
  });
</script>

Estados: pending (esperando pago) → declared (el cliente ingresó sus datos; se espera el aviso del banco) → paid. Si la coincidencia es dudosa queda en review y la resuelves en el dashboard (paid o rejected). Si vence sin pago: expired. Los eventos del webhook son payment.paid, payment.review, payment.expired y payment.rejected.

Firma del webhook: cabecera ValidApi-Signature: t=<unix>,v1=<hex>, donde v1 = HMAC-SHA256(secreto, t + "." + cuerpo_crudo). Verifícala sobre el cuerpo sin re-serializar, compárala en tiempo constante y rechaza t con más de 5 minutos. Responde 2xx: si no, se reintenta (1 min, 5 min, 30 min, 2 h y 6 h).

Producción: requiere que la fuente de avisos de tu Yape/Plin esté verificada (reenvío de correos del banco o app Android). Mientras tanto integra todo con mode: "test". El paso a paso de integración está en el dashboard, en Cobros → Integración.

12. Cotización de envíos

Calcula cuánto cobrar por un envío con tu propio tarifario, que configuras en el dashboard (Envíos) a partir de una plantilla: delivery urbano por km o por tramos, courier nacional por zonas de ubigeo y peso, o movilidad. Sobre el precio base se aplican el vehículo, los recargos (horario nocturno, feriados de Perú, paradas, espera, seguro, contraentrega, zona de difícil acceso…) y tus ajustes (% de margen, monto fijo, mínimo, envío gratis desde un monto, redondeo). La respuesta trae el total con su desglose.

curl -X POST https://apivalidape.com/api/v1/shipping/quote \
  -H "X-API-Key: vapi_xxx" -H "Content-Type: application/json" \
  -d '{
    "origin":      { "lat": -12.1211, "lng": -77.0297 },
    "destination": { "lat": -12.0464, "lng": -77.0428, "ubigeo": "150101" },
    "vehicle": "moto",
    "orderValue": 85.50,
    "options": { "cod": true }
  }'

# → { "data": { "id": "quo_…", "serviceable": true, "total": 17.00, "currency": "PEN",
#               "breakdown": [ { "code": "base.distance_time", "label": "Tarifa por recorrido (11.38 km)", "amount": 15.38 },
#                              { "code": "surcharge.cod", "label": "Contraentrega", "amount": 1.60 },
#                              { "code": "rounding", "label": "Redondeo", "amount": 0.02 } ],
#               "subtotal": 14.41, "tax": 2.59, "distanceKm": 11.38, "durationMin": 31, "expiresAt": "…" },
#     "usage": { "cost": 0.05, "balanceRemaining": … } }

# Verificar una cotización al cerrar la compra (gratis)
curl https://apivalidape.com/api/v1/shipping/quotes/quo_… -H "X-API-Key: vapi_xxx"

# Tus tarifarios, vehículos y qué datos exige cada uno (gratis)
curl https://apivalidape.com/api/v1/shipping/rate-cards -H "X-API-Key: vapi_xxx"

• Distancia: si ya calculas la ruta con tu proveedor de mapas envía route: { distanceKm, durationMin }. Si no, se usa la ruta real por calles (si tu tarifario la activa) o se estima con las coordenadas. Sin coordenadas basta el ubigeo: se usa la capital del distrito. distanceSource indica de dónde salió.
• Tarifarios por zonas requieren el ubigeo de origen y destino (o coordenadas, si tus zonas son polígonos dibujados en el mapa); por peso, packages (weightKg y/o medidas en cm: se cobra el mayor entre el peso real y el volumétrico).
• rateCardId elige el tarifario (por defecto, el predeterminado). scheduledAt (hora de Lima) define los recargos por horario, feriado y lluvia (pronóstico en el origen).
• Cobrar con Yape/Plin: crea el pedido de cobro con shippingQuoteId y ValidApi suma el envío al monto de los productos. Cada cotización sirve para un solo pedido vigente.
• Saldo: cada cotización se descuenta de tu saldo prepago; sin saldo se responde 400. Las fechas sin zona horaria se toman como hora de Perú.
• serviceable: false con reasons = fuera de cobertura (distancia, peso o zona).
• Cobro: se cobra cada cotización calculada, aunque repitas la dirección o quede sin cobertura. Cotiza cuando el cliente confirme sus datos de envío (no en cada tecla) y reutiliza el id mientras esté vigente. Los errores 400 no se cobran.

Guía completa de integración → Inicio rápido, cómo probar, todos los campos, errores, verificación del precio y ejemplos en Node, PHP y Python.

13. 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"];

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