Saltar al contenido principal

Sistema de Recarga y Recarga

El sistema de recarga de OmniCRM proporciona un portal de recarga prepago de autoservicio para que los clientes añadan crédito o extiendan la validez del servicio a través del Portal de Autoservicio. Esta función se utiliza comúnmente para:

  • Servicios de datos móviles - Tarjetas SIM prepago y servicios solo de datos
  • Servicios de hotspot - Dongles de hotspot WiFi y dispositivos de internet portátiles
  • Servicios inalámbricos fijos - Acceso a internet prepago

Visión General​

El sistema de recarga permite a los clientes comprar días adicionales de servicio a través de un proceso de pago simplificado y de múltiples pasos con procesamiento de pagos integrado de Stripe.

Características Clave:

  • Portal de autoservicio para clientes (no se requiere intervención del personal)
  • Selección de duración flexible (1-30 días)
  • Visualización de uso en tiempo real antes de la compra
  • Procesamiento de pagos seguro impulsado por Stripe
  • Reembolsos automáticos si la recarga falla
  • Generación de facturas y transacciones
  • Integración del sistema de aprovisionamiento para la activación del servicio

Acceso al Portal de Recarga​

El portal de recarga se accede a través de una URL pública que los clientes pueden visitar sin iniciar sesión en el CRM:

Cómo Acceden los Clientes:

  • Enlace directo enviado por SMS cuando el saldo es bajo
  • Código QR en materiales impresos
  • Enlace en el portal de autoservicio
  • Compartido a través del soporte al cliente

El portal detecta automáticamente el servicio del cliente en función de su dirección IP de solicitud o IMSI.

Proceso de Recarga​

El flujo de recarga consta de 4 pasos:

Paso 1: Selección de Datos​

Los clientes seleccionan cuántos días de servicio desean comprar.

Interfaz:

  • Control deslizante - Seleccionar de 1 a 30 días
  • Cálculo de precio en vivo - Muestra el costo total basado en la selección
  • Visualización de fecha de caducidad - Calcula y muestra cuándo expirará el servicio
  • Visualización de uso actual - Muestra el saldo restante/caducidad antes de la recarga

Ejemplo de Visualización:

Configuración de Precios:

  • El precio por día se configura a través de la variable de entorno REACT_APP_TOPUP_PRICE_PER_DAY
  • Predeterminado: $10 USD por día
  • La moneda se establece a través de REACT_APP_CURRENCY_CODE

Paso 2: Información de Facturación​

Los clientes proporcionan sus datos de contacto para la transacción:

  • Nombre
  • Apellido
  • Dirección de Correo Electrónico

Esta información se utiliza para:

  • Generación de facturas
  • Correo electrónico de recibo de pago
  • Registros de transacciones
  • Procesamiento de reembolsos (si es necesario)

Paso 3: Pago​

Procesamiento de pagos seguro a través de Stripe Elements.

Métodos de Pago Soportados:

  • Tarjetas de crédito (Visa, Mastercard, Amex)
  • Tarjetas de débito
  • Monederos digitales (Apple Pay, Google Pay) si están habilitados en Stripe

Características de Seguridad:

  • Integración de Stripe conforme a PCI
  • No se almacenan detalles de la tarjeta en OmniCRM
  • Soporte para autenticación 3D Secure
  • Transmisión de pago cifrada

Flujo de Pago:

  1. Se muestra el formulario de Stripe Elements con entrada de tarjeta
  2. El cliente ingresa los detalles de pago
  3. Se crea la Intención de Pago por el monto exacto
  4. La tarjeta se carga de inmediato
  5. Éxito/fallo del pago gestionado

::: note ::: title Nota :::

Si el pago tiene éxito pero el aprovisionamiento de la recarga falla (por ejemplo, error de red, OCS inalcanzable), el sistema inicia automáticamente un reembolso completo al método de pago del cliente. :::

Paso 4: Finalización​

Pantalla de Éxito:

Su servicio ha sido extendido. Nueva fecha de caducidad: 17 de enero de 2025

Recibo enviado a: <customer@example.com> ID de Transacción: TXN-123456

Pantalla de Fallo:

Si la recarga falla, el sistema muestra un error y procesa automáticamente un reembolso:

No pudimos completar su recarga. Su pago ha sido reembolsado.

Error: No se pudo conectar al sistema de facturación

Por favor, inténtelo de nuevo o contacte con el soporte.

Procesamiento en el Backend​

Cuando un cliente completa el pago, lo siguiente sucede automáticamente:

1. Validación del Pago

El sistema valida:

  • El estado de la Intención de Pago es succeeded
  • El monto del pago coincide con los días seleccionados (days × price_per_day)
  • La Intención de Pago no ha sido procesada antes (previene recargas dobles)

2. Operación de Recarga

- API endpoint: POST /oam/topup_dongle
- Valida service_uuid e IMSI
- Llama a OCS/CGRateS para añadir saldo
- Crea trabajo de aprovisionamiento (play_topup_hotspot)

3. Creación de Registros

El sistema crea múltiples registros en la base de datos:

  • Registro HotspotTopup - Rastrear la transacción de recarga
    • payment_intent_id
    • service_uuid
    • imsi
    • días comprados
    • topup_amount
    • estado (Éxito/Fallido/Reembolsado)
  • Registro de Transacción - Transacción financiera
    • Título: "Recarga de Hotspot - 7 Días"
    • Monto: topup_amount (positivo)
    • Vinculado a service_id y customer_id
  • Registro de Factura - Factura de pago
    • Contiene la transacción de recarga
    • Marcada como pagada de inmediato
    • Referencia de pago: payment_intent_id de Stripe
  • Transacción de Pago - Transacción de crédito compensatoria
    • Título: "Pago por [Título de la Factura]"
    • Monto: topup_amount (negativo - crédito)
    • Vincula el pago de la factura a la cuenta del cliente

4. Trabajo de Aprovisionamiento

Se crea un trabajo de aprovisionamiento con el playbook play_topup_hotspot que:

  • Se conecta a la API de OCS/CGRateS
  • Añade saldo a la cuenta
  • Extiende la fecha de caducidad
  • Crea una entrada de registro de actividad
  • Envía una notificación de confirmación (si está configurado)

La API espera a que se complete el aprovisionamiento (sondeo con intervalos de 0.2s, máximo 25 iteraciones) antes de devolver el éxito al cliente.

5. Reembolso Automático en Caso de Fallo

Si algún paso falla después del pago:

if topup_provisioning_failed:
    refund = stripe.Refund.create(
        payment_intent=payment_intent_id,
        reason='requested_by_customer'  # Reembolso automático del sistema
    )
    status_message = "Recarga Fallida. Reembolsando pago..."

El reembolso se procesa automáticamente y el cliente es notificado en pantalla.

Endpoints de API​

Endpoint de Recarga​

POST /oam/topup_dongle
Content-Type: application/json

{
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "imsi": "310120123456789",
  "days": 7,
  "payment_intent_id": "pi_1234567890abcdef",
  "topup_amount": 70.00
}

Respuesta (Éxito):

{
  "result": "OK",
  "status": 200,
  "provision_id": 456,
  "payment_intent_id": "pi_1234567890abcdef",
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_id": 789
}

Respuesta (Fallo):

{
  "result": "Failed",
  "Reason": "Tiempo de espera de conexión OCS",
  "status": 500
}

Comprobaciones de Validación:

  • Todos los campos requeridos presentes (service_uuid, imsi, days, payment_intent_id, topup_amount)
  • topup_amount coincide con days: topup_amount × 100 == days × 1000 (en centavos)
  • La Intención de Pago existe en Stripe
  • El monto de la Intención de Pago coincide: payment_intent.amount == topup_amount × 100
  • El estado de la Intención de Pago es succeeded
  • La Intención de Pago no ha sido procesada anteriormente (verifica la tabla HotspotTopup)

