Référence de l’API

FOCUS

Exportez vos factures sous forme de jeu de données FOCUS et lisez les données de facturation FOCUS de vos fournisseurs cloud.

En savoir plus sur cette ressource

FOCUS est le format ouvert de la FinOps Foundation pour les données de facturation. Pleaxy l’utilise dans les deux sens. Un export écrit les factures, les notes de débit et les avoirs acceptés de l’espace de travail sous forme de jeu de données FOCUS Cost and Usage, pour un outil FinOps ou de reporting. Une source FOCUS lit des données de facturation dans ce format, à partir de fichiers que vous téléversez ou de l’export FOCUS du fournisseur lui-même, et conserve les totaux de chaque mois par facture, émetteur et centre de coûts. L’export et l’import s’activent par espace de travail ; tant que l’un est désactivé, ses endpoints répondent 404.

Lister les exports FOCUS

Liste les exports FOCUS des 7 derniers jours, et indique si l’export est activé.

GET/v1/workspaces/{regionId}/focus-exports

Retour

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

Plus de détails

Renvoie si l’export FOCUS est activé pour l’espace de travail et ses exports des 7 derniers jours, des plus récents aux plus anciens, 20 au plus. La liste ne contient pas de liens de téléchargement ; obtenez-les avec GetFocusExport.

Nécessite l’accès 'view' aux factures. Une clé API peut l’appeler.

Champs de la réponse

  • enabledboolean

    Si l’export FOCUS est activé pour l’espace de travail.

  • from, tostring

    La première et la dernière période de facturation de l’export, au format YYYY-MM.

  • rowCount, documentCountnumber

    Les lignes du jeu de données et les factures, notes de débit et avoirs dont elles proviennent.

  • expiresAtstring

    Le moment où Pleaxy supprime les fichiers de l’export, 7 jours après sa création.

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}/focus-exports
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "enabled": boolean,
   "exports": [
      {
         "id": "string",
         "status": "ready",
         "createdAt": "string",
         "version": "1.2" | "1.4",
         "include": "all" | "non_cloud",
         "from": "string",
         "to": "string",
         "format": "csv" | "parquet",
         "rowCount": number,
         "documentCount": number,
         "commitmentCount": number,
         "expiresAt": "string"
      }
   ]
}

Créer un export FOCUS

Exporte les factures d’une plage de mois sous forme de jeu de données FOCUS.

POST/v1/workspaces/{regionId}/focus-exports

Corps

  • fromstringObligatoire

    La première période de facturation, au format YYYY-MM.

  • tostringObligatoire

    La dernière période de facturation, au format YYYY-MM, incluse. La plage couvre 36 mois au plus.

  • version"1.2" | "1.4"

    La version de FOCUS. 1.2 en son absence. Un export 1.4 peut aussi contenir un jeu de données Contract Commitment.

  • include"all" | "non_cloud"

    non_cloud exclut les factures des fournisseurs cloud et IA, qu’un outil FinOps peut lire dans les exports FOCUS des fournisseurs eux-mêmes. all en son absence.

  • format"csv" | "parquet"

    Le format du fichier. csv en son absence.

Retour

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

Plus de détails

Écrit les factures, les notes de débit et les avoirs acceptés de l’espace de travail pour les périodes de facturation from..to sous forme de jeu de données FOCUS Cost and Usage avec un fichier de métadonnées. Il y a une ligne par ligne de facture, écriture de taxe et ajustement ; les avoirs sont négatifs ; les montants restent dans la devise de chaque document. La réponse contient des liens de téléchargement valables 15 minutes, et les fichiers sont conservés 7 jours. Un export ne change rien dans l’espace de travail.

Nécessite l’accès 'view' aux factures. Une clé API peut l’appeler.

Champs de la réponse

  • from, tostring

    La première et la dernière période de facturation de l’export, au format YYYY-MM.

  • rowCount, documentCountnumber

    Les lignes du jeu de données et les factures, notes de débit et avoirs dont elles proviennent.

  • expiresAtstring

    Le moment où Pleaxy supprime les fichiers de l’export, 7 jours après sa création.

  • downloadUrl, metadataUrlstring

    Des liens vers le jeu de données et son fichier de métadonnées, valables 15 minutes. Appelez GetFocusExport pour obtenir de nouveaux liens.

  • commitmentsUrlstring

    Un lien vers le jeu de données Contract Commitment, présent seulement quand l’export en a un.

