Isi-APP Docs fonctionnelles
Toutes les docs
Markdown brut
API SYELLA / CloudCockpit (Marketplace CSP Microsoft)
Actif integrations functional Revu le 2026-07-30 integrations/syella-cloudcockpit-api.md

API SYELLA / CloudCockpit (Marketplace CSP Microsoft)

Doc fonctionnelle : décrit le quoi et le pourquoi (point de vue utilisateur / chef de projet).

À quoi ça sert

SYELLA est notre distributeur (CSP Microsoft). Son portail Marketplace tourne sur la plateforme CloudCockpit, qui expose une API REST. L'enjeu pour Isi-APP : ne plus maintenir les tarifs Microsoft dans Excel mais les récupérer à la source pour alimenter les devis, puis, à terme, rapprocher les abonnements des clients et éventuellement automatiser les commandes.

Un écran d'administration — /admin/syella — permet dès aujourd'hui de tester l'API avec un couple d'identifiants et de lire la documentation de la plateforme sans quitter Isi-APP.

Ce que l'API donne

Domaine Contenu
Catalogue & tarifs Offres CSP Microsoft, prix de revente marges incluses
Clients Clients finaux du revendeur, leurs licences, leurs domaines
Abonnements Quantités, dates de terme, renouvellements à venir, éligibilités
Facturation Factures et lignes de facture (licences, one-time, usage)
Commandes Création de commande — en écriture, hors périmètre des clés actuelles
Audit Journal des opérations réalisées sur le portail et via l'API

L'écran /admin/syella

Réservé aux développeurs (la page manipule les identifiants d'API du partenaire, qui ne sont pas cloisonnés par entité). Deux onglets :

Bac à sable — saisie du Client ID, du Client Secret et du header X-Tenant, puis :

  • Tester l'authentification : vérifie le couple d'identifiants et affiche la durée de validité du token obtenu ;
  • Exécuter : rejoue un appel choisi dans une liste (catalogue, clients, abonnements, factures…), affiche le statut HTTP, la durée, le nombre d'éléments, le JSON renvoyé et la commande curl équivalente ;
  • historique des dix derniers appels de la session.

Documentation — à quoi sert l'API, le flux d'authentification, les familles d'endpoints, les conventions (pagination, énumérations, codes d'erreur), la trajectoire d'intégration envisagée et les liens vers la documentation officielle.

Ce que l'écran ne fait pas

  • Aucune écriture : seuls des appels de lecture (GET) sont proposés, et le client HTTP refuse tout autre verbe. Aucune commande ne peut partir depuis cet écran.
  • Aucun stockage en base : le secret saisi reste chiffré dans la session serveur ; il disparaît à la déconnexion, ou immédiatement via le bouton Oublier.

Rôles côté plateforme : csp, reseller, customer

L'API attribue un rôle au contexte des identifiants, et chaque endpoint déclare les rôles qui y ont accès. Nos clés sont un contexte revendeur, donc une partie du catalogue est structurellement hors d'atteinte :

Appel Rôles autorisés
Revendeurs, Profil MPN, Tous les abonnements csp seulement — inaccessible avec nos clés
Liste des clients, Journaux d'audit csp, reseller
Synthèse tableau de bord, Prix de revente d'une offre csp, reseller, customer
Providers, Instances, Catalogue des offres, Factures… aucune restriction déclarée

L'écran affiche ces rôles à côté de chaque appel et prévient explicitement quand un appel est réservé au csp : un refus sur ceux-là est normal, ce n'est pas un défaut de configuration.

Règles d'accès

Profil Accès à /admin/syella
Développeur (liste isDeveloper()) ✅
Administrateur ISI non développeur ❌ 403
Session d'assistance (impersonation client) ❌ 403 — la garde suit l'acteur, pas l'assistant connecté
Autre profil ❌ arrêté par le middleware isi-admin

Identifiants et droits

  • Les clés (client_id / client_secret) sont émises par SYELLA : la création d'un « API Access » est réservée au CSP.
  • Les clés de test fournies sont en droits viewer (lecture seule), volontairement, pour écarter tout risque de commande accidentelle.
  • Le secret est valable 2 ans, ajustable au passage en production.

Le header X-Tenant (piège à connaître)

La valeur attendue est le domaine du portail : syella.cloudcockpit.com — confirmé par SYELLA le 30/07/2026, et valeur par défaut de l'écran. Si un jour nous passons en marque blanche avec notre propre domaine, c'est ce nouveau domaine qu'il faudra mettre (variable SYELLA_TENANT).

Toute autre valeur — ou l'absence du header — fait répondre à la plateforme 500 DependencyResolutionException sur tous les endpoints, avant même la vérification de l'authentification. Un 500 sur toute la ligne se lit donc « mauvais tenant », pas « panne » ; à l'inverse un 401 indique que le tenant est bon et que seul le token est en cause.

Chaque appel émis par Isi-APP porte un X-Correlation-Id, et l'écran affiche l'identifiant de corrélation renvoyé par la plateforme : c'est ce qu'il faut communiquer au support SYELLA pour faire retrouver un appel dans leurs journaux.

Points ouverts côté SYELLA

  • validation du jeton côté plateforme (bloquant, chez SYELLA) : au 30/07/2026, l'authentification aboutit (jeton délivré, valable 1 h, portant le rôle apiAccess) mais l'API refuse tous les appels en 401, en indiquant que l'issuer du tenant Azure imposé par sa propre documentation est invalide, et qu'un de ses schémas d'authentification n'a pas d'audience configurée. Rien à corriger côté Isi-APP : l'écran affiche le motif exact et le Correlation Id à leur transmettre ;
  • identifiant de l'instance de provider à utiliser (requis pour les factures et le prix des offres) ;
  • valeurs acceptées pour invoiceType ;
  • limites de débit et volumétrie du catalogue, pour dimensionner la synchronisation.

Trajectoire envisagée

  1. Tarifs dans les devis — synchronisation périodique du catalogue et des prix de revente.
  2. Rapprochement du parc client — clients et abonnements confrontés au CRM et au parc licences.
  3. Contrôle de facturation — factures et lignes de facture pour vérifier la refacturation.
  4. Commandes (optionnel) — nécessite des clés en écriture et un garde-fou métier.

Liens

Doc technique associée : .claude/technical-docs/integrations/syella-cloudcockpit-api.md.