ESC
Menú de Navegación

Telecomunicaciones (ISP)

Módulo ISP & RedesAbonados / Cuotas Adelantadas / Emisión SAR / Desconexión MikroTik

Endpoints especializados para plataformas de recaudación externa, redes de corresponsales y billeteras móviles integradas con proveedores de servicios de internet (WISP y FTTH). Permiten consultar en vivo la solvencia técnica y financiera de un contrato, obtener opciones precalculadas de pago (regular, ponerse al día o adelantos de hasta 12 meses) y procesar pagos emitiendo de inmediato la factura electrónica del SAR con CAI y reactivación en red.

Consultar Suscriptor ISP

Diseñado especialmente para corresponsales bancarios, aplicaciones móviles de pago y plataformas de recaudación masiva. Permite consultar al instante el estado de cuenta de un abonado de internet residencial o corporativo, su solvencia en red y las opciones de cobro precalculadas para presentar en pantalla.

GET/m2m/telecom/subscriptions/{subscriberCodeOrId}
Opciones Precalculadas de Pago (payment_options)

La respuesta incluye una lista de opciones listas para renderizar en cajero o quiosco: cuota regular de 1 mes, ponerse al día con cuotas vencidas, adelanto de 2 meses, semestre (6 meses) o año completo (12 meses).

Parámetro de Ruta (Path Param)

subscriberCodeOrIdRequeridostring

Código único de abonado en ventanilla (ej. SUB-2003), RTN/Identidad del titular o ID ULID de la suscripción.

curl -X GET "https://{tenant}.proyexa.app/m2m/telecom/subscriptions/SUB-2003" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://{tenant}.proyexa.app/m2m/telecom/subscriptions/SUB-2003');
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://{tenant}.proyexa.app/m2m/telecom/subscriptions/SUB-2003"))
    .header("Authorization", "Bearer " + token)
    .header("Accept", "application/json")
    .GET()
    .build();
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.GetAsync("https://{tenant}.proyexa.app/m2m/telecom/subscriptions/SUB-2003");
{
  "status": "success",
  "message": "Datos de suscriptor consultados exitosamente.",
  "data": {
    "subscription_id": "01m4c0mhw6k7d5jzg8wyaa9jpb",
    "subscriber_code": "SUB-2003",
    "customer_name": "Ing. Roberto Daniel Morales",
    "rtn": "0801199012345",
    "plan_name": "Plan Fibra Residencial 100 Mbps",
    "monthly_amount": 650.00,
    "paid_until": "2026-11-05",
    "extension_until": null,
    "is_solvent": true,
    "status": "active",
    "billing_day": 5,
    "months_overdue": 0,
    "amount_overdue": 0.00,
    "allow_partial_payments": false,
    "payment_options": [
      {
        "id": "regular_1_month",
        "label": "1 Mes de Servicio",
        "months": 1,
        "amount": 650.00,
        "projected_paid_until": "2026-12-05"
      },
      {
        "id": "advance_2_months",
        "label": "2 Meses de Servicio (Adelanto)",
        "months": 2,
        "amount": 1300.00,
        "projected_paid_until": "2027-01-05"
      },
      {
        "id": "semester_6_months",
        "label": "Semestre Completo (6 Meses)",
        "months": 6,
        "amount": 3900.00,
        "projected_paid_until": "2027-05-05"
      },
      {
        "id": "annual_12_months",
        "label": "Año Completo (12 Meses)",
        "months": 12,
        "amount": 7800.00,
        "projected_paid_until": "2027-11-05"
      }
    ]
  },
  "pagination": null,
  "errors": null
}
{
  "status": "success",
  "message": "Datos de suscriptor consultados exitosamente.",
  "data": {
    "subscription_id": "01m4c0mhw9ravyjsf40sc9k1xx",
    "subscriber_code": "SUB-2004",
    "customer_name": "Elena Patricia Durón",
    "rtn": "0801198899112",
    "plan_name": "Plan Fibra Residencial 100 Mbps",
    "monthly_amount": 650.00,
    "paid_until": "2026-08-05",
    "extension_until": null,
    "is_solvent": false,
    "status": "suspended",
    "billing_day": 5,
    "months_overdue": 2,
    "amount_overdue": 1300.00,
    "allow_partial_payments": false,
    "payment_options": [
      {
        "id": "regular_1_month",
        "label": "1 Mes de Servicio",
        "months": 1,
        "amount": 650.00,
        "projected_paid_until": "2026-09-05"
      },
      {
        "id": "clear_debt",
        "label": "Ponerse al Día (2 meses vencidos)",
        "months": 2,
        "amount": 1300.00,
        "projected_paid_until": "2026-10-05"
      },
      {
        "id": "clear_debt_plus_1",
        "label": "Ponerse al Día + 1 Mes Adelantado (3 meses)",
        "months": 3,
        "amount": 1950.00,
        "projected_paid_until": "2026-11-05"
      },
      {
        "id": "semester_6_months",
        "label": "Semestre Completo (6 Meses)",
        "months": 6,
        "amount": 3900.00,
        "projected_paid_until": "2027-02-05"
      },
      {
        "id": "annual_12_months",
        "label": "Año Completo (12 Meses)",
        "months": 12,
        "amount": 7800.00,
        "projected_paid_until": "2027-08-05"
      }
    ]
  },
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "Suscriptor no encontrado.",
  "data": null,
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "No autenticado. Token inválido o ausente.",
  "data": null,
  "pagination": null,
  "errors": null
}

