Riferimento API

FOCUS

Esporta le tue fatture come dataset FOCUS e leggi i dati di fatturazione FOCUS dei tuoi provider.

Altro su questa risorsa

FOCUS è il formato aperto della FinOps Foundation per i dati di fatturazione. Pleaxy lo usa in entrambe le direzioni. Un’esportazione scrive le fatture, le note di debito e le note di credito accettate del workspace come dataset FOCUS Cost and Usage, per uno strumento FinOps o di reportistica. Un’origine FOCUS legge dati di fatturazione in quel formato, da file che carichi o dall’esportazione FOCUS del provider stesso, e conserva i totali di ogni mese per fattura, emittente e centro di costo. Esportazione e importazione si attivano per workspace; finché una è disattivata, i suoi endpoint rispondono 404.

Elencare le esportazioni FOCUS

Elenca le esportazioni FOCUS degli ultimi 7 giorni e se l’esportazione è attiva.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce se l’esportazione FOCUS è attiva per il workspace e le sue esportazioni degli ultimi 7 giorni, dalla più recente, al massimo 20. L’elenco non contiene link di download; ottienili con GetFocusExport.

Richiede l’accesso 'view' alle fatture. Una chiave API può chiamarlo.

Campi della risposta

  • enabledboolean

    Se l’esportazione FOCUS è attiva per il workspace.

  • from, tostring

    Il primo e l’ultimo periodo di fatturazione dell’esportazione, come YYYY-MM.

  • rowCount, documentCountnumber

    Le righe del dataset e le fatture, note di debito e note di credito da cui provengono.

  • expiresAtstring

    Quando Pleaxy elimina i file dell’esportazione, 7 giorni dopo la sua creazione.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/focus-exports
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
      }
   ]
}

Creare un’esportazione FOCUS

Esporta le fatture di un intervallo di mesi come dataset FOCUS.

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

Corpo

  • fromstringObbligatorio

    Il primo periodo di fatturazione, come YYYY-MM.

  • tostringObbligatorio

    L’ultimo periodo di fatturazione, come YYYY-MM, incluso. L’intervallo copre al massimo 36 mesi.

  • version"1.2" | "1.4"

    La versione di FOCUS. 1.2 se assente. Un’esportazione 1.4 può contenere anche un dataset Contract Commitment.

  • include"all" | "non_cloud"

    non_cloud esclude le fatture dei provider cloud e IA, che uno strumento FinOps può leggere dalle esportazioni FOCUS dei provider stessi. all se assente.

  • format"csv" | "parquet"

    Il formato del file. csv se assente.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Scrive le fatture, le note di debito e le note di credito accettate del workspace per i periodi di fatturazione from..to come dataset FOCUS Cost and Usage con un file di metadati. C’è una riga per voce, voce d’imposta e rettifica; le note di credito sono negative; gli importi restano nella valuta di ciascun documento. La risposta contiene link di download validi per 15 minuti, e i file vengono conservati per 7 giorni. Un’esportazione non cambia nulla nel workspace.

Richiede l’accesso 'view' alle fatture. Una chiave API può chiamarlo.

Campi della risposta

  • from, tostring

    Il primo e l’ultimo periodo di fatturazione dell’esportazione, come YYYY-MM.

  • rowCount, documentCountnumber

    Le righe del dataset e le fatture, note di debito e note di credito da cui provengono.

  • expiresAtstring

    Quando Pleaxy elimina i file dell’esportazione, 7 giorni dopo la sua creazione.

  • downloadUrl, metadataUrlstring

    Link al dataset e al suo file di metadati, validi per 15 minuti. Chiama GetFocusExport per ottenere link nuovi.

  • commitmentsUrlstring

    Un link al dataset Contract Commitment, presente solo quando l’esportazione ne ha uno.

Errori

  • 400 Bad Request - from o to non è un mese scritto come YYYY-MM, from è successivo a to, oppure l’intervallo copre più di 36 mesi.
  • 404 Not Found - L’esportazione FOCUS non è attiva per questo workspace ("FOCUS export isn't switched on for this workspace yet.").
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/focus-exports
Richiesta
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/focus-exports
{
   "from": "2026-07",
   "to": "2026-09",
   "include": "non_cloud"
}
Risposta · 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://..."
}

Ottenere un’esportazione FOCUS

