API REST de Nevacom: integrar recargas en 10 minutos

Si lo que necesitas es procesar recargas desde tu propio sistema (un e-commerce, un bot, una app interna de tu agencia de viajes, un CRM), abrir la web de Nevacom cada vez no escala. La API REST resuelve esto: tu sistema le pega a un endpoint, le pasa el destino y el monto, recibe el comprobante. Sin operador humano, sin interfaz, todo automatizado.

Te muestro el flujo mínimo para tener una recarga corriendo en menos de diez minutos: cómo obtener las credenciales, los tres endpoints que vas a usar el 90% del tiempo, un ejemplo con curl que puedes pegar en tu terminal, y los detalles que se ven cuando empiezas a operar a volumen.

Antes de empezar: lo que necesitas

• Cuenta Nevacom activa con perfil de desarrollador habilitado.
• API key (te la entregamos desde el panel una vez aprobado el perfil dev).
• Saldo en la billetera Nevacom (las recargas se descuentan del mismo saldo que ves en la web).
• Cualquier cliente HTTP: curl, Postman, fetch desde JavaScript, requests de Python, Guzzle en PHP, lo que prefieras.

No hace falta SDK específico. La API es REST plana con JSON. Cualquier stack moderno la consume sin librería especial.

El flujo mental: tres pasos

Una integración típica con Nevacom se reduce a tres llamadas que vas a hacer en este orden:

• Verificar el destino antes de cobrar. Confirmas que el número o cuenta de servicio exista y la operadora correcta. Evita errores por tipeo.
• Crear la recarga. Mandas destino, monto, tipo de servicio. La API te devuelve un ID de transacción y el estado inicial.
• Consultar el estado (cuando lo necesites) o recibir el webhook (si lo configuraste). El estado final es approved, pending o rejected.

Con esos tres movimientos cubres el 90% de los casos de uso. El resto son detalles de configuración: webhook URLs, reintentos, conciliación.

Ejemplo concreto: recarga Movistar con curl

Asumiendo que ya tienes tu API key. Esto es lo que sería el call mínimo a un endpoint genérico de la API:

curl -X POST https://api.nevacom.net/v1/recharges \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operator": "movistar",
    "phone": "04141234567",
    "amount": 500,
    "currency": "VES",
    "callback_url": "https://tu-sistema.com/webhooks/nevacom"
  }'

Respuesta típica:

{
  "id": "rec_8K2j9P",
  "status": "pending",
  "operator": "movistar",
  "phone": "04141234567",
  "amount": 500,
  "currency": "VES",
  "created_at": "2026-05-20T14:32:11Z"
}

Cuando la operadora acredita el saldo, tu webhook recibe un POST con el estado actualizado (approved). Si algo falla (operadora caída, número inválido), recibes rejected con el motivo.

La documentación completa con los endpoints exactos, parámetros disponibles, códigos de error y ejemplos en varios lenguajes está en api.nevacom.net/docs. Si todavía no has revisado, ese es el primer link.

Patrones que vale la pena implementar desde el día uno

Validar antes de cobrar

El endpoint de verificación te dice si un número pertenece a Movistar, Digitel o Movilnet sin generar un cobro. Úsalo antes del cobro real para que el cliente no termine recargando una operadora distinta a la que pensaba. Cuesta cero (no descuenta saldo) y te ahorra reembolsos por destinos mal escritos.

Usar idempotency keys

Si tu sistema retrae automáticamente cuando hay timeout, pueden generarse recargas duplicadas. La API acepta un header opcional Idempotency-Key con un valor único por intento. Si reenvías la misma llamada con la misma key, la API te devuelve el resultado de la primera, no crea una nueva. Es el patrón estándar para pagos y aquí aplica igual.

Capturar el webhook bien

El estado de una recarga puede cambiar en segundos o en minutos, según la operadora. En lugar de hacer polling al endpoint de status (caro, ineficiente), configura un webhook URL en tu integración y deja que Nevacom te avise. El webhook trae el ID de transacción y el nuevo estado. Verifica la firma (HMAC) antes de procesar.

Manejar errores con códigos, no con strings

La API responde con códigos de error estructurados. Si tu lógica de reintento se basa en el mensaje literal ("Insufficient balance"), un día cambiamos el mensaje y se te rompe. Si se basa en el código (insufficient_balance), no.

Casos de uso típicos en Venezuela

• Cybercafé con bot interno. El operador atiende al cliente y un bot interno consume la API de Nevacom para cobrar la recarga. Acreditas y vuelves al cliente en segundos.
• Agencia de viajes que vende paquetes con saldo incluido. Al confirmar la compra del paquete, tu sistema dispara automáticamente una recarga al teléfono del viajero. Sin operación manual.
• Plataforma de e-commerce con módulo de recargas. Para distribuidores que quieren ofrecer recargas como producto adicional sin construir todo el backend.
• Aplicación de remesas para diáspora. El usuario en el exterior paga con su método (Zelle, USDT), tu app llama a la API de Nevacom para acreditar al destino en Venezuela, todo en flujo único.
• Sistema de nómina de empresas con planes corporativos. Cargas mensualmente saldo a todas las líneas corporativas con un loop sobre los empleados.

Lo que no es la API

Para que no haya sorpresas, dejamos claro lo que la API no es ni intenta ser:

• No es una pasarela de pago genérica. No procesa tarjetas de crédito de tus usuarios; descuenta del saldo de tu cuenta Nevacom.
• No tiene fees por transacción. Las recargas se cobran al precio del producto, sin fee adicional por usar API. Aplican los mismos términos comerciales que en la web.
• No reemplaza la SDK móvil oficial. Si lo que necesitas es embeber recargas en una app móvil con UI hecha por nosotros, eso es otra conversación.

Cómo arrancar

El camino recomendado para una primera integración:

• Revisa la documentación de la API de cabo a rabo. Está corta a propósito; léetela completa.
• Pide tu API key contactándonos por el centro de ayuda. Te activamos el perfil dev y te entregamos las credenciales por canal seguro.
• Implementa primero el endpoint de verificación. Probarlo no cuesta saldo, así que es seguro para experimentar.
• Cuando funcione la verificación, agrega el endpoint de recarga con un monto pequeño contra una línea de prueba. Verifica que el webhook llegue y que la línea reciba el saldo.
• Reproduce los casos de error: número inválido, saldo insuficiente, operadora con contingencia. Tu sistema debe manejar cada uno sin colgarse.

En diez minutos tienes el primer flujo funcionando. En una semana tienes la integración productiva con todos los casos de borde cubiertos. Si necesitas conectar con n8n, Zapier, Make, WooCommerce o Shopify sin escribir código, te invitamos a revisar las integraciones no-code que ya tenemos preparadas.