HAZ Group – Guía de Configuración del Cliente y Credenciales API¶

Fecha: 13 de noviembre de 2025 Estado: Activo – Producción Actualización: ✨ NUEVA - Soporte Dual para Movistar y Telcel

🎉 NUEVA FUNCIONALIDAD: Soporte Multi-Carrier¶

HAZ Group ahora tiene acceso automático a recarga para todos los operadores principales en México.

📱 Operadores Soportados¶

Operador	Códigos de Área	Ejemplo
Movistar	55, 56	5566374683
Telcel	Todos los demás	3312345678

Ventajas: - ✅ Detección automática del operador por número de teléfono - ✅ Sin cambios en tu integración API - ✅ Mismo endpoint para todos los operadores - ✅ Respuestas unificadas en el mismo formato

Información del Cliente¶

ID del Cliente: HAZ_001 Nombre de la Empresa: HAZ Group Estado: ACTIVO Saldo Inicial para pruebas: $200 USD

Credenciales de API¶

API Key: haz_prod_2025 Customer ID: HAZ_001 Secret Key: HAZ!gr0up#2025$

⚠️ Importante: Mantenga estas credenciales seguras y no las comparta públicamente.

Endpoints de API¶

URL Base (Producción): https://latcom-fix-production.up.railway.app

Endpoints disponibles:¶

Recarga (sincrónica): POST /api/enviadespensa/topup
Recarga (asíncrona con cola): POST /api/enviadespensa/topup-async
Consultar saldo: GET /api/balance
Estado de transacción: GET /api/transaction/{transactionId}
Verificación del sistema: GET /health

Ejemplo de Solicitud de Recarga¶

Movistar (área 55/56)¶

curl -X POST https://latcom-fix-production.up.railway.app/api/enviadespensa/topup \
-H "Content-Type: application/json" \
-H "x-api-key: haz_prod_2025" \
-H "x-customer-id: HAZ_001" \
-d '{"phone": "5566374683", "amount": 20}'

Telcel (otros códigos de área)¶

curl -X POST https://latcom-fix-production.up.railway.app/api/enviadespensa/topup \
-H "Content-Type: application/json" \
-H "x-api-key: haz_prod_2025" \
-H "x-customer-id: HAZ_001" \
-d '{"phone": "3312345678", "amount": 20}'

Respuesta Exitosa¶

{
  "success": true,
  "transaction": {
    "id": "RLR1760353500123",
    "status": "SUCCESS",
    "amount_mxn": 20,
    "amount_usd": 1.08,
    "exchange_rate": 18.52,
    "phone": "5566374683",
    "provider": "relier",
    "processedAt": "2025-11-13T10:00:00Z",
    "currency": "MXN"
  },
  "billing": {
    "deducted_usd": 1.08,
    "balance_before_usd": 200,
    "balance_after_usd": 198.92,
    "exchange_rate": 18.52
  },
  "message": "Recarga de 20 MXN procesada exitosamente. Se dedujeron $1.08 USD del saldo.",
  "remaining_balance": 198.92
}

Productos Disponibles¶

Movistar (Área 55, 56)¶

Montos disponibles (MXN): - 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 150, 200, 300, 500

Telcel (Todos los demás códigos)¶

Montos disponibles (MXN): - 10, 20, 30, 50, 80, 100, 150, 200, 300, 500

📝 Nota: Los montos pueden variar según disponibilidad del operador. Consulte con soporte para productos especiales o paquetes de datos.

Características de Seguridad¶

Autenticación por clave API: Todas las solicitudes requieren x-api-key y x-customer-id.
IP Whitelist: Necesitamos la IP desde donde van a enviar las solicitudes.
HTTPS Obligatorio: Todas las solicitudes deben usar conexión segura.
Rate Limiting: 200 solicitudes por minuto por cliente.

Instrucciones para Pruebas¶

1. Verificar estado del sistema¶

curl https://latcom-fix-production.up.railway.app/health

2. Verificar IP actual¶

curl https://latcom-fix-production.up.railway.app/api/check-ip

3. Consultar saldo¶

curl -X GET https://latcom-fix-production.up.railway.app/api/balance \
-H 'x-api-key: haz_prod_2025' \
-H 'x-customer-id: HAZ_001'

