API REST de Jefnix: integra tu tienda web en un día

Tener tu propia tienda web de accesos digitales es el paso que distingue a un distribuidor que escala de uno que opera de manera informal. Pero construir toda la lógica de gestión de inventario, asignación de cuentas y entrega de credenciales desde cero es costoso y complejo.

La API REST de Jefnix resuelve eso exactamente: tú construyes la experiencia de usuario, Jefnix opera el backend. Tu marca al frente, Jefnix trabajando por detrás.

Esta guía cubre el flujo completo de integración, desde la autenticación hasta la entrega de credenciales al cliente final.

---

Arquitectura de la integración

Antes de escribir una sola línea de código, es útil entender cómo fluye la información:

[Tu tienda web]
    |
    |-- GET  /plans          → Carga lista de planes para mostrar al cliente
    |-- POST /clients        → Registra al cliente cuando hace checkout
    |-- POST /payments/confirm → Confirma el pago y dispara la asignación
    |
    +-- [Tu cliente]
           |-- POST /accounts/send-otp    → Solicita ver sus credenciales
           +-- POST /accounts/verify-otp → Verifica OTP y recibe credenciales

El flujo tiene dos actores: tú (autenticado con API key) y tu cliente (autenticado por OTP). Las rutas de OTP son públicas — las llama tu frontend directamente, sin exponer tu API key.

---

Autenticación

Todas las rutas de gestión requieren tu API key en el header:

x-api-key: jxk_live_XXXXXXXXXXXXXXXX

Tu API key la generas en Dashboard → Configuración → API Keys. Requiere plan Pro activo.

Importante: nunca expongas tu API key en el frontend o en código JavaScript del navegador. Solo úsala en tu backend (servidor Node.js, Python, PHP, etc.).

---

Endpoints disponibles

Método	Ruta	Auth	Descripción
GET	/plans	API key	Lista planes activos
GET	/clients	API key	Lista clientes paginados
POST	/clients	API key	Crea un cliente
GET	/clients/{email}	API key	Estado de un cliente
POST	/payments/confirm	API key	Confirma un pago
GET	/pool/status	API key	Estado del inventario
POST	/accounts/send-otp	Pública	Envía OTP al cliente
POST	/accounts/verify-otp	Pública	Verifica OTP, retorna credenciales
POST	/accounts/rotation	API key	Solicita reemplazo de cuenta

Base URL: https://jefnix.com/api/v1

---

Flujo completo — paso a paso

Paso 1: Cargar los planes

En tu página de inicio o catálogo, llama a /plans para obtener los planes configurados en tu cuenta:

// En tu servidor (Next.js API route, Express, etc.)
const response = await fetch('https://jefnix.com/api/v1/plans', {
  headers: { 'x-api-key': process.env.JEFNIX_API_KEY }
});
const planes = await response.json();

Renderiza los planes en tu UI con los datos que devuelve la API. Así cualquier cambio de precio o nombre que hagas en el dashboard de Jefnix se refleja automáticamente en tu tienda.

Paso 2: Registrar al cliente en el checkout

Cuando el cliente completa el formulario de compra y antes de procesar el pago, registra su email:

const res = await fetch('https://jefnix.com/api/v1/clients', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.JEFNIX_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: cliente.email })
});
// 201 → cliente creado | 409 → ya existe (continúa el flujo normalmente)

Paso 3: Confirmar el pago en Jefnix

Una vez verificado el pago en tu pasarela, llamas a /payments/confirm. Este es el endpoint que dispara todo: Jefnix asigna una cuenta del pool al cliente y envía las credenciales por email automáticamente.

await fetch('https://jefnix.com/api/v1/payments/confirm', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.JEFNIX_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_email: clientEmail,
    plan_id: planId,
    note: 'Pago confirmado vía MercadoPago'
  })
});

Después de esta llamada, el cliente recibe un email con sus credenciales. No necesitas hacer nada más.

---

Manejo de errores

Código	Significado	Qué hacer
401	API key inválida o ausente	Verificar variable de entorno
404	Cliente o recurso no encontrado	Verificar email / plan_id
409	Conflicto (ej. cliente ya existe)	Continuar flujo normalmente
422	Límite del plan alcanzado	Notificar al usuario y contactar soporte
429	Rate limit excedido	Implementar retry con backoff

---

Rate Limiting

Tipo de ruta	Límite
Rutas con API key	60 req/min
OTP (públicas)	3 req/10 min por email

---

Webhooks para eventos en tiempo real

Si tu sistema necesita reaccionar a eventos en tiempo real, configura un webhook en Dashboard → Configuración → Webhooks. Jefnix enviará un POST a tu URL con el payload del evento.

Evento	Cuándo se dispara
payment.confirmed	Pago confirmado y cuenta asignada
account.rotated	Cuenta reemplazada por falla
account.expiring	Cuenta expira en menos de 24h
client.trial_expired	Trial gratuito del cliente expiró

---

Deploy de tu tienda

Plataforma	Ideal para	Costo inicial
Vercel	Next.js / React	Gratis (free tier)
Railway	Node.js / Python	~5 USD/mes
Render	Cualquier stack	Gratis (free tier)
VPS propio	Máximo control	~10–20 USD/mes

---

Siguientes pasos

Con la integración básica lista, los pasos naturales son:

1. Personalizar el diseño de tu tienda con tu branding
2. Integrar tu pasarela de pagos favorita (ver tutorial de MercadoPago)
3. Configurar webhooks para automatizar notificaciones
4. Agregar dominio propio para que la tienda viva en tienda.tudominio.com

La documentación completa de la API está disponible en /api/docs.

Accede a tu API key →

---

¿Necesitas ayuda con la integración? Escríbenos a soporte@jefnix.com — tenemos soporte técnico dedicado para integradores.