---
title: "API SYELLA / CloudCockpit (Marketplace CSP Microsoft)"
module: integrations
type: functional
status: active
updated: 2026-07-30
---

# 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

- [Documentation Reseller](https://developer.cloudcockpit.com/reseller/) (celle qui nous concerne)
- [Guide d'authentification](https://developer.cloudcockpit.com/reseller/topic/topic-authentication-guide)
- [Documentation Customer](https://developer.cloudcockpit.com/customer/)
- [Journal des évolutions](https://developer.cloudcockpit.com/changes)
- [Contrat OpenAPI](https://api.cloudcockpit.com/swagger/v1/swagger.json)

Doc technique associée :
[`.claude/technical-docs/integrations/syella-cloudcockpit-api.md`](../../.claude/technical-docs/integrations/syella-cloudcockpit-api.md).