Ir al contenido
WISPA

Versión 1

API de WISPA

Conecta tu web, tu app o tu sistema con WISPA. HTTPS y JSON.

Empezar

Cada ISP tiene su propia dirección de API: es el dominio de su WISPA.

Dirección base 
https://TU-DOMINIO/api/v1
  1. Crea un token en WISPA (abajo).
  2. Manda el token en la cabecera Authorization.
  3. Recibes JSON.
Primera llamada 
curl "https://TU-DOMINIO/api/v1/clientes/buscar?q=garcia" \
  -H "Authorization: Bearer TU_TOKEN"

Autenticación

La API usa un token personal por aplicación. Lo creas tú, con los permisos justos.

Crear un token

  1. Entra a WISPA como administrador.
  2. Abre Ajustes › API y tokens.
  3. Pon un nombre, elige cuándo vence (30 días, 90 días, 1 año o nunca) y marca los permisos que necesitas.
  4. Pulsa Generar y copia el token. Se muestra una sola vez.

Usarlo

Cabeceras 
Authorization: Bearer TU_TOKEN
Accept: application/json
  • Solo se acepta Authorization: Bearer. Otras cabeceras, como X-Token, no sirven.
  • El token nunca puede más que el usuario que lo creó: hereda sus permisos y sus zonas.
  • Cada endpoint pide un permiso. Si falta, responde 403.
  • Para quitar el acceso a una aplicación, revoca su token en la misma pantalla. Deja de servir al instante.
  • Guarda el token en el servidor de tu aplicación, nunca en una página web ni en una app que se instale en celulares.

Respuestas y errores

Siempre JSON en UTF-8, con ok en true o false.

Éxito 
{
  "ok": true,
  "data": { ... },
  "meta": { ... }
}
Error 
{
  "ok": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "No tienes permiso para buscar clientes.",
    "details": { ... }
  }
}

meta y details solo aparecen cuando hay algo que decir. Para decidir qué hacer, lee error.code; el message es para personas.

CódigoHTTPCuándo
UNAUTHENTICATED401Falta el token, está mal escrito, venció o fue revocado.
FORBIDDEN403El token no tiene el permiso que pide ese endpoint.
VALIDATION_ERROR422Falta un dato o tiene un formato incorrecto. El mensaje dice cuál.
NOT_FOUND404El recurso no existe en tu empresa.
IDEMPOTENCY_KEY_REQUIRED422Falta la cabecera Idempotency-Key.
IDEMPOTENCY_CONFLICT409Esa Idempotency-Key ya se usó con otro contenido.
INVALID_DOCUMENT422El DNI o el RUC no tiene un formato válido.
DOCUMENT_ALREADY_REGISTERED409El documento ya es de un cliente. Trae su id en details.
DOCUMENT_NOT_FOUND404El documento es válido, pero no se encontraron datos.
INTEGRATION_DISABLED503La empresa no activó la consulta de DNI y RUC.
RATE_LIMITED429Demasiadas consultas seguidas. Espera un minuto.
INTERNAL_ERROR500Error nuestro. Reintenta; si sigue, escríbenos.

Límites

  • Buscar clientes: hasta 30 resultados por llamada.
  • Consultar documentos: 40 consultas por minuto por usuario; hasta 10 de ellas al proveedor externo. Al pasarte, 429.
  • Notificaciones: de 1 a 10 intentos por mensaje; Idempotency-Key de 8 a 190 caracteres.
  • Tokens: vencen cuando tú lo decides, o nunca.
  • Por ahora no hay un tope general de llamadas por token. Haz las pausas razonables que harías con cualquier servicio.

Endpoints

GET Buscar clientes

/clientes/buscar

Busca por nombre, código, DNI/RUC o teléfono. Trae lo justo para elegir a un cliente.

Permiso del token: customers.view

Parámetros

NombreTipoObligatorioQué es
qtextoSíLo que buscas. Mínimo 2 caracteres. Coincide con cualquier parte.
limitnúmeroNoCuántos resultados. De 1 a 30. Por defecto 20.

Ejemplo

curl 
curl "https://TU-DOMINIO/api/v1/clientes/buscar?q=garcia&limit=2" \
  -H "Authorization: Bearer TU_TOKEN"

Respuestas

