Pleaxy

Émettez des bons de commande, validez et payez les factures, et configurez votre espace de travail.

Référence de l’API

Connexions cloud

Accès en lecture seule à la facturation de vos comptes de fournisseurs cloud.

En savoir plus sur cette ressource

Une connexion cloud donne à Pleaxy un accès en lecture seule à la facturation d’un compte de fournisseur cloud, via un accès que vous créez dans votre propre compte avec un script de configuration. AWS utilise un rôle IAM inter-comptes, Google Cloud la Workload Identity Federation et Azure un identifiant fédéré, chacun pour des sessions de courte durée sans stocker de clé de longue durée. Oracle Cloud utilise une clé de signature d’API que Pleaxy génère pour la connexion ; vous ne téléversez que sa clé publique. La connexion se fait en deux appels : init renvoie les valeurs dont le script de configuration a besoin, puis CreateCloudConnection vérifie l’accès et finalise la connexion. Seule la personne qui a lancé une configuration peut la finaliser ou l’annuler.

Endpoints

Lister les connexions cloud

Liste les connexions cloud de l’espace de travail.

GET/v1/workspaces/{regionId}/cloud-connections

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Liste les connexions cloud de l’espace de travail, y compris les configurations encore en cours (status pending). Ne renvoie jamais de secrets ni les identifiants utilisés par la configuration (ARN de rôle, ID externe, compte de service, OCID, ID de tenant ou d’application).

Champs de la réponse

  • dataSourcesArray<"invoices" | "current_cost">

    Ce que Pleaxy peut lire : les factures finalisées et/ou le coût depuis le début du mois. Absent signifie les deux.

  • lastSyncStatus"ok" | "error" | "throttled" | "never"

    Le déroulement de la dernière synchronisation de facturation. lastSyncErrorCode indique pourquoi une synchronisation a échoué : throttled, access_revoked, platform_config, data_not_enabled ou unknown.

Erreurs

  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
GET /v1/workspaces/{regionId}/cloud-connections
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
[
   {
      "id": "string",
      "provider": "aws" | "gcp" | "azure" | "oci",
      "accountLabel": "string",
      "detail": "string",
      "spend": number,
      "status": "connected" | "pending" | "error",
      "connectedAt": "string",
      "awsAccountId": "string",
      "dataSources": [ "invoices" | "current_cost" ],
      "gcp": { "billingAccountId": "string", "providerId": "string" },
      "oci": { "homeRegion": "string", "keyFingerprint": "string" },
      "azure": { "scopeDisplayName": "string", "agreementType": "string" },
      "lastSyncedAt": "string",
      "lastSyncStatus": "ok" | "error" | "throttled" | "never",
      "lastSyncError": "string",
      "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
   }
]

Initialiser une connexion cloud AWS

Commence la connexion d’un compte AWS.

POST/v1/workspaces/{regionId}/cloud-connections/aws/init

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Commence la connexion d’un compte AWS et renvoie les valeurs à fournir au script de configuration (CloudFormation, CDK ou CLI), qui crée un rôle IAM en lecture seule dans votre compte. Un nouvel appel renvoie votre propre configuration inachevée, avec le même ID externe. Ne prend pas de corps.

Champs de la réponse

  • connectionIdstring

    À passer à CreateCloudConnection comme awsConnectionId.

  • cloudFormationTemplateUrlstring

    Absent lorsque ce déploiement ne publie aucun modèle CloudFormation ; utilisez alors le script CDK ou CLI.

Erreurs

  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/cloud-connections/aws/init
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/aws/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 201 Created
{
   "connectionId": "string",
   "platformAwsAccountId": "string",
   "externalId": "string",
   "cloudFormationTemplateUrl": "string"
}

Initialiser une connexion cloud

Commence la connexion d’un compte Google Cloud, Azure ou Oracle Cloud.

POST/v1/workspaces/{regionId}/cloud-connections/{provider}/init