Ottiene un’esportazione FOCUS con link di download nuovi.

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

Parametri

  • exportIdstringObbligatorio

    L’id dell’esportazione, come lo restituisce CreateFocusExport.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce un’esportazione degli ultimi 7 giorni con link nuovi al suo dataset e al suo file di metadati, validi per 15 minuti.

Richiede l’accesso 'view' alle fatture. Una chiave API può chiamarlo.

Campi della risposta

  • from, tostring

    Il primo e l’ultimo periodo di fatturazione dell’esportazione, come YYYY-MM.

  • rowCount, documentCountnumber

    Le righe del dataset e le fatture, note di debito e note di credito da cui provengono.

  • expiresAtstring

    Quando Pleaxy elimina i file dell’esportazione, 7 giorni dopo la sua creazione.

  • downloadUrl, metadataUrlstring

    Link al dataset e al suo file di metadati, validi per 15 minuti. Chiama GetFocusExport per ottenere link nuovi.

  • commitmentsUrlstring

    Un link al dataset Contract Commitment, presente solo quando l’esportazione ne ha uno.

Errori

  • 404 Not Found - Nessuna esportazione in questo workspace ha questo id, è scaduta (le esportazioni vengono conservate per 7 giorni), oppure l’esportazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/focus-exports/{exportId}
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports/{exportId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Elencare le origini FOCUS

Elenca le origini FOCUS del workspace con la loro ultima esecuzione e se l’importazione è attiva.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce se l’importazione FOCUS è attiva e le origini FOCUS del workspace, ciascuna con la sua ultima esecuzione, i mesi che ha conservato e le sue chiavi di tag più comuni.

Richiede l’accesso 'view' alle fatture.

Campi della risposta

  • enabledboolean

    Se l’importazione FOCUS è attiva per il workspace.

  • kindstring

    upload: file che carichi. aws_s3: un’esportazione FOCUS di AWS Data Exports. azure_blob: un’esportazione FOCUS di Azure Cost Management. gcp_bigquery: la tabella FOCUS di Google Cloud. oci: i report FOCUS di Oracle Cloud. s3_compatible: un bucket su qualsiasi storage compatibile con S3.

  • periodsArray<string>

    I mesi per cui l’origine ha cifre conservate, come YYYY-MM.

  • lastRunobject

    L’ultima lettura: i mesi, i file e le righe letti, le righe saltate per motivo, e failure.reason quando status è failed.

  • tagKeysArray<string>

    Le chiavi di tag più comuni nelle righe dell’origine.

  • s3.keyHintstring

    Un breve indizio di quale chiave di accesso segreta è conservata. Il segreto in sé non viene mai restituito.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/focus-sources
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
      }
   ]
}

Creare un’origine FOCUS

Aggiunge l’esportazione FOCUS di un provider come origine che Pleaxy legge ogni giorno.

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

Corpo

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

    Dove si trovano i dati FOCUS. Invia accanto l’oggetto dello stesso provider.

  • labelstring

    Facoltativo. Un nome per l’origine.

  • connectionIdstring

    La connessione cloud a cui appartiene l’origine, come la restituisce ListCloudConnections. Obbligatoria per tutti i tipi tranne s3_compatible.

  • awsobject

    Per aws_s3: il bucket in cui scrive AWS Data Exports, il prefisso dell’esportazione (il suo prefisso S3 e il nome dell’esportazione) e la regione del bucket.

  • azureobject

    Per azure_blob: l’account di archiviazione, il contenitore e la directory dell’esportazione.

  • gcpobject

    Per gcp_bigquery: la tabella o la vista FOCUS, come project.dataset.table.

  • ociobject

    Per oci: la regione principale della tenancy.

  • s3object

    Per s3_compatible: l’endpoint HTTPS, la regione, il bucket e il prefisso dello storage, e una chiave di accesso che possa leggerlo. Il segreto viene conservato cifrato e non viene mai restituito.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Aggiunge un’origine FOCUS. L’origine di un cloud (aws_s3, azure_blob, gcp_bigquery o oci) appartiene a una delle connessioni cloud del workspace dello stesso provider; diventa quindi l’origine delle voci IA di quella connessione, al posto della lettura IA propria del connettore. Un’origine s3_compatible porta la propria chiave di accesso. Pleaxy legge un’origine ogni giorno, e subito con SyncFocusSource. Una connessione ha al massimo un’origine FOCUS.

