¿Qué es esta API?

Es una API HTTP pensada para integraciones externas (CRM, apps de TV, etc.). Permite buscar clientes por cédula, consultar facturas pendientes y registrar pagos por transferencia sin comprobante adjunto. Los datos incluyen nombre, contacto, estado del servicio, plan, zona y saldo pendiente.

¿Sirve para un CRM?

Sí. Un CRM puede identificar al cliente por cédula, mostrar deuda pendiente y registrar transferencias reportadas por el operador, todo con la misma clave API y sin acceso al panel.

• Consulta de cliente: estado, plan, teléfono, correo, usuario del portal.
• Pendientes: facturas en estado PENDING u OVERDUE con montos y fechas.
• Registrar pago: transferencia con referencia numérica; sin imagen de comprobante.

Seguridad y aislamiento por tenant

Cada ISP (tenant) tiene su propia clave de API. La clave identifica automáticamente a qué empresa pertenece la consulta; no hace falta enviar el ID del tenant en la URL.

• Solo ve clientes de su tenant. Una clave de TecnoLaing no puede leer datos de otro proveedor.
• La clave se guarda hasheada en el servidor; ni siquiera el equipo de Wispx la puede recuperar después de generarla.
• Puede deshabilitar o revocar la clave al instante si deja de confiar en una integración.
• No expone contraseñas, código del programa, configuración interna ni listados masivos de todos los clientes.
• No da acceso al panel web ni permisos de administrador: es únicamente el endpoint documentado.

Activar la API en su cuenta

Autenticación

En cada petición incluya la clave en uno de estos headers:

Authorization: Bearer wispx_xxxxxxxxxxxxxxxx
# o
X-Api-Key: wispx_xxxxxxxxxxxxxxxx

Si la clave es incorrecta, está revocada o la API está deshabilitada, la respuesta será 401 sin revelar si el tenant existe.

1. Consulta por cédula

Método GET. La cédula va como parámetro de consulta (solo números o con formato habitual).

GET {BASE_URL}/api/public/integration/customers?cedula=1712345678

Ejemplo con curl

curl -s \
  -H "Authorization: Bearer TU_API_KEY" \
  "{BASE_URL}/api/public/integration/customers?cedula=1712345678"

Respuesta — cliente (JSON)

{
  "ok": true,
  "cedula": "1712345678",
  "count": 1,
  "customers": [{
    "id": "cl_abc123",
    "cedula": "1712345678",
    "firstName": "Juan",
    "lastName": "Pérez",
    "fullName": "Juan Pérez",
    "email": "[email protected]",
    "phone": "0991234567",
    "status": "ACTIVE",
    "portalUsername": "1712345678",
    "address": "Calle principal",
    "city": "Quito",
    "neighborhood": "Centro",
    "plan": {
      "id": "plan_1",
      "name": "50 Mbps",
      "download": 50,
      "upload": 50,
      "price": 25
    },
    "zone": { "id": "zone_1", "name": "Zona Norte" }
  }]
}

status suele ser ACTIVE, SUSPENDED u otros estados del servicio. Si no hay coincidencias, count es 0 y customers es un arreglo vacío.

2. Pendientes por cédula

Método GET. Devuelve los mismos datos del cliente más un bloque pending con facturas PENDING u OVERDUE.

GET {BASE_URL}/api/public/integration/pending?cedula=1712345678

Ejemplo con curl

curl -s \
  -H "Authorization: Bearer TU_API_KEY" \
  "{BASE_URL}/api/public/integration/pending?cedula=1712345678"

Respuesta (fragmento)

{
  "ok": true,
  "cedula": "1712345678",
  "count": 1,
  "customers": [{
    "id": "cl_abc123",
    "fullName": "Juan Pérez",
    "status": "ACTIVE",
    "pending": {
      "totalPending": 25,
      "invoiceCount": 1,
      "invoices": [{
        "id": "inv_1",
        "invoiceNumber": "F-001",
        "amount": 25,
        "status": "PENDING",
        "dueDate": "2026-07-01T00:00:00.000Z",
        "issueDate": "2026-06-01T00:00:00.000Z"
      }]
    }
  }]
}

3. Registrar pago por transferencia

Método POST con cuerpo JSON. No requiere imagen de comprobante. Si hay varias facturas pendientes y no envía invoiceId, se aplica a la más antigua por fecha de vencimiento.

POST {BASE_URL}/api/public/integration/payments
Content-Type: application/json

{
  "cedula": "1712345678",
  "amount": 25,
  "paymentReference": "12345678",
  "customerId": "opcional si hay varios servicios",
  "invoiceId": "opcional",
  "paymentMethodId": "opcional",
  "paidDate": "2026-07-01",
  "clientNote": "Transferencia reportada por operador"
}

Ejemplo con curl

curl -s -X POST \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cedula":"1712345678","amount":25,"paymentReference":"12345678"}' \
  "{BASE_URL}/api/public/integration/payments"

Respuesta exitosa

{
  "ok": true,
  "status": "APPROVED",
  "reportId": "cpr_xxx",
  "invoiceId": "inv_1",
  "customerId": "cl_abc123",
  "message": "Pago registrado y factura marcada como pagada."
}

Si hay varios servicios con la misma cédula, el POST devuelve 409 hasta que envíe customerId (obténgalo del GET de clientes o pendientes).

Códigos de error habituales

• 401 — Clave ausente, inválida o API deshabilitada.
• 400 — Falta parámetro, referencia inválida o monto incorrecto.
• 404 — Cédula o factura pendiente no encontrada.
• 409 — Varios servicios con la misma cédula (indique customerId) o pago ya en revisión.
• 200 con count: 0 — Cédula no encontrada en su base (no es error HTTP).

Límites y buenas prácticas

• Consulte por cédula cuando el operador o el CRM ya la conocen; no haga barridos masivos.
• Guarde la clave como secreto; no la incluya en apps móviles públicas ni en repositorios Git.
• Si sospecha filtración, regenere o revoque la clave en el panel.
• Una misma cédula puede devolver varios registros si hay más de un servicio a nombre de esa persona (máx. 20).

Preguntas frecuentes