Erreurs

  • 400 Bad Request - from ou to n’est pas un mois écrit sous la forme YYYY-MM, from est postérieur à to, ou la plage couvre plus de 36 mois.
  • 404 Not Found - L’export FOCUS n’est pas activé pour cet espace de travail (« FOCUS export isn't switched on for this workspace yet. »).
  • 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}/focus-exports
Requête
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/focus-exports
{
   "from": "2026-07",
   "to": "2026-09",
   "include": "non_cloud"
}
Réponse · 201 Created
{
   "id": "FE-mhu8x2k04f9a1c",
   "status": "ready",
   "createdAt": "2026-11-11T15:04:05.000Z",
   "version": "1.2",
   "include": "non_cloud",
   "from": "2026-07",
   "to": "2026-09",
   "format": "csv",
   "rowCount": 412,
   "documentCount": 57,
   "expiresAt": "2026-11-18T15:04:05.000Z",
   "downloadUrl": "https://...",
   "metadataUrl": "https://..."
}

Obtenir un export FOCUS

Obtient un export FOCUS avec de nouveaux liens de téléchargement.

GET/v1/workspaces/{regionId}/focus-exports/{exportId}

Paramètres

  • exportIdstringObligatoire

    L’id de l’export, tel que CreateFocusExport le renvoie.

Retour

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

Plus de détails

Renvoie un export des 7 derniers jours avec de nouveaux liens vers son jeu de données et son fichier de métadonnées, valables 15 minutes.

Nécessite l’accès 'view' aux factures. Une clé API peut l’appeler.

Champs de la réponse

  • from, tostring

    La première et la dernière période de facturation de l’export, au format YYYY-MM.

  • rowCount, documentCountnumber

    Les lignes du jeu de données et les factures, notes de débit et avoirs dont elles proviennent.

  • expiresAtstring

    Le moment où Pleaxy supprime les fichiers de l’export, 7 jours après sa création.

  • downloadUrl, metadataUrlstring

    Des liens vers le jeu de données et son fichier de métadonnées, valables 15 minutes. Appelez GetFocusExport pour obtenir de nouveaux liens.

  • commitmentsUrlstring

    Un lien vers le jeu de données Contract Commitment, présent seulement quand l’export en a un.

Erreurs

  • 404 Not Found - Aucun export de cet espace de travail n’a cet id, il a expiré (les exports sont conservés 7 jours), ou l’export FOCUS n’est pas activé pour cet 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.
  • 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}/focus-exports/{exportId}
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports/{exportId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "id": "string",
   "status": "ready",
   "createdAt": "string",
   "version": "1.2" | "1.4",
   "include": "all" | "non_cloud",
   "from": "string",
   "to": "string",
   "format": "csv" | "parquet",
   "rowCount": number,
   "documentCount": number,
   "commitmentCount": number,
   "expiresAt": "string",
   "downloadUrl": "string",
   "metadataUrl": "string",
   "commitmentsUrl": "string"
}

Lister les sources FOCUS

Liste les sources FOCUS de l’espace de travail avec leur dernière exécution, et indique si l’import est activé.

GET/v1/workspaces/{regionId}/focus-sources

Retour

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

Plus de détails

Renvoie si l’import FOCUS est activé et les sources FOCUS de l’espace de travail, chacune avec sa dernière exécution, les mois qu’elle a conservés et ses clés de tag les plus fréquentes.

Nécessite l’accès 'view' aux factures.