200 · Éxito 
{
  "ok": true,
  "data": {
    "items": [
      {
        "id": 42,
        "code": "C0000042",
        "display_name": "Ana K. G. H.",
        "doc_type": "DNI",
        "doc_number": "••••0793",
        "phone": "•••••3429",
        "address": null,
        "zone_id": null,
        "zone_name": null,
        "has_contract": 1
      },
      {
        "id": 85,
        "code": "C0000085",
        "display_name": "Andrea V. P. G.",
        "doc_type": "DNI",
        "doc_number": "••••1160",
        "phone": "•••••0062",
        "address": null,
        "zone_id": null,
        "zone_name": null,
        "has_contract": 1
      }
    ]
  },
  "meta": { "query": "garcia", "count": 2 }
}
422 · Búsqueda muy corta 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Escribe al menos 2 caracteres para buscar."
  }
}
  • has_contract vale 1 si el cliente tiene un contrato activo o por instalar.
  • Si el usuario que creó el token está limitado a ciertas zonas, solo verás clientes de esas zonas.
  • En el ejemplo, los nombres, documentos y teléfonos van enmascarados.

GET Consultar un DNI o RUC

/documentos/consultar

Devuelve el nombre o la razón social de un documento, con la conexión DNI/RUC que tu empresa activó en WISPA.

Permiso del token: customers.manage

Parámetros

NombreTipoObligatorioQué es
tipotextoSíDNI o RUC.
numerotextoSíDNI de 8 dígitos o RUC de 11.
contexttextoNoDéjalo vacío para solo consultar. Con customers, si hay datos, WISPA registra al cliente sin contrato y responde 409 con su id.

Ejemplo

curl 
curl "https://TU-DOMINIO/api/v1/documentos/consultar?tipo=DNI&numero=12345678" \
  -H "Authorization: Bearer TU_TOKEN"

Respuestas

200 · DNI encontrado 
{
  "ok": true,
  "data": {
    "tipo": "DNI",
    "numero": "12345678",
    "nombre": "JUAN CARLOS PEREZ QUISPE",
    "direccion": "AV. LOS ANDES 123, ICA",
    "estado": "",
    "condicion": ""
  },
  "meta": { "cached": true, "source": "cache" }
}
200 · RUC encontrado 
{
  "ok": true,
  "data": {
    "tipo": "RUC",
    "numero": "20601234565",
    "nombre": "SERVICIOS DEMO S.A.C.",
    "direccion": "JR. COMERCIO 450, ICA",
    "estado": "ACTIVO",
    "condicion": "HABIDO"
  },
  "meta": { "cached": true, "source": "cache" }
}
422 · Formato incorrecto 
{
  "ok": false,
  "error": {
    "code": "INVALID_DOCUMENT",
    "message": "El DNI debe tener 8 dígitos."
  }
}
409 · Ya es cliente (con context=customers) 
{
  "ok": false,
  "error": {
    "code": "DOCUMENT_ALREADY_REGISTERED",
    "message": "Este documento ya está registrado para el cliente: Ana K. G. H.",
    "details": {
      "resource": "customer",
      "resource_id": 42,
      "archived": false,
      "code": "C0000042",
      "doc_masked": "••••0793"
    }
  }
}
503 · Conexión DNI/RUC apagada 
{
  "ok": false,
  "error": {
    "code": "INTEGRATION_DISABLED",
    "message": "La consulta automática no está configurada. Completa los datos a mano."
  }
}
  • meta.source es cache si WISPA ya lo tenía guardado o provider si lo pidió al proveedor.
  • Límite: 40 consultas por minuto por usuario; de ellas, 10 pueden ir al proveedor externo.
  • No es la consulta oficial de RENIEC ni de SUNAT: sirve para completar el nombre. Revísalo antes de guardar.
  • Los datos del ejemplo son ficticios.

POST Crear una notificación

/notificaciones

Pone un correo o un WhatsApp en la cola de envío. La API solo lo encola: WISPA lo envía con la conexión de tu empresa.

Permiso del token: notifications.manage

Cabeceras

NombreObligatoriaQué es
Idempotency-KeySíTexto único de 8 a 190 caracteres por mensaje. Si reintentas con la misma, no se duplica.
Content-TypeSíapplication/json

Cuerpo JSON