Solo sessione con accesso effettuato, con accesso 'edit' alle fatture: un’origine apre un percorso di lettura verso il tuo account cloud, quindi è una persona ad aggiungerla e rimuoverla.

Campi della risposta

  • kindstring

    upload: file che carichi. aws_s3: un’esportazione FOCUS di AWS Data Exports. azure_blob: un’esportazione FOCUS di Azure Cost Management. gcp_bigquery: la tabella FOCUS di Google Cloud. oci: i report FOCUS di Oracle Cloud. s3_compatible: un bucket su qualsiasi storage compatibile con S3.

  • periodsArray<string>

    I mesi per cui l’origine ha cifre conservate, come YYYY-MM.

  • lastRunobject

    L’ultima lettura: i mesi, i file e le righe letti, le righe saltate per motivo, e failure.reason quando status è failed.

  • tagKeysArray<string>

    Le chiavi di tag più comuni nelle righe dell’origine.

  • s3.keyHintstring

    Un breve indizio di quale chiave di accesso segreta è conservata. Il segreto in sé non viene mai restituito.

Errori

  • 400 Bad Request - Un campo manca o non è valido, la connessione è di un cloud diverso da kind, oppure la connessione ha già un’origine FOCUS.
  • 403 Forbidden - Il chiamante non è una persona che ha effettuato l’accesso (per esempio, una chiave API), oppure non ha l’accesso 'edit' alle fatture.
  • 404 Not Found - Nessuna connessione cloud in questo workspace ha questo connectionId, oppure l’importazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
POST /v1/workspaces/{regionId}/focus-sources
Richiesta
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" }
}
Risposta · 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"
}

Ottenere un’origine FOCUS

Ottiene un’origine FOCUS con la sua ultima esecuzione.

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

Parametri

  • sourceIdstringObbligatorio

    L’id dell’origine FOCUS, come lo restituisce ListFocusSources.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce un’origine FOCUS con la sua ultima esecuzione. Interrogala dopo SyncFocusSource o CompleteFocusUpload per sapere quando la lettura è terminata.

Richiede l’accesso 'view' alle fatture.

Campi della risposta

  • kindstring

    upload: file che carichi. aws_s3: un’esportazione FOCUS di AWS Data Exports. azure_blob: un’esportazione FOCUS di Azure Cost Management. gcp_bigquery: la tabella FOCUS di Google Cloud. oci: i report FOCUS di Oracle Cloud. s3_compatible: un bucket su qualsiasi storage compatibile con S3.

  • periodsArray<string>

    I mesi per cui l’origine ha cifre conservate, come YYYY-MM.

  • lastRunobject

    L’ultima lettura: i mesi, i file e le righe letti, le righe saltate per motivo, e failure.reason quando status è failed.

  • tagKeysArray<string>

    Le chiavi di tag più comuni nelle righe dell’origine.

  • s3.keyHintstring

    Un breve indizio di quale chiave di accesso segreta è conservata. Il segreto in sé non viene mai restituito.

Errori

  • 404 Not Found - Nessuna origine FOCUS in questo workspace ha questo id, oppure l’importazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/focus-sources/{sourceId}
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Sincronizzare un’origine FOCUS

Legge un’origine FOCUS adesso, in background.

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

Parametri

  • sourceIdstringObbligatorio

    L’id dell’origine FOCUS, come lo restituisce ListFocusSources.

Restituisce

202 Accepted con l’oggetto mostrato nella risposta.

Più dettagli

Avvia in background una lettura dell’origine, che rilegge i mesi che contiene, e restituisce l’origine. Il suo lastRun mostra il risultato una volta terminata la lettura.

Richiede l’accesso 'edit' alle fatture. Una chiave API può chiamarlo.

