API de Revendedores de KernelHost

Qué ofrece la API de Revendedores

La API de Revendedores de KernelHost expone exactamente las mismas acciones de pedido y gestión que usted realizaría manualmente en el portal de clientes. Le permite automatizar su negocio de reventa, integrar los productos de KernelHost en su propio frontend o sistema de facturación, y mantener el control total sobre permisos, límites de tasa y lista blanca de IP por cada clave API.

Cada llamada se firma con HMAC-SHA256, queda protegida contra repetición, se procesa de forma idempotente (obligatorio en pedidos), se registra en un registro de auditoría a prueba de manipulación y, opcionalmente, se confirma mediante webhook. Los pagos se cargan primero contra su saldo y, a continuación, contra la tarjeta registrada. Las tarjetas nuevas solo se pueden añadir en el portal de clientes (con 3-D Secure 2 obligatorio).

https://www.kernelhost.com/cp/kh_reseller_api/v1

Índice

• Inicio rápido en 5 minutos
• Autenticación (HMAC-SHA256)
• Referencia de endpoints
• Códigos de error (RFC 7807)
• SDKs: PHP, Node.js, Python, Go
• Seguridad y buenas prácticas
• Historial de cambios

Qué puede hacer con la API

• Consultar productos y precios (servidores raíz KVM, dedicados, webspace, Minecraft, VPN, tráfico ilimitado).
• Realizar pedidos (Idempotency-Key protege frente a cargos duplicados ante reintentos de red).
• Listar sus propios servicios, comprobar su estado y ejecutar acciones (arranque, parada, reinicio, reinstalación, suspensión, terminación).
• Leer las credenciales únicamente de sus propios servicios (permiso separado, auditado, con correo de confirmación opcional en cada acceso).
• Obtener facturas, comprobar el saldo y descargar PDFs de facturas.
• Registrar un webhook por clave para eventos de pedido, servicio y factura (esquema de firma compatible con Stripe).

Diseño de máxima seguridad

La API está diseñada partiendo de la base de que cada llamada tiene impacto financiero directo y puede exponer credenciales sensibles del servidor. Por ello, las exigencias de seguridad están claramente por encima del estándar habitual en REST.

• Firma de petición HMAC-SHA256 sobre método, ruta, marca de tiempo, nonce y hash del cuerpo. Comparación en tiempo constante.
• Protección contra repetición: ventana de marca de tiempo +-300s, caché de nonce de un solo uso durante 600s.
• Los secretos se almacenan persistentemente solo como cifrado AES-256-GCM. El texto en claro existe únicamente de forma transitoria en memoria para la verificación de firma. La clave maestra reside fuera de la base de datos.
• Permisos granulares por clave. Los permisos peligrosos (read:credentials, write:orders) deben activarse de forma explícita. El valor por defecto es solo lectura.
• Aislamiento de datos a nivel de base de datos: cada consulta filtra estrictamente por el identificador de su cuenta. El acceso entre clientes es imposible por diseño.

Ejemplo: consultar la información de su propia cuenta

La petición se firma íntegramente con su secreto. El secreto nunca abandona la memoria del cliente; solo se transmite la firma.

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIG_INPUT=$(printf 'GET\n/v1/me\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $2}')

curl https://www.kernelhost.com/cp/kh_reseller_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

Preguntas frecuentes

¿Quién puede utilizar la API de Revendedores?

Cualquier cliente actual de KernelHost puede crear una clave en "Mi cuenta → API de Revendedores" con su propia etiqueta, permisos y lista blanca de IP. No se requiere ningún acuerdo de reventa adicional: todos los productos publicados están disponibles vía API.

¿Cómo se pagan los pedidos?

Orden: primero el saldo y, a continuación, su método de pago registrado (tarjeta de crédito con 3-D Secure 2). Si el pago es rechazado o no hay tarjeta registrada, la API devuelve HTTP 402 "Payment Required" con un motivo concreto (insufficient_credit_and_no_card, card_declined, card_expired). El pedido permanece en estado "pending payment" durante 24h y, transcurrido ese plazo, se cancela automáticamente.

¿Puedo leer las contraseñas de los servicios mediante la API?

Sí, pero solo de sus propios servicios y únicamente con el permiso explícito read:credentials, que debe activarse al crear la clave. Cada acceso genera una entrada de auditoría credentials.read; bajo petición puede recibir además un correo de confirmación a la dirección de su cuenta, de modo que cualquier uso indebido encubierto resulta imposible.

¿Qué ocurre si mi secreto resulta comprometido?

Usted rota el secreto con un solo clic en el portal de clientes. El secreto anterior queda invalidado de inmediato y todas las sesiones activas son revocadas. Ante fallos de autenticación sospechosos (5 en 10 minutos) el sistema bloquea la clave automáticamente durante 15 minutos y le notifica por correo.