Pagar Servicio ISP

Procesa en tiempo real el cobro de mensualidades de internet. Emite la Factura Oficial del SAR con CAI de contado en el acto, extiende la cobertura en red (paid_until) respetando el día de corte del suscriptor, y reactiva automáticamente el servicio en enrutadores MikroTik u OLTs GPON mediante colas asíncronas si el abonado se encontraba suspendido.

POST/m2m/telecom/subscriptions/payments
Reglas de Negocio: Montos vs. Meses y Política de Pagos Parciales

Validación Estricta de Meses: Si la petición incluye el parámetro months, el amount debe cubrir la totalidad correspondiente (amount >= months × tarifa_mensual). Por ejemplo, si se envían 5 meses pero con el monto de 1 solo mes (ej. L. 650.00), la API rechaza inmediatamente la transacción devolviendo error 422 Unprocessable Entity ("El monto enviado (650) es insuficiente para cubrir 5 mes(es) de servicio. Se requieren 3250").

Adelanto de Cuotas: El cliente puede adelantar 2, 6 o el año completo (12 meses). La API extenderá proporcionalmente la fecha paid_until sin desfases.

Pagos Parciales: Si la credencial M2M tiene deshabilitados los pagos parciales (recomendado por defecto), los montos que no cubran cuotas exactas completas serán rechazados para evitar inconsistencias operativas.

Parámetros del Cuerpo (JSON)

subscriber_codeCondicionalstring

Código único de abonado en ventanilla (ej. SUB-2003) o RTN. Requerido si no se envía subscription_id.

amountRequeridonumber (decimal)

Monto total pagado en moneda local (HNL). Debe cubrir cuotas mensuales completas exactas.

referenceRequeridostring

Número único de transacción de la entidad recaudadora. Se valida duplicidad para evitar cobros dobles.

monthsOpcionalinteger (1 a 36)

Cantidad de mensualidades que ampara el pago. Permite pagar el año completo (12 meses) por adelantado.

notesOpcionalstring

Trazabilidad o comentarios de la pasarela para incluir en la factura emitida.

curl -X POST "https://{tenant}.proyexa.app/m2m/telecom/subscriptions/payments" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subscriber_code": "SUB-2003",
    "amount": 7800.00,
    "reference": "BANCO-TRX-998822",
    "months": 12,
    "notes": "Pago de año completo por adelantado vía Banca Móvil"
  }'
$response = Http::withToken($token)
    ->acceptJson()
    ->post('https://{tenant}.proyexa.app/m2m/telecom/subscriptions/payments', [
        'subscriber_code' => 'SUB-2003',
        'amount'          => 7800.00,
        'reference'       => 'BANCO-TRX-998822',
        'months'          => 12,
        'notes'           => 'Pago de año completo por adelantado vía Banca Móvil',
    ]);
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://{tenant}.proyexa.app/m2m/telecom/subscriptions/payments"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Accept", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
        {
          "subscriber_code": "SUB-2003",
          "amount": 7800.00,
          "reference": "BANCO-TRX-998822",
          "months": 12,
          "notes": "Pago de año completo por adelantado vía Banca Móvil"
        }
        """))
    .build();
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var payload = new {
    subscriber_code = "SUB-2003",
    amount = 7800.00,
    reference = "BANCO-TRX-998822",
    months = 12,
    notes = "Pago de año completo por adelantado vía Banca Móvil"
};
var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://{tenant}.proyexa.app/m2m/telecom/subscriptions/payments", content);
{
  "status": "success",
  "message": "Pago procesado y factura emitida con éxito.",
  "data": {
    "transaction_id": "01J2Z8K9M34Q7QE2VQWKCK72X6",
    "document_type": "invoice",
    "invoice_number": "000-001-01-00000105",
    "cai": "3B8C12-9F0A34-451298-BC7612-4409AB-12",
    "subscriber_code": "SUB-2003",
    "customer_name": "Ing. Roberto Daniel Morales",
    "months_paid": 12,
    "paid_amount": 7800.00,
    "reference": "BANCO-TRX-998822",
    "previous_paid_until": "2026-09-30",
    "paid_until": "2027-09-30",
    "status": "active",
    "is_active": true,
    "message": "Factura #000-001-01-00000105 emitida exitosamente por 12 mes(es). Cobertura activa hasta 2027-09-30."
  },
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "El monto enviado (650.00) es insuficiente para cubrir 5 mes(es) de servicio. Se requieren 3250.00 (650.00 por mes).",
  "data": null,
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "Esta credencial M2M no autoriza pagos parciales de servicios ISP. El monto enviado (450.00) debe cubrir cuotas mensuales completas exactas (Tarifa mensual: 650.00).",
  "data": null,
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "La referencia de pago externa 'BANCO-TRX-998822' ya fue procesada anteriormente.",
  "data": null,
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "No se encontró una suscripción válida para los datos suministrados.",
  "data": null,
  "pagination": null,
  "errors": null
}
{
  "status": "error",
  "message": "No autenticado. Token inválido o ausente.",
  "data": null,
  "pagination": null,
  "errors": null
}