Champs de la réponse

  • enabledboolean

    Si l’import FOCUS est activé pour l’espace de travail.

  • kindstring

    upload : des fichiers que vous téléversez. aws_s3 : un export FOCUS d’AWS Data Exports. azure_blob : un export FOCUS d’Azure Cost Management. gcp_bigquery : la table FOCUS de Google Cloud. oci : les rapports FOCUS d’Oracle Cloud. s3_compatible : un bucket sur n’importe quel stockage compatible S3.

  • periodsArray<string>

    Les mois pour lesquels la source a des chiffres conservés, au format YYYY-MM.

  • lastRunobject

    La dernière lecture : les mois, fichiers et lignes lus, les lignes ignorées par motif, et failure.reason quand status vaut failed.

  • tagKeysArray<string>

    Les clés de tag les plus fréquentes dans les lignes de la source.

  • s3.keyHintstring

    Un court indice de la clé d’accès secrète conservée. Le secret lui-même n’est jamais renvoyé.

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}/focus-sources
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "enabled": boolean,
   "sources": [
      {
         "id": "string",
         "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
         "label": "string",
         "provider": "aws" | "azure" | "gcp" | "oci",
         "connectionId": "string",
         "aws": { "bucket": "string", "prefix": "string", "region": "string" },
         "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
         "gcp": { "table": "string" },
         "oci": { "region": "string" },
         "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
         "periods": [ "string" ],
         "lastRun": {
            "runId": "string",
            "startedAt": "string",
            "finishedAt": "string",
            "status": "ok" | "partial" | "failed",
            "trigger": "schedule" | "manual" | "upload",
            "periods": [ "string" ],
            "files": number,
            "rows": number,
            "skipped": number,
            "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
            "ignoredFiles": number,
            "version": "string",
            "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
         },
         "tagKeys": [ "string" ],
         "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
         "createdAt": "string",
         "updatedAt": "string"
      }
   ]
}

Créer une source FOCUS

Ajoute l’export FOCUS d’un fournisseur cloud comme source que Pleaxy lit chaque jour.

POST/v1/workspaces/{regionId}/focus-sources

Corps

  • kind"aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible"Obligatoire

    Où se trouvent les données FOCUS. Envoyez à côté l’objet du même fournisseur.

  • labelstring

    Facultatif. Un nom pour la source.

  • connectionIdstring

    La connexion cloud à laquelle la source appartient, telle que ListCloudConnections la renvoie. Obligatoire pour tous les types sauf s3_compatible.

  • awsobject

    Pour aws_s3 : le bucket dans lequel AWS Data Exports écrit, le préfixe de l’export (son préfixe S3 et le nom de l’export) et la région du bucket.

  • azureobject

    Pour azure_blob : le compte de stockage, le conteneur et le répertoire de l’export.

  • gcpobject

    Pour gcp_bigquery : la table ou la vue FOCUS, sous la forme project.dataset.table.

  • ociobject

    Pour oci : la région d’origine de la location.

  • s3object

    Pour s3_compatible : l’endpoint HTTPS, la région, le bucket et le préfixe du stockage, et une clé d’accès qui peut le lire. Le secret est conservé chiffré et n’est jamais renvoyé.

Retour

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

Plus de détails

Ajoute une source FOCUS. La source d’un cloud (aws_s3, azure_blob, gcp_bigquery ou oci) appartient à l’une des connexions cloud de l’espace de travail chez le même fournisseur ; elle devient alors la source des lignes IA de cette connexion, à la place de la lecture IA propre au connecteur. Une source s3_compatible apporte sa propre clé d’accès. Pleaxy lit une source chaque jour, et tout de suite avec SyncFocusSource. Une connexion a au plus une source FOCUS.

Session connectée uniquement, avec l’accès 'edit' aux factures : une source ouvre un accès en lecture à votre compte cloud, c’est donc une personne qui l’ajoute et la retire.

Champs de la réponse

  • kindstring

    upload : des fichiers que vous téléversez. aws_s3 : un export FOCUS d’AWS Data Exports. azure_blob : un export FOCUS d’Azure Cost Management. gcp_bigquery : la table FOCUS de Google Cloud. oci : les rapports FOCUS d’Oracle Cloud. s3_compatible : un bucket sur n’importe quel stockage compatible S3.

  • periodsArray<string>

    Les mois pour lesquels la source a des chiffres conservés, au format YYYY-MM.

  • lastRunobject

    La dernière lecture : les mois, fichiers et lignes lus, les lignes ignorées par motif, et failure.reason quand status vaut failed.

  • tagKeysArray<string>

    Les clés de tag les plus fréquentes dans les lignes de la source.

  • s3.keyHintstring

    Un court indice de la clé d’accès secrète conservée. Le secret lui-même n’est jamais renvoyé.

Erreurs

  • 400 Bad Request - Un champ est absent ou invalide, la connexion est d’un autre cloud que kind, ou la connexion a déjà une source FOCUS.
  • 403 Forbidden - L’appelant n’est pas une personne connectée (par exemple, une clé API), ou n’a pas l’accès 'edit' aux factures.
  • 404 Not Found - Aucune connexion cloud de cet espace de travail n’a ce connectionId, ou l’import FOCUS n’est pas activé pour cet 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.