Campi della risposta

  • kindstring

    upload: file che carichi. aws_s3: un’esportazione FOCUS di AWS Data Exports. azure_blob: un’esportazione FOCUS di Azure Cost Management. gcp_bigquery: la tabella FOCUS di Google Cloud. oci: i report FOCUS di Oracle Cloud. s3_compatible: un bucket su qualsiasi storage compatibile con S3.

  • periodsArray<string>

    I mesi per cui l’origine ha cifre conservate, come YYYY-MM.

  • lastRunobject

    L’ultima lettura: i mesi, i file e le righe letti, le righe saltate per motivo, e failure.reason quando status è failed.

  • tagKeysArray<string>

    Le chiavi di tag più comuni nelle righe dell’origine.

  • s3.keyHintstring

    Un breve indizio di quale chiave di accesso segreta è conservata. Il segreto in sé non viene mai restituito.

Errori

  • 400 Bad Request - L’origine è l’origine dei caricamenti, che viene letta all’arrivo di un file: carica di nuovo il file per rileggerlo.
  • 404 Not Found - Nessuna origine FOCUS in questo workspace ha questo id, oppure l’importazione FOCUS non è attiva per questo workspace.
  • 503 Service Unavailable - La lettura non può essere avviata in questo momento. Riprova tra qualche minuto.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/focus-sources/{sourceId}/sync
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Eliminare un’origine FOCUS

Rimuove un’origine FOCUS con i mesi che ha conservato.

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

Parametri

  • sourceIdstringObbligatorio

    L’id dell’origine FOCUS, come lo restituisce ListFocusSources.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Rimuove l’origine con i mesi e le voci IA che ha conservato. La lettura IA propria del connettore riprende per la sua connessione cloud.

Solo sessione con accesso effettuato, con accesso 'edit' alle fatture: un’origine apre un percorso di lettura verso il tuo account cloud, quindi è una persona ad aggiungerla e rimuoverla.

Errori

  • 403 Forbidden - Il chiamante non è una persona che ha effettuato l’accesso (per esempio, una chiave API), oppure non ha l’accesso 'edit' alle fatture.
  • 404 Not Found - Nessuna origine FOCUS in questo workspace ha questo id, oppure l’importazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
DELETE /v1/workspaces/{regionId}/focus-sources/{sourceId}
Richiesta
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "removed": true
}

Ottenere un periodo di un’origine FOCUS

Ottiene un mese conservato di un’origine FOCUS, per fattura, centro di costo ed emittente.

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

Parametri

  • sourceIdstringObbligatorio

    L’id dell’origine FOCUS, come lo restituisce ListFocusSources.

  • periodstringObbligatorio

    Il mese, come YYYY-MM.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce un mese conservato di un’origine: i suoi totali per valuta, ogni fattura per numero con i suoi importi per categoria e servizio, la spesa per centro di costo e i totali per emittente.

Richiede l’accesso 'view' alle fatture.

Campi della risposta

  • totalsobject

    Il totale fatturato del mese, per codice di valuta.

  • invoicesArray<object>

    Ogni fattura nominata dalle righe del mese, con il suo totale e i suoi importi per categoria e per servizio.

  • costCentersArray<object>

    La spesa del mese per centro di costo, come la assegnano le regole di attribuzione per tag del workspace.

Errori

  • 400 Bad Request - period non è un mese scritto come YYYY-MM.
  • 404 Not Found - L’origine non ha cifre conservate per questo mese, nessuna origine FOCUS in questo workspace ha questo id, oppure l’importazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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 } ]
}

Creare un caricamento FOCUS

Avvia il caricamento di un file FOCUS e restituisce l’URL a cui inviarlo.

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

Corpo

  • fileNamestringObbligatorio

    Il nome del file, che termina con .csv o .csv.gz.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Avvia il caricamento di un file FOCUS. Il file è CSV o CSV compresso con gzip (.csv o .csv.gz), fino a 500 MB. Invialo con PUT a uploadUrl con il contentType restituito, poi chiama CompleteFocusUpload. L’URL è valido per qualche minuto. I file caricati vanno nell’origine dei caricamenti del workspace, sourceId.

Richiede l’accesso 'edit' alle fatture. Una chiave API può chiamarlo.

Errori

  • 400 Bad Request - Il nome del file non termina con .csv o .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’importazione FOCUS non è attiva per questo workspace ("FOCUS import isn't switched on for this workspace yet.").
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/focus-sources/uploads
Richiesta
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"
}
Risposta · 201 Created
{
   "sourceId": "string",
   "uploadId": "string",
   "uploadUrl": "string",
   "contentType": "string",
   "maxBytes": number
}

Completare un caricamento FOCUS