NombreTipoObligatorioQué es
channeltextoSíemail o whatsapp. WhatsApp exige el módulo encendido en WISPA.
recipienttextoSíCorreo, o teléfono de 8 a 15 dígitos para WhatsApp.
bodytextoSíEl mensaje.
subjecttextoNoAsunto, hasta 190 caracteres (correo).
customer_idnúmeroNoId de un cliente de tu empresa.
invoice_idnúmeroNoId de una factura de tu empresa.
template_idnúmeroNoPlantilla de WhatsApp de tu empresa. Solo con whatsapp.
variablesobjetoNoValores para la plantilla.
origintextoNogeneral (por defecto), manual_admin, pos_confirmation, technician_event, billing o due_reminder. Los tres primeros salen de inmediato; billing y due_reminder se reparten desde las 9:00.
scheduled_atfechaNoCuándo enviar, por ejemplo 2026-11-02 09:00:00.
max_attemptsnúmeroNoReintentos, de 1 a 10. Por defecto 5.

Ejemplo

curl 
curl -X POST "https://TU-DOMINIO/api/v1/notificaciones" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recibo-octubre-0042" \
  -d '{
    "channel": "email",
    "recipient": "cliente@example.com",
    "subject": "Aviso de WISPA",
    "body": "Hola, tu recibo de octubre ya está disponible.",
    "customer_id": 42
  }'

Respuestas

201 · Creada 
{
  "ok": true,
  "data": {
    "id": 621,
    "channel": "email",
    "status": "queued",
    "customer_id": 42,
    "invoice_id": null,
    "recipient": "cliente@example.com",
    "subject": "Aviso de WISPA",
    "body": "Hola, tu recibo de octubre ya está disponible.",
    "template_id": null,
    "variables": { "_dispatch": { "origin": "general", "delivery_class": "queued" } },
    "priority": 5,
    "scheduled_at": "2026-10-29 14:59:26",
    "attempts": 0,
    "max_attempts": 5,
    "last_error": null,
    "provider_reference": null,
    "sent_at": null,
    "created_at": "2026-10-29 14:59:26",
    "updated_at": "2026-10-29 14:59:26"
  },
  "meta": { "created": true }
}

200 · Repetida (misma Idempotency-Key y mismo contenido). Devuelve la misma notificación, con "meta": { "created": false }. No se envía dos veces.

409 · Misma Idempotency-Key con otro contenido 
{
  "ok": false,
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency-Key ya fue utilizada con un contenido diferente."
  }
}
422 · Dato inválido 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "channel debe ser email o whatsapp."
  }
}
  • status pasa por queued, running, retry, sent, handed_off, dead o cancelled. Consúltalo con el siguiente endpoint.
  • Una notificación creada con éxito no se puede cambiar por API.

GET Ver una notificación

/notificaciones/{id}

Consulta el estado de una notificación que creaste: si salió, cuántos intentos lleva y el último error.

Permiso del token: notifications.view

Parámetros

NombreTipoObligatorioQué es
idnúmeroSíEn la ruta. El id que devolvió al crearla.

Ejemplo

curl 
curl "https://TU-DOMINIO/api/v1/notificaciones/621" \
  -H "Authorization: Bearer TU_TOKEN"

Respuestas

200 · Éxito 
{
  "ok": true,
  "data": {
    "id": 621,
    "channel": "email",
    "status": "queued",
    "customer_id": 42,
    "invoice_id": null,
    "recipient": "cliente@example.com",
    "subject": "Aviso de WISPA",
    "body": "Hola, tu recibo de octubre ya está disponible.",
    "template_id": null,
    "variables": { "_dispatch": { "origin": "general", "delivery_class": "queued" } },
    "priority": 5,
    "scheduled_at": "2026-10-29 14:59:26",
    "attempts": 0,
    "max_attempts": 5,
    "last_error": null,
    "provider_reference": null,
    "sent_at": null,
    "created_at": "2026-10-29 14:59:26",
    "updated_at": "2026-10-29 14:59:26"
  }
}
404 · No existe 
{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Notificación no encontrada."
  }
}
  • Solo ves notificaciones de la empresa del token.

Próximamente

Leer y modificar, con el mismo token y los mismos permisos.

  • ClientesListar, ver, crear y editar.
  • ContratosConsultar, activar, suspender y dar de baja.
  • FacturasConsultar y crear.
  • PagosConsultar y registrar.

¿Necesitas algo de esto ya? Escríbenos.

Míralo funcionando

Sin registrarte. Datos ficticios.

Probar demo Lo quiero

Probar demo Lo quiero