POST /v1/workspaces/{regionId}/focus-sources
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "kind": "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "secretAccessKey": "string" }
}
Réponse · 201 Created
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Obtenir une source FOCUS

Obtient une source FOCUS avec sa dernière exécution.

GET/v1/workspaces/{regionId}/focus-sources/{sourceId}

Paramètres

  • sourceIdstringObligatoire

    L’id de la source FOCUS, tel que ListFocusSources le renvoie.

Retour

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

Plus de détails

Renvoie une source FOCUS avec sa dernière exécution. Interrogez-la après SyncFocusSource ou CompleteFocusUpload pour savoir quand la lecture est terminée.

Nécessite l’accès 'view' aux factures.

Champs de la réponse

  • kindstring

    upload : des fichiers que vous téléversez. aws_s3 : un export FOCUS d’AWS Data Exports. azure_blob : un export FOCUS d’Azure Cost Management. gcp_bigquery : la table FOCUS de Google Cloud. oci : les rapports FOCUS d’Oracle Cloud. s3_compatible : un bucket sur n’importe quel stockage compatible S3.

  • periodsArray<string>

    Les mois pour lesquels la source a des chiffres conservés, au format YYYY-MM.

  • lastRunobject

    La dernière lecture : les mois, fichiers et lignes lus, les lignes ignorées par motif, et failure.reason quand status vaut failed.

  • tagKeysArray<string>

    Les clés de tag les plus fréquentes dans les lignes de la source.

  • s3.keyHintstring

    Un court indice de la clé d’accès secrète conservée. Le secret lui-même n’est jamais renvoyé.

Erreurs

  • 404 Not Found - Aucune source FOCUS de cet espace de travail n’a cet id, ou l’import FOCUS n’est pas activé pour cet 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.
  • 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}/focus-sources/{sourceId}
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Synchroniser une source FOCUS

Lit une source FOCUS maintenant, en arrière-plan.

POST/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync

Paramètres

  • sourceIdstringObligatoire

    L’id de la source FOCUS, tel que ListFocusSources le renvoie.

Retour

202 Accepted avec l’objet présenté dans la réponse.

Plus de détails

Lance une lecture de la source en arrière-plan, qui relit les mois qu’elle contient, et renvoie la source. Son lastRun montre le résultat une fois la lecture terminée.

Nécessite l’accès 'edit' aux factures. Une clé API peut l’appeler.

Champs de la réponse

  • kindstring

    upload : des fichiers que vous téléversez. aws_s3 : un export FOCUS d’AWS Data Exports. azure_blob : un export FOCUS d’Azure Cost Management. gcp_bigquery : la table FOCUS de Google Cloud. oci : les rapports FOCUS d’Oracle Cloud. s3_compatible : un bucket sur n’importe quel stockage compatible S3.

  • periodsArray<string>

    Les mois pour lesquels la source a des chiffres conservés, au format YYYY-MM.

  • lastRunobject

    La dernière lecture : les mois, fichiers et lignes lus, les lignes ignorées par motif, et failure.reason quand status vaut failed.

  • tagKeysArray<string>

    Les clés de tag les plus fréquentes dans les lignes de la source.

  • s3.keyHintstring

    Un court indice de la clé d’accès secrète conservée. Le secret lui-même n’est jamais renvoyé.

Erreurs

  • 400 Bad Request - La source est la source des téléversements, lue à l’arrivée d’un fichier : téléversez de nouveau le fichier pour le relire.
  • 404 Not Found - Aucune source FOCUS de cet espace de travail n’a cet id, ou l’import FOCUS n’est pas activé pour cet espace de travail.
  • 503 Service Unavailable - La lecture ne peut pas être lancée pour le moment. Réessayez dans quelques minutes.
  • 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}/focus-sources/{sourceId}/sync
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 202 Accepted
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Supprimer une source FOCUS

Retire une source FOCUS avec les mois qu’elle a conservés.

DELETE/v1/workspaces/{regionId}/focus-sources/{sourceId}

Paramètres

  • sourceIdstringObligatoire

    L’id de la source FOCUS, tel que ListFocusSources le renvoie.

Retour

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

Plus de détails

Retire la source avec les mois et les lignes IA qu’elle a conservés. La lecture IA propre au connecteur reprend pour sa connexion cloud.

Session connectée uniquement, avec l’accès 'edit' aux factures : une source ouvre un accès en lecture à votre compte cloud, c’est donc une personne qui l’ajoute et la retire.