Paramètres

  • provider"gcp" | "azure" | "oci"Obligatoire

    Le fournisseur cloud à connecter.

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Identique à InitAwsCloudConnection pour Google Cloud, Azure ou Oracle Cloud : renvoie les valeurs propres à la connexion que fixe le script de configuration de ce fournisseur, dont un connectionId à passer à CreateCloudConnection (comme gcpConnectionId, azureConnectionId ou ociConnectionId). Un nouvel appel renvoie votre propre configuration inachevée. Ne prend pas de corps.

Champs de la réponse

  • gcpobject

    connectionId, platformAwsAccountId, federationRoleArn, expectedSubject, poolId et providerId : les valeurs de Workload Identity Federation que fixe le script de configuration.

  • azureobject

    connectionId, issuer, subject, audience, appDisplayName et credentialName : l’identifiant fédéré que le script de configuration crée sur votre application.

  • ociobject

    connectionId, publicKeyPem, fingerprint et regions : la clé publique à téléverser pour l’utilisateur pleaxy-billing, et les régions d’origine parmi lesquelles choisir.

Erreurs

  • 404 Not Found - Le connecteur réel de ce fournisseur cloud n’est pas activé dans ce déploiement (« Real connections to this provider aren't switched on. »).
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/cloud-connections/{provider}/init
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 201 Created
{
   "connectionId": "string",
   ...the provider's setup values
}

Découvrir les périmètres de facturation Azure

Liste les profils de facturation Azure que vous pouvez connecter.

POST/v1/workspaces/{regionId}/cloud-connections/azure/discover

Corps

  • azureConnectionIdstringObligatoire

    connectionId issu d’InitCloudConnection.

  • azureTenantIdstringObligatoire

    Le tenant Microsoft Entra dans lequel l’application a été inscrite (GUID).

  • azureClientIdstringObligatoire

    L’ID d’application (client) de l’inscription d’application (GUID).

  • azureBillingAccountIdstringObligatoire

    L’ID du compte de facturation Microsoft Customer Agreement (<guid>:<guid>_YYYY-MM-DD).

  • azureBillingProfileIdstringObligatoire

    L’ID du profil de facturation sur lequel l’application a le rôle Billing profile reader.

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Azure uniquement, entre init et CreateCloudConnection : vérifie l’ID de tenant et l’ID d’application (client) affichés par le script de configuration, et lit le compte de facturation et le profil de facturation Microsoft Customer Agreement que vous indiquez, pour que vous puissiez choisir le profil à connecter. Seule la personne qui a lancé la configuration peut l’appeler, et l’appel est décompté de la même limite de tentatives et du même délai d’attente que CreateCloudConnection.

Erreurs

  • 404 Not Found - Le connecteur réel d’Azure n’est pas activé, ou la configuration n’existe plus ou a été lancée par quelqu’un d’autre.
  • 429 Too Many Requests - Nouvel essai trop tôt ; retryAfterSeconds indique quand réessayer.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/cloud-connections/azure/discover
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/azure/discover" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 201 Created
{
   "scopes": [
      { "billingAccountId": "string", "billingProfileId": "string", "displayName": "string", "billingAccountDisplayName": "string", "agreementType": "string" }
   ]
}

Créer une connexion cloud

Finalise la connexion d’un compte cloud.

POST/v1/workspaces/{regionId}/cloud-connections

Corps

  • provider"aws" | "gcp" | "azure" | "oci"Obligatoire

    Le fournisseur cloud à connecter.

  • accountLabelstringObligatoire

    Votre libellé pour ce compte, par exemple "Production payer".

  • dataSourcesArray<"invoices" | "current_cost">

    Ce que Pleaxy peut lire : les factures finalisées et/ou le coût depuis le début du mois. Si omis : les deux. Pleaxy n’appelle jamais le fournisseur cloud pour une source que vous omettez, y compris lors d’une synchronisation manuelle. Certains fournisseurs facturent chaque requête de coût courant (AWS Cost Explorer).

  • supplierContactEmailstring

    Contact facultatif chez le fournisseur cloud pour la fiche fournisseur que cela crée.

  • awsConnectionIdstring

    AWS, obligatoire : connectionId issu d’InitAwsCloudConnection.

  • roleArnstring

    AWS, obligatoire : le rôle IAM créé par le script de configuration, arn:aws:iam::<12-digit account>:role/<name>.

  • gcpConnectionIdstring

    Google Cloud : connectionId issu d’InitCloudConnection.

  • gcpProjectNumberstring

    Google Cloud : le numéro du projet d’export de facturation (chiffres).

  • gcpServiceAccountEmailstring

    Google Cloud : le compte de service créé par le script de configuration dans ce projet.

  • gcpExportTablestring

    Google Cloud : la table d’export standard des coûts d’utilisation, project.dataset.gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX.

  • azureConnectionIdstring

    Azure : connectionId issu d’InitCloudConnection.

  • azureBillingAccountIdstring

    Azure : le compte de facturation du profil choisi avec DiscoverAzureBillingScopes.

  • azureBillingProfileIdstring

    Azure : le profil de facturation choisi avec DiscoverAzureBillingScopes.

  • ociConnectionIdstring

    Oracle Cloud : connectionId issu d’InitCloudConnection.

  • ociTenancyOcidstring

    Oracle Cloud : l’OCID du tenancy (ocid1.tenancy.oc1..…).

  • ociUserOcidstring

    Oracle Cloud : l’OCID de l’utilisateur pleaxy-billing créé par le script de configuration.

  • ociHomeRegionstring

    Oracle Cloud : la région d’origine du tenancy, l’une de celles que liste InitCloudConnection.

  • detailstring

    Uniquement pour une connexion de démonstration, lorsque le connecteur réel d’un fournisseur cloud est désactivé : un identifiant de compte que vous saisissez. Une connexion réelle le lit plutôt auprès du fournisseur cloud.

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Finalise une configuration lancée avec init : Pleaxy vérifie qu’il peut lire votre facturation avec l’accès créé par le script de configuration, puis marque la connexion comme connectée et ajoute le fournisseur cloud à vos fournisseurs. Envoyez les champs correspondant à votre fournisseur cloud. Seule la personne qui a lancé la configuration peut la finaliser. Soumis au plan de la région : le plan Free autorise un seul fournisseur cloud connecté.

Erreurs

  • 400 Bad Request - La validation des données a échoué ; Pleaxy n’a pas pu lire la facturation avec l’accès fourni (le code indique le fournisseur cloud, par exemple CLOUD_VERIFY_FAILED) ; trop de tentatives ont échoué pour cette configuration, recommencez donc avec init (code se terminant par ATTEMPTS_EXHAUSTED) ; ou le plan de la région a atteint sa limite de fournisseurs cloud connectés (Free : 1).
  • 404 Not Found - La configuration n’existe plus, a expiré, ou a été lancée par quelqu’un d’autre.
  • 409 Conflict - Cette configuration, ou le même compte ou périmètre de facturation, est déjà connectée.
  • 429 Too Many Requests - Nouvel essai trop tôt après une tentative échouée ; retryAfterSeconds indique quand réessayer.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/cloud-connections
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "provider": "aws",
   "accountLabel": "string",
   "awsConnectionId": "string",
   "roleArn": "string",
   "dataSources": [ "invoices", "current_cost" ]
}
Réponse · 201 Created
{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "accountLabel": "string",
   "detail": "string",
   "spend": number,
   "status": "connected" | "pending" | "error",
   "connectedAt": "string",
   "awsAccountId": "string",
   "dataSources": [ "invoices" | "current_cost" ],
   "gcp": { "billingAccountId": "string", "providerId": "string" },
   "oci": { "homeRegion": "string", "keyFingerprint": "string" },
   "azure": { "scopeDisplayName": "string", "agreementType": "string" },
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled" | "never",
   "lastSyncError": "string",
   "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
}