Endpoint de Uso​

Recupera la información de uso y servicio actual para el cliente:

GET /oam/usage

Respuesta:

{
  "imsi": "310120123456789",
  "service": {
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "service_name": "Datos Móviles - 0412345678",
    "service_status": "Activo"
  },
  "balance": {
    "expiry": "2025-01-10T23:59:59Z",
    "unlimited": true
  },
  "requestingIp": "203.0.113.45"
}

Este endpoint utiliza la dirección IP de solicitud para identificar automáticamente el servicio del cliente.

Configuración​

Variables de Entorno​

Configura estas en el archivo .env de OmniCRM-UI:

# Configuración del Portal de Recarga
REACT_APP_TOPUP_PRICE_PER_DAY=10
REACT_APP_CURRENCY_CODE=AUD
REACT_APP_SELF_CARE_NAME="YourCompany"

# Configuración de Stripe
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

Configuración de Stripe​

El sistema de recarga utiliza Intenciones de Pago de Stripe:

  1. Habilitar Intenciones de Pago en tu Panel de Control de Stripe
  2. Configurar Webhook para recibir actualizaciones del estado de pago (opcional pero recomendado)
  3. Configurar métodos de pago (tarjetas, monederos, etc.)
  4. Modo de prueba - Usa claves de prueba para el desarrollo
# Desarrollo
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Producción
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

Configuración del Playbook​

El playbook de aprovisionamiento play_topup_hotspot.yaml debe configurarse para:

  • Aceptar la variable days
  • Conectarse a la API de OCS/CGRateS
  • Añadir saldo a la cuenta
  • Actualizar la fecha de caducidad del servicio

Ejemplo de estructura del playbook:

- name: Recargar servicio de hotspot
  hosts: localhost
  tasks:
    - name: Añadir saldo a OCS
      uri:
        url: "{{ ocs_api_url }}/add_balance"
        method: POST
        body:
          imsi: "{{ imsi }}"
          days: "{{ days }}"
          service_uuid: "{{ service_uuid }}"

Notificaciones de Saldo Bajo​

El sistema puede enviar notificaciones automáticas cuando el saldo del cliente es bajo:

Notificaciones SMS:

Cuando se activan por eventos de OCS (Action_Balance_Low, Action_Balance_Out, Action_Balance_Expired):

Notificaciones por Correo Electrónico:

Configuradas en los planes de acción de OCS/CGRateS para enviar alertas de saldo.

Disparadores de Notificación:

  • Action_Balance_Low - Saldo por debajo del umbral (por ejemplo, 2 días restantes)
  • Action_Balance_Out - Saldo agotado
  • Action_Balance_Expired - Servicio expirado

Cada notificación incluye el enlace al portal de recarga para un fácil acceso del cliente.

Solución de Problemas​

Problemas Comunes​

"Sistema de pago no disponible"

  • Causa: La biblioteca de Stripe no se cargó o la clave publicable es inválida
  • Solución:
    • Verifica que REACT_APP_STRIPE_PUBLISHABLE_KEY esté configurada correctamente
    • Verifica que la cuenta de Stripe esté activa
    • Revisa la consola del navegador en busca de errores de JavaScript

"Recarga fallida. Reembolsando pago..."

  • Causa: Falló el trabajo de aprovisionamiento (OCS inalcanzable, error en el playbook, etc.)
  • Solución:
    • Verifica los registros de aprovisionamiento: GET /crm/provision/provision_id/<id>
    • Verifica que la API de OCS/CGRateS sea accesible
    • Revisa el playbook play_topup_hotspot.yaml en busca de errores
    • Verifica los registros de Ansible

"Intención de pago ya procesada"

  • Causa: El cliente intenta reutilizar el mismo pago (por ejemplo, actualizar después del éxito)
  • Solución: Esto funciona como se diseñó para prevenir la doble facturación. El cliente debe iniciar una nueva recarga si es necesario.