Comunica a Pleaxy che un file FOCUS caricato è al suo posto, così viene letto.

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

Parametri

  • uploadIdstringObbligatorio

    L’id del caricamento, come lo restituisce CreateFocusUpload.

Restituisce

202 Accepted con l’oggetto mostrato nella risposta.

Più dettagli

Dice che il file è stato caricato. Pleaxy lo legge in background e restituisce l’origine dei caricamenti; il suo lastRun mostra il risultato una volta terminata la lettura.

Richiede l’accesso 'edit' alle fatture. Una chiave API può chiamarlo.

Campi della risposta

  • kindstring

    upload: file che carichi. aws_s3: un’esportazione FOCUS di AWS Data Exports. azure_blob: un’esportazione FOCUS di Azure Cost Management. gcp_bigquery: la tabella FOCUS di Google Cloud. oci: i report FOCUS di Oracle Cloud. s3_compatible: un bucket su qualsiasi storage compatibile con S3.

  • periodsArray<string>

    I mesi per cui l’origine ha cifre conservate, come YYYY-MM.

  • lastRunobject

    L’ultima lettura: i mesi, i file e le righe letti, le righe saltate per motivo, e failure.reason quando status è failed.

  • tagKeysArray<string>

    Le chiavi di tag più comuni nelle righe dell’origine.

  • s3.keyHintstring

    Un breve indizio di quale chiave di accesso segreta è conservata. Il segreto in sé non viene mai restituito.

Errori

  • 400 Bad Request - Il file supera i 500 MB, oppure uploadId non è un id di caricamento.
  • 404 Not Found - Nessun caricamento con questo id è in attesa in questo workspace: carica di nuovo il file. Anche quando l’importazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Elencare gli emittenti FOCUS

Elenca gli emittenti di fatture nei mesi FOCUS conservati e il fornitore a cui ciascuno corrisponde.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce ogni emittente di fatture nei mesi FOCUS conservati (gli ultimi tre per origine), con quanto ha fatturato per valuta e il fornitore a cui corrisponde, se c’è.

Richiede l’accesso 'view' alle fatture.

Campi della risposta

  • issuerstring

    Il nome dell’emittente della fattura come lo riportano i file FOCUS.

  • mappedBy"person" | "name"

    person: qualcuno ha associato l’emittente al fornitore. name: Pleaxy ha riconosciuto dal nome un emittente noto (AWS, Microsoft, Google, Oracle). Assente quando l’emittente non ha un fornitore.

  • totalsobject

    Quanto ha fatturato l’emittente nei mesi conservati, per codice di valuta.

Errori

  • 404 Not Found - L’importazione FOCUS non è attiva per questo workspace ("FOCUS import isn't switched on for this workspace yet.").
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/focus-sources/issuers
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]

Associare un emittente FOCUS

Associa un emittente di fatture FOCUS a uno dei tuoi fornitori, o dimentica l’associazione.

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

Parametri

  • issuerstringObbligatorio

    Il nome dell’emittente come lo riportano i file FOCUS, codificato per URL.

Corpo

  • supplierConnectionIdstring | null

    L’id di connessione del fornitore. null, oppure ometterlo, dimentica l’associazione.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Associa un emittente di fatture a uno dei fornitori del workspace. Restituisce gli emittenti come fa ListFocusIssuers.

Richiede l’accesso 'edit' alle fatture. Una chiave API può chiamarlo.

Campi della risposta

  • issuerstring

    Il nome dell’emittente della fattura come lo riportano i file FOCUS.

  • mappedBy"person" | "name"

    person: qualcuno ha associato l’emittente al fornitore. name: Pleaxy ha riconosciuto dal nome un emittente noto (AWS, Microsoft, Google, Oracle). Assente quando l’emittente non ha un fornitore.

  • totalsobject

    Quanto ha fatturato l’emittente nei mesi conservati, per codice di valuta.

Errori

  • 400 Bad Request - Il nome dell’emittente è vuoto o troppo lungo.
  • 404 Not Found - Nessun fornitore in questo workspace ha questo supplierConnectionId, oppure l’importazione FOCUS non è attiva per questo workspace.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
PUT /v1/workspaces/{regionId}/focus-sources/issuers/{issuer}
Richiesta
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
}
Risposta · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]
Contattaci