Venta de alojamiento de Zinn® desde sus propios sistemas

Tú revendes nuestro alojamiento. Tus clientes son tuyos: tus precios, tus facturas, tu proveedor de pagos. Así es como gestionas nuestra plataforma desde lo que ya utilizas: un panel de facturación, tu propio sitio WordPress o un script.

Qué ven realmente tus clientes

Antes de la parte mecánica: tus clientes nunca tienen que vernos a nosotros. Tres interfaces, y tú eliges cuál usas.

| Superficie | De quién es | |---|---| | El panel de alojamiento, en tu propio nombre de host | Configura un nombre de host para el panel en Reselling → Your brand y tus clientes iniciarán sesión en panel.yourcompany.com con tu logotipo y tus colores. El mismo panel, tu dirección. | | Tu propio sitio web | El plugin de WordPress coloca la búsqueda de dominios y un enlace de inicio de sesión con un solo clic en tu sitio, y procesa el pedido a través de tu propia pasarela de pago de WooCommerce. | | Tu panel de facturación | WHMCS o HostBill sigue siendo la puerta de entrada; el módulo realiza el aprovisionamiento en segundo plano y el botón del área de clientes los conecta directamente a su alojamiento. |

⛔ Elijas la que elijas, eres el comerciante registrado (merchant of record) para tus clientes: tus precios, tus facturas, tu número de IVA, tu proveedor de pagos. Nosotros te facturamos a ti, una vez al mes, al por mayor.

Una vez que hayas configurado un nombre de host para el panel, introdúcelo en el campo Panel address del plugin de WordPress y en ningún otro lugar; los enlaces de inicio de sesión que genera esta API lo siguen automáticamente.

Las cuatro formas de acceso

Hay cuatro formas de acceder, y todas hacen lo mismo por debajo:

| | Para | |---|---| | El módulo de WHMCS | Una tienda WHMCS | | El módulo de HostBill | Una tienda HostBill | | El plugin de WordPress | Vender desde tu propio sitio de WordPress o WooCommerce | | La API | Cualquier otra cosa: Blesta, un sistema propio, un script cron |

1. Obtener una clave de API

En tu panel, ve a API keys y crea una. Asígnale únicamente lo que necesite:

| Permiso | Motivo | |---|---| | org.read | Leer las cuentas de tus clientes | | sites.create | Aprovisionar un sitio | | sites.view | Leer un servicio | | sites.delete | Dar de baja | | reseller.view | Listar tus servicios y leer el uso | | reseller.provision | Suspender, reactivar y conectar a un cliente |

⛔ No otorgues reseller.manage a una integración. Ese permiso edita tu lista de precios y tus propias credenciales de pasarela de pago. reseller.provision existe precisamente para que una clave que pegues en un panel de facturación o un sitio web no lo necesite.

La clave se muestra una sola vez. Almacénala donde guardas tus otras credenciales; nunca en un archivo al que sirva tu servidor web.

2. Realizar tu primera llamada

curl https://api.zinndigital.com/v1/reseller/services \
  -H "Authorization: Bearer zdk_live_…"

Eso devuelve cada servicio que hayas aprovisionado, una fila por sitio, con el cliente al que pertenece, su estado y lo que cobras por él. En una cuenta nueva es una lista vacía, lo cual es la respuesta correcta, no un error.

3. Toda la integración, en seis llamadas

CUÁNDO                LLAMADA
se paga un pedido    POST   /v1/orgs                                   una vez por CLIENTE
                     POST   /v1/sites                                  una vez por SERVICIO
no han pagado        POST   /v1/reseller/services/{siteId}/suspend
pagan                POST   /v1/reseller/services/{siteId}/unsuspend
cancelan             DELETE /v1/sites/{siteId}
"iniciar sesión"     POST   /v1/reseller/services/{siteId}/sso

El aprovisionamiento consta de dos llamadas, y las claves importan:

# 1. la cuenta del cliente: identificada con TU ID de cliente
curl -X POST https://api.zinndigital.com/v1/orgs \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-4211" \
  -d '{"type":"customer","name":"Acme Ltd"}'

# 2. su sitio: identificado con TU ID de servicio
curl -X POST https://api.zinndigital.com/v1/sites \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: service-9915" \
  -d '{"org_id":"<from step 1>","product_line":"mainstream","primary_domain":"acme.com"}'

Dos reglas que cuestan dinero cuando te equivocas

Identifica la cuenta con tu CLIENTE y el sitio con tu SERVICIO. El segundo pedido de un cliente debe recaer en la cuenta que ya tiene. Si identificas ambos con el servicio, un cliente terminará con tres cuentas no relacionadas y tres paneles independientes.
Envía una Idempotency-Key en cada POST, construida a partir de tu propio ID para el elemento. Todos los sistemas de facturación reintentan: la retrollamada de una pasarela llega dos veces, un administrador vuelve a ejecutar un aprovisionamiento fallido, un cliente hace doble clic. Sin la clave, el segundo intento crea un segundo sitio y se te facturará por él.

Tres respuestas que no debes simplificar en dos

unsuspend puede responder 409. Eso significa que nuestro equipo de abuso retiene el sitio, no tú. Muestra el mensaje; no lo reintentes.
**Dar de baja programa una eliminación, no la ejecuta.** La fecha devuelta es pending_deletion_at. Decirle a un cliente que sus datos ya han desaparecido cuando no es así es peor que no decirle nada.
disk_used_bytes puede ser null, y null no es cero. Significa que no hemos podido medirlo, no que no se haya usado nada. Sáltatelo; no escribas 0 en tus propios registros o le mostrarás a un cliente una barra de uso verde para un sitio del que no tienes ninguna lectura.

4. Iniciar sesión por un cliente

POST /v1/reseller/services/{siteId}/sso devuelve una URL de un solo uso que lleva a tu cliente directamente a su propia cuenta, con la sesión ya iniciada.

⛔ Genérala cuando hagan clic, nunca cuando renderices la página. El enlace es de un solo uso y caduca en cuestión minutos, por lo que un enlace escrito en una página se consume en la primera visualización y se queda en todas las cachés entre ti y el navegador.

5. Instalar un módulo en su lugar

WHMCS: copia el módulo en modules/servers/zinn/, añade un servidor cuya Password sea tu clave de API y establece la línea de productos en el producto. Haz clic en Test Connection: realiza una llamada real y te indica lo que ha respondido la plataforma.
HostBill: cópialo en includes/modules/Hosting/zinn/ y conéctalo de la misma manera.
WordPress: el Zinn® Reseller Toolkit: búsqueda de dominios, un enlace de inicio de sesión al alojamiento de tus clientes y aprovisionamiento de WooCommerce cuando se paga un pedido. Código abierto en <https://github.com/Zinn-Digital/zinn-reseller-toolkit>, o descárgalo desde Plugins en tu panel.

6. Poner en marcha

Comprueba esto antes de aceptar un pedido real:

La prueba de conexión se supera en el módulo o tu primer curl devuelve una lista.
Tu lista de precios está configurada (Reselling → Your prices).
Tu pasarela de pago está conectada (Reselling → Payment gateways): tus clientes te pagan a ti, a través de tu propia cuenta.
Los datos de tu empresa están introducidos (Reselling → Your company) para que las facturas de tus clientes lleven tu entidad legal y tu número de IVA, no los nuestros.
Has realizado un pedido real de principio a fin y has visto aparecer el sitio.

Dónde está todo lo demás

La referencia completa de la API (cada punto de conexión, generado a partir de nuestra especificación, con el permiso que necesita cada uno) se encuentra en <https://zinndigital.com/developers/api>.