API para integradores

Valwisp expone una API REST pensada para que sistemas externos (tu ERP, un bot de mensajería, una red de cobro, tu propio portal) se integren con tu ISP sin tocar el dashboard. Es una API distinta de la que usa internamente el dashboard/app móvil — más pequeña, más estable, y con su propio modelo de autenticación pensado para terceros.

Cómo leer esta sección: cada grupo de endpoints trae una etiqueta — 🟢 Disponible (ya puedes usarlo hoy) o 🟡 Próximamente (está especificado y en construcción, todavía no responde en producción). Esta sección documenta el diseño completo de la API, incluyendo lo que está en camino, para que puedas planificar tu integración con anticipación.

Base URL

https://api.valwisp.com/api/v1/external

Todas las rutas de esta sección cuelgan de ese prefijo — distinto del que usa el dashboard internamente, para que un cambio en la app web nunca rompa tu integración.

Autenticación

Cada tenant genera API keys desde Ajustes → API en el dashboard 🟡. Una key se envía como header estándar, nunca en el cuerpo de la petición:

Authorization: Bearer vw_live_51H8x...

• Cada key tiene un scope: read (solo lectura) o write (lectura + escritura), y puede limitarse a recursos específicos (por ejemplo, una key que solo pueda crear pagos, sin acceso a clientes).
• Las keys son revocables individualmente y no expiran salvo que las revoques — pero puedes configurar expiración automática si tu integración lo requiere.
• Hay un entorno de sandbox (https://api.valwisp.com/api/v1/external/sandbox) con datos de prueba, para integrar sin tocar clientes reales.

Formato de respuesta

Igual que el resto de la plataforma — una sola forma de respuesta en toda la API, sin excepciones por endpoint:

// Éxito
{ "success": true, "data": { ... }, "timestamp": "2026-08-05T14:00:00.000Z" }

// Error
{ "success": false, "message": "Cliente no encontrado", "statusCode": 404, "timestamp": "2026-08-05T14:00:00.000Z" }

Paginación

Todo endpoint de listado usa el mismo esquema, sin importar el recurso:

GET /clients?page=1&limit=25

{
  "success": true,
  "data": {
    "data": [ ... ],
    "total": 342,
    "page": 1,
    "limit": 25,
    "pages": 14
  }
}

Límites de uso

🟡 300 peticiones/minuto por API key. Al superarlo, la API responde 429 Too Many Requests con un header Retry-After. Si tu integración necesita más volumen (por ejemplo, una conciliación masiva), contáctanos para ajustar el límite de tu tenant.

Idempotencia

Los endpoints de escritura que registran dinero (pagos, reversos) aceptan un identificador externo (referencia_externa o secuencial, según el endpoint) para que reintentar la misma petición no duplique el efecto — ver Pagos externos.

El ciclo de vida de un suscriptor

Un cliente no se crea directamente por API. Existe un único camino, en orden:

Registro  →  Instalación  →  Cliente

Ver Registro para el detalle completo de por qué está diseñado así.

Grupos de endpoints

¿Vienes migrando desde otro sistema? Los nombres de recursos usan inglés en la URL (/clients, /invoices) siguiendo la convención REST estándar, pero toda la documentación está en español.