Synchroniser une connexion cloud

Synchronise immédiatement les données de facturation d’un compte cloud.

POST/v1/workspaces/{regionId}/cloud-connections/{id}/sync

Paramètres

  • idstringObligatoire

    L’id de la connexion cloud.

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Synchronise immédiatement les données de facturation d’un compte connecté, en ne lisant que les dataSources de la connexion. Une fois toutes les 15 minutes au plus par connexion. Ne prend pas de corps.

Erreurs

  • 400 Bad Request - Synchronisé il y a moins de 15 minutes (« …try again in {n}m. »), ou la connexion n’est pas un compte connecté doté d’un connecteur de facturation réel.
  • 404 Not Found - Aucune connexion de ce type dans l’espace de travail, ou elle a été déconnectée.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/cloud-connections/{id}/sync
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 201 Created
{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "accountLabel": "string",
   "detail": "string",
   "spend": number,
   "status": "connected" | "pending" | "error",
   "connectedAt": "string",
   "awsAccountId": "string",
   "dataSources": [ "invoices" | "current_cost" ],
   "gcp": { "billingAccountId": "string", "providerId": "string" },
   "oci": { "homeRegion": "string", "keyFingerprint": "string" },
   "azure": { "scopeDisplayName": "string", "agreementType": "string" },
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled" | "never",
   "lastSyncError": "string",
   "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
}