Erreurs

  • 403 Forbidden - L’appelant n’est pas une personne connectée (par exemple, une clé API), ou n’a pas l’accès 'edit' aux factures.
  • 404 Not Found - Aucune source FOCUS de cet espace de travail n’a cet id, ou l’import FOCUS n’est pas activé pour cet 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}/focus-sources/{sourceId}
Requête
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "removed": true
}

Obtenir une période de source FOCUS

Obtient un mois conservé d’une source FOCUS, par facture, centre de coûts et émetteur.

GET/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}

Paramètres

  • sourceIdstringObligatoire

    L’id de la source FOCUS, tel que ListFocusSources le renvoie.

  • periodstringObligatoire

    Le mois, au format YYYY-MM.

Retour

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

Plus de détails

Renvoie un mois conservé d’une source : ses totaux par devise, chaque facture par numéro avec ses montants par catégorie et par service, les dépenses par centre de coûts et les totaux par émetteur.

Nécessite l’accès 'view' aux factures.

Champs de la réponse

  • totalsobject

    Le total facturé du mois, par code de devise.

  • invoicesArray<object>

    Chaque facture que nomment les lignes du mois, avec son total et ses montants par catégorie et par service.

  • costCentersArray<object>

    Les dépenses du mois par centre de coûts, telles que les règles d’attribution par tags de l’espace de travail les affectent.

Erreurs

  • 400 Bad Request - period n’est pas un mois écrit sous la forme YYYY-MM.
  • 404 Not Found - La source n’a pas de chiffres conservés pour ce mois, aucune source FOCUS de cet espace de travail n’a cet id, ou l’import FOCUS n’est pas activé pour cet 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.
  • 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}/focus-sources/{sourceId}/periods/{period}
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "sourceId": "string",
   "period": "string",
   "rows": number,
   "version": "string",
   "asOf": "string",
   "totals": { "USD": number },
   "issuers": { "string": { "USD": number } },
   "invoices": [
      {
         "issuer": "string",
         "billingAccountId": "string",
         "invoiceId": "string",
         "currency": "string",
         "total": number,
         "byCategory": { "string": number },
         "byService": { "string": number },
         "corrections": number
      }
   ],
   "costCenters": [ { "costCenter": "string", "serviceCategory": "string", "currency": "string", "amount": number } ]
}

Créer un téléversement FOCUS

Lance le téléversement d’un fichier FOCUS et renvoie l’URL à laquelle l’envoyer.

POST/v1/workspaces/{regionId}/focus-sources/uploads

Corps

  • fileNamestringObligatoire

    Le nom du fichier, se terminant par .csv ou .csv.gz.

Retour

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

Plus de détails

Lance le téléversement d’un fichier FOCUS. Le fichier est en CSV ou en CSV compressé avec gzip (.csv ou .csv.gz), jusqu’à 500 MB. Envoyez-le par PUT à uploadUrl avec le contentType renvoyé, puis appelez CompleteFocusUpload. L’URL est valable quelques minutes. Les fichiers téléversés vont dans la source des téléversements de l’espace de travail, sourceId.

Nécessite l’accès 'edit' aux factures. Une clé API peut l’appeler.

Erreurs

  • 400 Bad Request - Le nom du fichier ne se termine pas par .csv ou .csv.gz (« Upload a FOCUS file as CSV, or gzipped CSV (.csv.gz). Parquet files are read in a later release. »).
  • 404 Not Found - L’import FOCUS n’est pas activé pour cet espace de travail (« FOCUS import isn't switched on for this workspace yet. »).
  • 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}/focus-sources/uploads
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "fileName": "string"
}
Réponse · 201 Created
{
   "sourceId": "string",
   "uploadId": "string",
   "uploadUrl": "string",
   "contentType": "string",
   "maxBytes": number
}

Terminer un téléversement FOCUS

Signale à Pleaxy qu’un fichier FOCUS téléversé est en place, pour qu’il soit lu.

POST/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete

Paramètres

  • uploadIdstringObligatoire

    L’id du téléversement, tel que CreateFocusUpload le renvoie.

Retour

202 Accepted avec l’objet présenté dans la réponse.

Plus de détails

Indique que le fichier est téléversé. Pleaxy le lit en arrière-plan et renvoie la source des téléversements ; son lastRun montre le résultat une fois la lecture terminée.

