Pleaxy

Emetti ordini d’acquisto, approva e paga le fatture e configura il tuo spazio di lavoro.

Riferimento API

Connessioni cloud

Collegamenti in sola lettura alla fatturazione dei tuoi account presso i provider cloud.

Altro su questa risorsa

Una connessione cloud dà a Pleaxy accesso in sola lettura alla fatturazione di un account presso un provider cloud, tramite un accesso che crei nel tuo account con uno script di configurazione. AWS usa un ruolo IAM cross-account, Google Cloud la Workload Identity Federation e Azure una credenziale federata, ciascuno per sessioni di breve durata senza memorizzare alcuna chiave di lunga durata. Oracle Cloud usa una chiave di firma API che Pleaxy genera per la connessione; tu carichi solo la chiave pubblica. La connessione richiede due chiamate: init restituisce i valori necessari allo script di configurazione, poi CreateCloudConnection verifica l’accesso e completa la connessione. Solo la persona che ha avviato una configurazione può completarla o annullarla.

Endpoint

Elencare le connessioni cloud

Elenca le connessioni cloud del workspace.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Elenca le connessioni cloud del workspace, comprese le configurazioni ancora in corso (status pending). Non restituisce mai segreti né gli identificativi usati dalla configurazione (ARN del ruolo, external ID, service account, OCID, ID del tenant o dell’app).

Campi della risposta

  • dataSourcesArray<"invoices" | "current_cost">

    Cosa può leggere Pleaxy: fatture emesse e/o costo del mese in corso. Se assente, entrambi.

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

    L’esito dell’ultima sincronizzazione della fatturazione. lastSyncErrorCode indica perché è fallita: throttled, access_revoked, platform_config, data_not_enabled o unknown.

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}/cloud-connections
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
   }
]

Avviare una connessione cloud AWS

Avvia il collegamento di un account AWS.

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

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Avvia il collegamento di un account AWS e restituisce i valori da passare allo script di configurazione (CloudFormation, CDK o CLI), che crea un ruolo IAM in sola lettura nel tuo account. Chiamarlo di nuovo restituisce la tua configurazione non ancora completata, con lo stesso external ID. Non accetta un corpo.

Campi della risposta

  • connectionIdstring

    Passalo a CreateCloudConnection come awsConnectionId.

  • cloudFormationTemplateUrlstring

    Assente quando questo deployment non pubblica alcun template CloudFormation; in tal caso usa lo script CDK o CLI.

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.
POST /v1/workspaces/{regionId}/cloud-connections/aws/init
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/aws/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 201 Created
{
   "connectionId": "string",
   "platformAwsAccountId": "string",
   "externalId": "string",
   "cloudFormationTemplateUrl": "string"
}

Avviare una connessione cloud

Avvia il collegamento di un account Google Cloud, Azure o Oracle Cloud.

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

Parametri

  • provider"gcp" | "azure" | "oci"Obbligatorio

    Il provider da collegare.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Come InitAwsCloudConnection, per Google Cloud, Azure o Oracle Cloud: restituisce i valori per connessione che lo script di configurazione di quel provider fissa, compreso un connectionId da passare a CreateCloudConnection (come gcpConnectionId, azureConnectionId o ociConnectionId). Chiamarlo di nuovo restituisce la tua configurazione non ancora completata. Non accetta un corpo.

Campi della risposta

  • gcpobject

    connectionId, platformAwsAccountId, federationRoleArn, expectedSubject, poolId e providerId: i valori di Workload Identity Federation che lo script di configurazione fissa.

  • azureobject

    connectionId, issuer, subject, audience, appDisplayName e credentialName: la credenziale federata che lo script di configurazione crea sulla tua app.

  • ociobject

    connectionId, publicKeyPem, fingerprint e regions: la chiave pubblica da caricare sull’utente pleaxy-billing e le home region tra cui scegliere.

Errori

  • 404 Not Found - Il connettore reale di questo provider non è attivo in questo deployment ("Real connections to this provider aren't switched on.").
  • 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}/cloud-connections/{provider}/init
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 201 Created
{
   "connectionId": "string",
   ...the provider's setup values
}

Individuare gli ambiti di fatturazione Azure