Déconnecter une connexion cloud

Déconnecte un compte cloud.

DELETE/v1/workspaces/{regionId}/cloud-connections/{id}

Paramètres

  • idstringObligatoire

    L’id de la connexion cloud.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Déconnecte un compte cloud, ou annule une configuration en cours. Supprime la connexion avec tout ce que Pleaxy a stocké pour elle (pour Oracle Cloud, sa clé d’API chiffrée) et consigne qui l’a déconnectée. Pour Oracle Cloud, la réponse indique l’empreinte de la clé à supprimer de l’utilisateur pleaxy-billing. Retirez aussi l’accès dans votre propre compte.

Session connectée avec l’accès 'edit' aux fournisseurs ; une clé API reçoit 403. Une configuration en cours ne peut être annulée que par la personne qui l’a lancée.

Erreurs

  • 403 Forbidden - L’appelant est une clé API, n’a pas 'edit' sur les fournisseurs, ou annule la configuration de quelqu’un d’autre (« Only the person who started this setup can cancel it. »).
  • 404 Not Found - Aucune connexion de ce type dans l’espace de travail.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
DELETE /v1/workspaces/{regionId}/cloud-connections/{id}
Requête
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "ociKeyFingerprint": "string"
}

Ajouter un fournisseur cloud comme fournisseur

Ajoute un fournisseur cloud comme fournisseur sans connecter de compte.

POST/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier

Paramètres

  • provider"aws" | "gcp" | "azure" | "oci"Obligatoire

    Le fournisseur cloud à ajouter.

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Ajoute un fournisseur cloud à votre liste de fournisseurs sans connecter de compte, pour que vous puissiez lui adresser des bons de commande. Rien n’est lu auprès du fournisseur cloud. Renvoie la fiche fournisseur existante du fournisseur cloud s’il y en a une, et une connexion ultérieure est rattachée à cette même fiche. Nécessite l’accès 'create' aux fournisseurs. Ne prend pas de corps.

Erreurs

  • 404 Not Found - Fournisseur cloud inconnu.
  • 409 Conflict - Code SUPPLIER_ALREADY_LISTED : un fournisseur portant ce nom a déjà une intégration en cours ou validée.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/cloud-connections/{provider}/supplier
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 201 Created
{
   "id": "string",
   "buyerOrgId": "string",
   "supplierName": "string",
   "cloudProvider": "aws" | "gcp" | "azure" | "oci",
   "status": "pending_invite" | "invited" | "in_progress" | "submitted" | "approved" | "rejected",
   "createdAt": "string"
}
Nous contacter