"El monto de la intención de pago no coincide"

  • Causa: Desajuste entre el cálculo de la UI y la validación del backend
  • Solución:
    • Verifica que REACT_APP_TOPUP_PRICE_PER_DAY coincida con la expectativa del backend (predeterminado $10)
    • Verifica que la configuración de la moneda sea consistente
    • Limpia la caché del navegador y vuelve a intentarlo

Monitoreo de Recargas​

Ver Registros de Recarga:

Consulta la tabla HotspotTopup para ver todos los intentos de recarga:

SELECT
  hotspot_topup_id,
  service_uuid,
  days,
  topup_amount,
  status,
  payment_intent_id,
  created
FROM hotspot_topup
WHERE status = 'Failed'
ORDER BY created DESC;

Verificar Estado de Aprovisionamiento:

GET /crm/provision/provision_id/<provision_id>

Muestra el estado detallado del trabajo de aprovisionamiento de la recarga.

Panel de Control de Stripe:

Monitorea pagos, reembolsos y transacciones fallidas en tu Panel de Control de Stripe en <https://dashboard.stripe.com>

Consideraciones de Seguridad​

Seguridad de Pagos:

  • Todos los datos de la tarjeta son manejados por Stripe (conforme a PCI Nivel 1)
  • No se almacenan datos de pago sensibles en la base de datos de OmniCRM
  • Las Intenciones de Pago previenen cargos no autorizados
  • Validación de montos tanto en el lado del cliente como en el servidor

Prevención de Fraude:

  • La detección de Intenciones de Pago duplicadas previene la doble facturación
  • Seguimiento de direcciones IP para correlación de uso
  • La validación de IMSI asegura que la recarga vaya al servicio correcto
  • Los reembolsos automáticos limitan la exposición financiera

Control de Acceso:

  • El portal de recarga es público (por diseño - los clientes necesitan acceso)
  • El endpoint de uso requiere identificación de servicio válida (IP o IMSI)
  • La validación del backend previene recargas arbitrarias de servicios
  • El administrador puede ver todos los registros de recarga a través de la interfaz del CRM

Mejores Prácticas​

Para Operadores:

  1. Probar el flujo de reembolso - Prueba regularmente escenarios de fallo para asegurar que los reembolsos funcionen
  2. Monitorear recargas fallidas - Configura alertas para altas tasas de fallo
  3. Mantener los playbooks simples - Los playbooks de recarga deben ser rápidos y confiables
  4. Verificar conectividad de OCS - Asegúrate de que la API de OCS esté siempre accesible
  5. Revisar precios - Actualiza REACT_APP_TOPUP_PRICE_PER_DAY según sea necesario

Para Clientes:

  1. Guardar la URL de recarga - Acceso rápido cuando sea necesario
  2. Guardar notificaciones de saldo bajo - El SMS contiene un enlace directo
  3. Mantener el correo electrónico actualizado - Los recibos se envían al correo electrónico registrado
  4. Verificar la caducidad antes de viajar - Recargar antes de salir del área de cobertura

Para Desarrolladores:

  1. Manejar webhooks de Stripe - Implementar controladores de webhook para actualizaciones del estado de pago
  2. Implementar idempotencia - Siempre verifica payment_intent_id antes de procesar
  3. Registrar extensivamente - Las fallas de recarga necesitan información detallada de solución de problemas
  4. Probar rutas de error - Verifica que la automatización de reembolsos funcione correctamente
  5. Monitorear rendimiento - El sondeo de aprovisionamiento debe completarse en <5 segundos

Documentación Relacionada​

  • payments_process - Procesamiento de pagos general
  • concepts_provisioning - Visión general del sistema de aprovisionamiento
  • integrations_stripe - Detalles de integración de Stripe
  • payments_transaction - Gestión de transacciones
  • payments_invoices - Manejo de facturas