Elenca i profili di fatturazione Azure che puoi collegare.

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

Corpo

  • azureConnectionIdstringObbligatorio

    connectionId di InitCloudConnection.

  • azureTenantIdstringObbligatorio

    Il tenant Microsoft Entra in cui è stata registrata l’app (GUID).

  • azureClientIdstringObbligatorio

    L’ID applicazione (client) della registrazione dell’app (GUID).

  • azureBillingAccountIdstringObbligatorio

    L’ID dell’account di fatturazione Microsoft Customer Agreement (<guid>:<guid>_YYYY-MM-DD).

  • azureBillingProfileIdstringObbligatorio

    L’ID del profilo di fatturazione su cui l’app ha il ruolo Billing profile reader.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Solo Azure, tra init e CreateCloudConnection: verifica il tenant ID e l’ID dell’app (client) stampati dallo script di configurazione, e legge l’account di fatturazione Microsoft Customer Agreement e il profilo di fatturazione che indichi, così puoi scegliere il profilo da collegare. Può chiamarlo solo la persona che ha avviato la configurazione, e conta ai fini dello stesso limite di tentativi e periodo di attesa di CreateCloudConnection.

Errori

  • 404 Not Found - Il connettore reale di Azure non è attivo, oppure la configurazione non esiste più o è stata avviata da qualcun altro.
  • 429 Too Many Requests - Nuovo tentativo troppo presto; retryAfterSeconds indica quando riprovare.
  • 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}/cloud-connections/azure/discover
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/azure/discover" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 201 Created
{
   "scopes": [
      { "billingAccountId": "string", "billingProfileId": "string", "displayName": "string", "billingAccountDisplayName": "string", "agreementType": "string" }
   ]
}

Creare una connessione cloud

Completa il collegamento di un account cloud.

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

Corpo

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

    Il provider cloud da collegare.

  • accountLabelstringObbligatorio

    La tua etichetta per questo account, ad es. "Production payer".

  • dataSourcesArray<"invoices" | "current_cost">

    Cosa può leggere Pleaxy: fatture emesse e/o costo del mese in corso. Se omesso: entrambi. Pleaxy non chiama mai il provider per una fonte che escludi, nemmeno in una sincronizzazione manuale. Alcuni provider addebitano ogni richiesta per il costo corrente (AWS Cost Explorer).

  • supplierContactEmailstring

    Referente facoltativo presso il provider per la scheda fornitore che questa chiamata crea.

  • awsConnectionIdstring

    AWS, obbligatorio: connectionId di InitAwsCloudConnection.

  • roleArnstring

    AWS, obbligatorio: il ruolo IAM creato dallo script di configurazione, arn:aws:iam::<12-digit account>:role/<name>.

  • gcpConnectionIdstring

    Google Cloud: connectionId di InitCloudConnection.

  • gcpProjectNumberstring

    Google Cloud: il numero del progetto dell’esportazione della fatturazione (cifre).

  • gcpServiceAccountEmailstring

    Google Cloud: il service account creato dallo script di configurazione in quel progetto.

  • gcpExportTablestring

    Google Cloud: la tabella standard di esportazione dei costi di utilizzo, project.dataset.gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX.

  • azureConnectionIdstring

    Azure: connectionId di InitCloudConnection.

  • azureBillingAccountIdstring

    Azure: l’account di fatturazione del profilo scelto con DiscoverAzureBillingScopes.

  • azureBillingProfileIdstring

    Azure: il profilo di fatturazione scelto con DiscoverAzureBillingScopes.

  • ociConnectionIdstring

    Oracle Cloud: connectionId di InitCloudConnection.

  • ociTenancyOcidstring

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

  • ociUserOcidstring

    Oracle Cloud: l’OCID dell’utente pleaxy-billing creato dallo script di configurazione.

  • ociHomeRegionstring

    Oracle Cloud: la home region della tenancy, una di quelle elencate da InitCloudConnection.

  • detailstring

    Solo per una connessione demo, quando il connettore reale di un provider è disattivato: un identificativo dell’account che digiti tu. Una connessione reale lo legge invece dal provider.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Completa una configurazione avviata con init: Pleaxy verifica di poter leggere la tua fatturazione con l’accesso creato dallo script di configurazione, poi contrassegna la connessione come connessa e aggiunge il provider ai tuoi fornitori. Invia i campi del tuo provider. Solo la persona che ha avviato la configurazione può completarla. Dipende dal piano della regione: il piano Free consente un solo provider connesso.