4. Pruebas de Recarga¶

Número Movistar (55):

curl -X POST https://latcom-fix-production.up.railway.app/api/enviadespensa/topup \
-H "Content-Type: application/json" \
-H "x-api-key: haz_prod_2025" \
-H "x-customer-id: HAZ_001" \
-d '{"phone": "5512345678", "amount": 10}'

Número Telcel (33):

curl -X POST https://latcom-fix-production.up.railway.app/api/enviadespensa/topup \
-H "Content-Type: application/json" \
-H "x-api-key: haz_prod_2025" \
-H "x-customer-id: HAZ_001" \
-d '{"phone": "3312345678", "amount": 10}'

5. Consultar estado de transacción¶

curl https://latcom-fix-production.up.railway.app/api/transaction/{transactionId} \
-H 'x-api-key: haz_prod_2025' \
-H 'x-customer-id: HAZ_001'

Manejo de Errores Comunes¶

Código	Significado	Solución
401	Credenciales inválidas	Verifique los encabezados x-api-key y x-customer-id
403	Saldo insuficiente o IP no autorizada	Contacte al administrador para recargar cuenta o verificar IP
400	Monto no válido	Solo se permiten montos de la tabla de productos
429	Límite de solicitudes excedido	Reduzca frecuencia (máx 200/min)
500	Error del sistema	Intente nuevamente o contacte soporte

Detección Automática de Operador¶

¿Cómo funciona?¶

El sistema detecta automáticamente el operador basándose en el código de área:

Número: 5566374683
         ^^
         └─ Código 55 → Movistar

Número: 3312345678
         ^^
         └─ Código 33 → Telcel

Códigos de Área Principales en México¶

Código	Ciudad/Zona	Operador Principal
55	Ciudad de México	Movistar
56	Ciudad de México	Movistar
33	Guadalajara	Telcel
81	Monterrey	Telcel
222	Puebla	Telcel
998	Cancún	Telcel

📝 Importante: El sistema enruta automáticamente cada número al operador correcto.

Ejemplos de Integración¶

PHP¶

<?php
$ch = curl_init('https://latcom-fix-production.up.railway.app/api/enviadespensa/topup');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: haz_prod_2025',
    'x-customer-id: HAZ_001'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone' => '5566374683',
    'amount' => 20
]));

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    echo "Recarga exitosa! ID: " . $result['transaction']['id'];
} else {
    echo "Error: " . $result['error'];
}
?>

Python¶

import requests

response = requests.post(
    'https://latcom-fix-production.up.railway.app/api/enviadespensa/topup',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'haz_prod_2025',
        'x-customer-id': 'HAZ_001'
    },
    json={
        'phone': '5566374683',
        'amount': 20
    }
)

result = response.json()
if result['success']:
    print(f"Recarga exitosa! ID: {result['transaction']['id']}")
else:
    print(f"Error: {result['error']}")

Node.js¶

const axios = require('axios');

async function topup(phone, amount) {
    try {
        const response = await axios.post(
            'https://latcom-fix-production.up.railway.app/api/enviadespensa/topup',
            { phone, amount },
            {
                headers: {
                    'Content-Type': 'application/json',
                    'x-api-key': 'haz_prod_2025',
                    'x-customer-id': 'HAZ_001'
                }
            }
        );

        console.log('Recarga exitosa!', response.data.transaction.id);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response.data.error);
        throw error;
    }
}

// Uso
topup('5566374683', 20);

Soporte y Contacto¶

Para asistencia técnica o facturación:

Correo directo: support@relier.group

Horario de soporte: Lunes a Viernes, 9:00 AM - 6:00 PM (Hora México)

Respuesta promedio: 2-4 horas hábiles

Registro de Cambios¶

13 de Noviembre 2025 - v2.0¶

✨ NUEVO: Soporte dual para Movistar y Telcel
✨ NUEVO: Detección automática de operador por código de área
✨ NUEVO: Sin cambios requeridos en integración existente
📝 Actualización de tablas de productos disponibles
📝 Nuevos ejemplos de integración para ambos operadores

13 de Octubre 2025 - v1.0¶

🎉 Lanzamiento inicial

Última actualización: 13 de noviembre de 2025 Versión del documento: 2.0 Estado: Producción Activa