Vente d’hébergement Zinn® depuis vos propres systèmes

Vous revendez notre hébergement. Vos clients vous appartiennent : vos prix, vos factures, votre prestataire de paiement. Voici comment piloter notre plateforme depuis vos outils actuels — un panneau de facturation, votre propre site WordPress ou un script.

Ce que vos clients voient réellement

Avant la mécanique : vos clients n’ont jamais besoin de nous voir. Trois interfaces s’offrent à vous, et vous choisissez celle que vous utilisez.

⛔ Quel que soit 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, une fois par mois, aux tarifs de gros.

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

Les quatre voies d’accès

Il existe quatre voies d’accès, et elles réalisent toutes la même opération sous-jacente :

1. Obtenir une clé d’API

Dans votre tableau de bord, accédez à Clés d’API et créez-en une. Attribuez-lui uniquement ce dont elle a besoin :

⛔ Ne donnez pas reseller.manage à une intégration. Cette autorisation permet de modifier votre grille tarifaire et les identifiants de votre propre passerelle de paiement. reseller.provision existe précisément pour qu’une clé collée dans un panneau de facturation ou un site web n’en ait pas besoin.

La clé n’est affichée qu’une seule fois. Conservez-la à l’endroit où vous stockez 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 l’ensemble des services que vous avez provisionnés, à raison d’une ligne par site, avec le client auquel il appartient, son statut et le montant que vous lui facturez. Sur un nouveau compte, il s’agit d’une liste vide — ce qui constitue la réponse correcte, et non une erreur.

3. L’intégration complète, en six appels

QUAND                APPEL
une commande est payée  POST   /v1/orgs                                   une fois par CLIENT
                        POST   /v1/sites                                  une fois par SERVICE
ils n'ont pas payé      POST   /v1/reseller/services/{siteId}/suspend
ils paient              POST   /v1/reseller/services/{siteId}/unsuspend
ils annulent            DELETE /v1/sites/{siteId}
« connexion hébergement » POST /v1/reseller/services/{siteId}/sso

Le provisionnement se fait en deux appels, et les clés d’identification sont essentielles :

# 1. le compte du client — indexé sur 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. leur site — indexé sur 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 dont l’inobservation coûte de l’argent

1. Indexez le compte sur votre CLIENT et le site sur votre SERVICE. La deuxième commande d’un client doit être rattachée au compte qu’il possède déjà. Si vous indexez les deux sur le service, le client se retrouvera avec trois comptes sans lien entre eux et trois panneaux distincts.
2. Envoyez une clé Idempotency-Key sur chaque POST, générée à partir de votre propre identifiant pour l’élément concerné. Chaque système de facturation effectue des nouvelles tentatives — un rappel de passerelle arrive en double, un administrateur relance un provisionnement ayant échoué, un client clique deux fois. Sans cette clé, la seconde tentative crée un second site qui vous sera facturé.

Trois réponses à ne pas confondre

• unsuspend peut renvoyer un code 409. Cela signifie que notre équipe de lutte contre les abus bloque le site, et non vous. Affichez le message ; ne réessayez pas.
• **La résiliation planifie 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 sont déjà supprimées alors que ce n’est pas le cas est pire que de ne rien lui dire.
• disk_used_bytes peut avoir la valeur null, et null n’est pas zéro. Cela signifie que nous n’avons pas pu mesurer l’espace, et non que rien n’a été utilisé. Ignorez cette valeur — n’inscrivez pas 0 dans vos propres registres, faute de quoi vous afficherez au client une barre d’utilisation verte pour un site dont vous ne possédez aucun relevé.

4. Connecter un client

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

⛔ Générez-la lors du clic, jamais au moment du rendu de la page. Le lien est à usage unique et expire au bout de quelques minutes ; un lien inscrit dans une page est donc consommé dès la première consultation de la page et conservé dans tous les caches intermédiaires entre vous et le navigateur.

5. Installer plutôt un module

• WHMCS — copiez le module dans modules/servers/zinn/, ajoutez un serveur dont le champ Password correspond à votre clé d’API, et définissez la gamme de produits sur le produit. Cliquez sur Test Connection : il effectue un appel réel et vous indique la réponse de la plateforme.
• HostBill — copiez dans includes/modules/Hosting/zinn/ et connectez-le de la même manière.
• WordPress — la boîte à outils Zinn® Reseller Toolkit : recherche de domaines, lien de connexion vers l’hébergement de vos clients et provisionnement WooCommerce lorsqu’une commande est payée. Projet open source disponible sur <https://github.com/Zinn-Digital/zinn-reseller-toolkit>, ou téléchargeable depuis la section Extensions de votre tableau de bord.

6. Mettre en production

Vérifiez les points suivants avant d’accepter une commande réelle :

• Le test de connexion réussit sur le module, ou votre première commande curl renvoie une liste.
• Votre grille tarifaire est configurée (Revente → Vos tarifs).
• Votre passerelle de paiement est connectée (Revente → Passerelles de paiement) — vos clients vous paient, via votre propre compte.
• Les coordonnées de votre entreprise sont renseignées (Revente → Votre entreprise) afin que les factures de vos clients mentionnent votre entité juridique et votre numéro de TVA, et non les nôtres.
• Vous avez passé une commande réelle de bout en bout et constaté la création effective du site.

Où trouver tout le reste

La référence complète de l’API — chaque point de terminaison, généré à partir de nos spécifications, avec les autorisations requises par chacun — est disponible sur <https://zinndigital.com/developers/api>.