Nécessite l’accès 'edit' aux factures. Une clé API peut l’appeler.

Champs de la réponse

  • kindstring

    upload : des fichiers que vous téléversez. aws_s3 : un export FOCUS d’AWS Data Exports. azure_blob : un export FOCUS d’Azure Cost Management. gcp_bigquery : la table FOCUS de Google Cloud. oci : les rapports FOCUS d’Oracle Cloud. s3_compatible : un bucket sur n’importe quel stockage compatible S3.

  • periodsArray<string>

    Les mois pour lesquels la source a des chiffres conservés, au format YYYY-MM.

  • lastRunobject

    La dernière lecture : les mois, fichiers et lignes lus, les lignes ignorées par motif, et failure.reason quand status vaut failed.

  • tagKeysArray<string>

    Les clés de tag les plus fréquentes dans les lignes de la source.

  • s3.keyHintstring

    Un court indice de la clé d’accès secrète conservée. Le secret lui-même n’est jamais renvoyé.

Erreurs

  • 400 Bad Request - Le fichier dépasse 500 MB, ou uploadId n’est pas un id de téléversement.
  • 404 Not Found - Aucun téléversement avec cet id n’est en attente dans cet espace de travail : téléversez de nouveau le fichier. Également quand l’import FOCUS n’est pas activé pour cet 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.
  • 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}/focus-sources/uploads/{uploadId}/complete
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 202 Accepted
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Lister les émetteurs FOCUS

Liste les émetteurs de factures des mois FOCUS conservés et le fournisseur auquel chacun correspond.

GET/v1/workspaces/{regionId}/focus-sources/issuers

Retour

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

Plus de détails

Renvoie chaque émetteur de factures des mois FOCUS conservés (les trois derniers par source), avec ce qu’il a facturé par devise et le fournisseur auquel il correspond, s’il y en a un.

Nécessite l’accès 'view' aux factures.

Champs de la réponse

  • issuerstring

    Le nom de l’émetteur de la facture tel que les fichiers FOCUS le donnent.

  • mappedBy"person" | "name"

    person : quelqu’un a associé l’émetteur au fournisseur. name : Pleaxy a reconnu un émetteur connu (AWS, Microsoft, Google, Oracle) à son nom. Absent quand l’émetteur n’a pas de fournisseur.

  • totalsobject

    Ce que l’émetteur a facturé sur les mois conservés, par code de devise.

Erreurs

  • 404 Not Found - L’import FOCUS n’est pas activé pour cet espace de travail (« FOCUS import isn't switched on for this workspace yet. »).
  • 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}/focus-sources/issuers
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]

Associer un émetteur FOCUS

Associe un émetteur de factures FOCUS à l’un de vos fournisseurs, ou oublie l’association.

PUT/v1/workspaces/{regionId}/focus-sources/issuers/{issuer}

Paramètres

  • issuerstringObligatoire

    Le nom de l’émetteur tel que les fichiers FOCUS le donnent, encodé pour une URL.

Corps

  • supplierConnectionIdstring | null

    L’id de connexion du fournisseur. null, ou son omission, oublie l’association.

Retour

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

Plus de détails

Associe un émetteur de factures à l’un des fournisseurs de l’espace de travail. Renvoie les émetteurs comme le fait ListFocusIssuers.

Nécessite l’accès 'edit' aux factures. Une clé API peut l’appeler.

Champs de la réponse

  • issuerstring

    Le nom de l’émetteur de la facture tel que les fichiers FOCUS le donnent.

  • mappedBy"person" | "name"

    person : quelqu’un a associé l’émetteur au fournisseur. name : Pleaxy a reconnu un émetteur connu (AWS, Microsoft, Google, Oracle) à son nom. Absent quand l’émetteur n’a pas de fournisseur.

  • totalsobject

    Ce que l’émetteur a facturé sur les mois conservés, par code de devise.

Erreurs

  • 400 Bad Request - Le nom de l’émetteur est vide ou trop long.
  • 404 Not Found - Aucun fournisseur de cet espace de travail n’a ce supplierConnectionId, ou l’import FOCUS n’est pas activé pour cet 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.
  • 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.
PUT /v1/workspaces/{regionId}/focus-sources/issuers/{issuer}
Requête
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers/{issuer}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "supplierConnectionId": "string" | null
}
Réponse · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]
Nous contacter