Vente de l'hébergement Zinn® à partir de vos propres systèmes

Vous revendez notre hébergement. Vos clients vous appartiennent : vos prix, vos factures, votre prestataire de paiement. C'est ainsi que vous pilotez notre plateforme depuis l'outil que vous utilisez déjà — un panneau de facturation, votre propre site WordPress ou un script.

Ce que vos clients voient réellement

Avant la technique : vos clients ne doivent jamais nous voir. Trois interfaces, et c'est vous qui choisissez celle que vous utilisez.

| Interface | À qui elle appartient | |---|---| | Le panneau d'hébergement, sur votre propre nom d'hôte | Définissez un nom d'hôte de panneau dans Revente → Votre marque et vos clients se connectent sur panel.votreentreprise.com avec votre logo et vos couleurs. Même panneau, votre adresse. | | Votre propre site web | Le plugin WordPress intègre une recherche de domaine et un lien de connexion en un clic sur votre site, et traite la commande via votre propre module de paiement WooCommerce. | | Votre panneau de facturation | WHMCS ou HostBill reste la porte d'entrée ; le module effectue le provisionnement en arrière-plan et le bouton de l'espace client les connecte directement à leur hébergement. |

⛔ Peu importe votre choix, vous êtes le commerçant officiel (merchant of record) pour vos clients : vos prix, vos factures, votre numéro de TVA, votre prestataire de paiement. Nous vous facturons, vous, une fois par mois, au tarif de gros.

Une fois que vous avez défini un nom d'hôte pour le panneau, renseignez-le dans le champ Adresse du panneau du plugin WordPress et nulle part ailleurs — les liens de connexion générés par cette API le suivent automatiquement.

Les quatre portes d'entrée

Il existe quatre façons de procéder, qui font toutes la même chose en arrière-plan :

| | Pour | |---|---| | Le module WHMCS | Une boutique WHMCS | | Le module HostBill | Une boutique HostBill | | Le plugin WordPress | Vendre depuis votre propre site WordPress ou WooCommerce | | L'API | Tout le reste — Blesta, un système interne, un script cron |

1. Obtenir une clé API

Dans votre tableau de bord, allez dans Clés API et créez-en une. Attribuez-lui uniquement ce dont elle a besoin :

| Permission | Pourquoi | |---|---| | org.read | Lire les comptes de vos clients | | sites.create | Provisionner un site | | sites.view | Lire un service | | sites.delete | Résilier | | reseller.view | Lister vos services et lire la consommation | | reseller.provision | Suspendre, libérer et connecter un client |

⛔ N'attribuez pas reseller.manage à une intégration. Cette permission modifie votre liste de prix et les identifiants de votre propre passerelle de paiement. reseller.provision existe précisément pour qu'une clé que vous collez dans un panneau de facturation ou un site web n'en ait pas besoin.

La clé n'est affichée qu'une seule fois. Stockez-la là où vous conservez vos autres identifiants — jamais dans un fichier servi par votre serveur web.

2. Effectuer votre premier appel

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

Cela renvoie chaque service que vous avez provisionné, une ligne par site, avec le client auquel il appartient, son statut et ce que vous lui facturez. Sur un nouveau compte, il s'agit d'une liste vide — ce qui est la réponse correcte, et non une erreur.

3. L'intégralité de l'intégration en six appels

QUAND                APPEL
une commande est payée  POST   /v1/orgs                                   une fois par CLIENT
                        POST   /v1/sites                                  une fois par SERVICE
le client n'a pas payé  POST   /v1/reseller/services/{siteId}/suspend
il paie                 POST   /v1/reseller/services/{siteId}/unsuspend
il annule               DELETE /v1/sites/{siteId}
« se connecter à l'hébergement » POST   /v1/reseller/services/{siteId}/sso

Le provisionnement se fait en deux appels, et les clés ont leur importance :

# 1. le compte du client — identifié par VOTRE identifiant client
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. son site — identifié par VOTRE identifiant de service
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"}'

Deux règles qui coûtent cher lorsqu'elles sont mal appliquées

Identifiez le compte par votre CLIENT et le site par votre SERVICE. La deuxième commande d'un client doit aboutir dans le compte qu'il possède déjà. Si vous utilisez le service comme unique identifiant pour les deux, un client se retrouvera avec trois comptes sans lien entre eux et trois panneaux distincts.
Envoyez un en-tête Idempotency-Key sur chaque POST, construit à partir de votre propre identifiant pour l'élément. Tout système de facturation effectue des nouvelles tentatives — le webhook d'une passerelle arrive deux fois, un administrateur relance un provisionnement échoué, un client double-clique. Sans cette clé, la seconde tentative crée un second site qui vous sera facturé.

Trois réponses qu'il ne faut pas aplatir en deux

unsuspend peut renvoyer 409. Cela signifie que notre équipe en charge des abus bloque le site, et non vous. Affichez le message ; ne relancez pas l'appel.
**La résiliation programme une suppression, elle ne l'exécute pas immédiatement.** La date est renvoyée sous la forme pending_deletion_at. Dire à un client que ses données ont déjà disparu alors que ce n'est pas le cas est pire que de ne rien lui dire.
disk_used_bytes peut être null, et null n'est pas égal à zéro. Cela signifie que nous n'avons pas pu mesurer, et non qu'aucun espace n'a été utilisé. Ignorez cette valeur — n'écrivez pas 0 dans vos propres enregistrements, sous peine d'afficher à un client une barre d'utilisation verte pour un site dont vous n'avez aucune mesure.

4. Connecter un client

POST /v1/reseller/services/{siteId}/sso renvoie une URL à usage unique qui plonge directement votre client dans son propre compte, déjà connecté.

⛔ Générez-la au moment du clic, jamais lors du rendu de la page. Le lien est à usage unique et expire en quelques minutes. Par conséquent, un lien inscrit directement dans une page est consommé dès le premier affichage et conservé dans tous les caches situés entre vous et le navigateur.

5. Installer un module à la place

WHMCS — copiez le module dans modules/servers/zinn/, ajoutez un serveur dont le Mot de passe est votre clé API, et définissez la gamme de produits sur le produit. Cliquez sur Tester la connexion : cela effectue un véritable appel et vous restitue la réponse de la plateforme.
HostBill — copiez-le dans includes/modules/Hosting/zinn/ et connectez-le de la même manière.
WordPress — le Zinn® Reseller Toolkit : recherche de domaine, lien de connexion vers l'hébergement de vos clients et provisionnement WooCommerce lorsqu'une commande est payée. Open source sur <https://github.com/Zinn-Digital/zinn-reseller-toolkit>, ou à télécharger depuis Extensions dans votre tableau de bord.

6. Passer en production

Vérifiez les points suivants avant d'enregistrer une vraie commande :

Le test de connexion réussit sur le module, ou votre premier curl renvoie une liste.
Votre liste de prix est configurée (Revente → Vos prix).
Votre passerelle de paiement est connectée (Revente → Passerelles de paiement) — vos clients vous payent via votre propre compte.
Les informations de votre entreprise sont renseignées (Revente → Votre entreprise) afin que les factures de vos clients portent le nom de votre entité légale et votre numéro de TVA, et non les nôtres.
Vous avez passé une véritable commande de bout en bout et vérifié l'apparition du site.

Où se trouve le reste

La documentation de référence complète de l'API — chaque point de terminaison, généré à partir de notre spécification, avec la permission nécessaire pour chacun — se trouve sur <https://zinndigital.com/developers/api>.