Errori

  • 400 Bad Request - Convalida non riuscita; Pleaxy non è riuscito a leggere la fatturazione con l’accesso fornito (il codice indica quale provider, ad es. CLOUD_VERIFY_FAILED); troppi tentativi falliti per questa configurazione, quindi ricomincia con init (codice che termina con ATTEMPTS_EXHAUSTED); oppure il piano della regione ha raggiunto il limite di provider connessi (Free: 1).
  • 404 Not Found - La configurazione non esiste più, è scaduta o è stata avviata da qualcun altro.
  • 409 Conflict - Questa configurazione, o lo stesso account o ambito di fatturazione, è già connessa.
  • 429 Too Many Requests - Nuovo tentativo troppo presto dopo un tentativo fallito; retryAfterSeconds indica quando riprovare.
  • 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}/cloud-connections
Richiesta
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" ]
}
Risposta · 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"
}

Sincronizzare una connessione cloud

Sincronizza ora i dati di fatturazione di un account cloud.

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

Parametri

  • idstringObbligatorio

    L’id della connessione cloud.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Sincronizza ora i dati di fatturazione di un account connesso, leggendo solo i dataSources della connessione. Una volta ogni 15 minuti per connessione. Non accetta un corpo.

Errori

  • 400 Bad Request - Sincronizzata meno di 15 minuti fa ("…try again in {n}m."), oppure la connessione non è un account connesso con un connettore di fatturazione reale.
  • 404 Not Found - Questa connessione non esiste nel workspace, oppure è stata disconnessa.
  • 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}/cloud-connections/{id}/sync
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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"
}

Disconnettere una connessione cloud

Disconnette un account cloud.

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

Parametri

  • idstringObbligatorio

    L’id della connessione cloud.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Disconnette un account cloud o annulla una configurazione in corso. Elimina la connessione con tutto ciò che Pleaxy aveva memorizzato per essa (per Oracle Cloud, la sua chiave API cifrata) e registra chi l’ha disconnessa. Per Oracle Cloud la risposta indica l’impronta della chiave da eliminare dall’utente pleaxy-billing. Rimuovi l’accesso anche nel tuo account.

Sessione con accesso effettuato con accesso 'edit' ai fornitori; una chiave API riceve 403. Una configurazione in corso può essere annullata solo dalla persona che l’ha avviata.

Errori

  • 403 Forbidden - Il chiamante è una chiave API, non ha 'edit' sui fornitori, oppure sta annullando la configurazione di qualcun altro ("Only the person who started this setup can cancel it.").
  • 404 Not Found - Questa connessione non esiste nel 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}/cloud-connections/{id}
Richiesta
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "ociKeyFingerprint": "string"
}

Aggiungere un provider cloud come fornitore

Aggiunge un provider cloud come fornitore senza collegare un account.

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

Parametri

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

    Il provider da aggiungere.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Aggiunge un provider cloud al tuo elenco fornitori senza collegare un account, così puoi emettere OdA verso di esso. Dal provider non viene letto nulla. Restituisce la scheda fornitore esistente del provider, se c’è, e un collegamento successivo si aggancia alla stessa scheda. Richiede l’accesso 'create' ai fornitori. Non accetta un corpo.

Errori

  • 404 Not Found - Provider sconosciuto.
  • 409 Conflict - Codice SUPPLIER_ALREADY_LISTED: un fornitore con quel nome ha già un onboarding in corso o approvato.
  • 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}/cloud-connections/{provider}/supplier
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 201 Created
{
   "id": "string",
   "buyerOrgId": "string",
   "supplierName": "string",
   "cloudProvider": "aws" | "gcp" | "azure" | "oci",
   "status": "pending_invite" | "invited" | "in_progress" | "submitted" | "approved" | "rejected",
   "createdAt": "string"
}
Contattaci