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

Riferimento API

Provider IA

Provider IA collegati direttamente con una chiave in sola lettura, e gli emittenti IA che puoi aggiungere come fornitori.

Altro su questa risorsa

Novità con i controlli della spesa in IA. Oltre alle voci di IA sulle tue fatture cloud, Pleaxy legge i report di costo e utilizzo dei provider IA che paghi direttamente. OpenAI e Anthropic usano una chiave di amministrazione in sola lettura; anche Mistral, se l’organizzazione dispone della sua Admin API (una funzionalità Enterprise); OpenRouter una chiave di gestione; CoreWeave un token di accesso API con il ruolo Billing Viewer; Databricks il segreto OAuth di un service principal; per Snowflake Pleaxy genera una coppia di chiavi, la cui chiave pubblica assegni a un utente di servizio. Lambda, Nebius, Crusoe e gli emittenti a licenza per utente (Cursor, GitHub, Microsoft) non hanno un’API di fatturazione che Pleaxy possa leggere: aggiungili come fornitori e le loro fatture vengono confrontate con il contratto. La chiave viene verificata con una lettura prima di salvare qualsiasi cosa, memorizzata cifrata, mai restituita (solo i suoi ultimi quattro caratteri, keyHint) e mai usata per modificare nulla presso il provider. Le voci di ogni provider collegato vengono lette ogni giorno e compaiono in Spesa in IA come emittente a sé, confrontate con gli ordini d’acquisto emessi verso la sua scheda fornitore. Ogni emittente IA ha una scheda fornitore che Pleaxy crea in anticipo e che puoi aggiungere senza collegarti: le sue fatture e i suoi ordini funzionano allora come quelli di qualsiasi fornitore. Un provider collegato conta ai fini del limite di provider del piano, come un account cloud. Il connettore di ogni provider viene attivato per regione; finché non lo è, il collegamento risponde 404 e l’aggiunta del fornitore funziona comunque.

Endpoint

GET…/ai-providers
POST…/ai-providers
POST…/ai-providers/{id}/sync
DELETE…/ai-providers/{id}
POST…/ai-providers/{provider}/supplier
GET…/ai-invoicers

Elencare i provider IA

Elenca i provider IA collegati del workspace.

GET/v1/workspaces/{regionId}/ai-providers

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Ogni connessione diretta a un provider IA nel workspace, collegata o in attesa: di quale provider si tratta, l’account che legge, gli ultimi quattro caratteri della chiave, quando è stata sincronizzata l’ultima volta e con quale esito. La chiave in sé non viene mai restituita. Richiede l’accesso 'view' ai fornitori o alle fatture.

Campi della risposta

accountLabelstring
Come il provider chiama l’organizzazione o l’account che la chiave legge.
keyHintstring
Gli ultimi quattro caratteri della chiave, l’unica traccia che Pleaxy ne mostra. Assente per Snowflake, la cui coppia di chiavi è stata generata da Pleaxy.
statusstring
connected, oppure pending per una coppia di chiavi Snowflake la cui chiave pubblica non è ancora stata assegnata all’utente di servizio: SyncAiProvider la verifica e completa il collegamento.
snowflakeobject
Solo Snowflake: l’identificativo dell’account, l’utente di servizio, il warehouse e il ruolo facoltativo con cui la coppia di chiavi accede, e la chiave pubblica (PEM) con la sua impronta da assegnare con ALTER USER ... SET RSA_PUBLIC_KEY.
creditPriceobject
Solo Snowflake: il prezzo per credito del tuo contratto, che trasforma i crediti in denaro. Senza di esso le voci di IA del provider restano in crediti, con currency credits, e non vengono mai sommate al denaro.
supplierConnectionIdstring
La scheda fornitore a cui è agganciato il provider; Spesa in IA confronta le sue voci con gli ordini d’acquisto emessi verso questa scheda.
currencystring
La valuta di fatturazione del provider, come la riporta il suo report dei costi.
lastSyncStatusstring
L’esito dell’ultima lettura: ok, error (lastSyncError dice perché, lastSyncErrorCode è access_revoked quando la chiave non funziona più) o throttled (il provider ha chiesto a Pleaxy di attendere; la prossima esecuzione riprova).

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}/ai-providers

Richiesta

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Risposta · 200 OK

[
   {
      "id": "string",
      "provider": "openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave",
      "accountLabel": "string",
      "keyHint": "string",
      "status": "connected" | "pending",
      "connectedAt": "string",
      "connectedBy": "string",
      "snowflake": { "account": "string", "user": "string", "warehouse": "string", "role": "string", "publicKeyPem": "string", "publicKeyFingerprint": "string" },
      "creditPrice": { "amount": number, "currency": "string", "kind": "on_demand" | "capacity" | "commit" },
      "supplierConnectionId": "string",
      "currency": "string",
      "lastSyncedAt": "string",
      "lastSyncStatus": "ok" | "error" | "throttled",
      "lastSyncError": "string",
      "lastSyncErrorCode": "string"
   }
]

Creare un provider IA

Collega un provider IA con una chiave in sola lettura.

POST/v1/workspaces/{regionId}/ai-providers

Corpo

provider"openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave"Obbligatorio
Il provider da collegare. Il suo connettore deve essere attivo nella regione.
keystring
Ogni provider tranne Snowflake, obbligatorio: una chiave in sola lettura. La chiave di amministrazione di OpenAI inizia con sk-admin- (Organization settings › Admin keys); quella di Anthropic con sk-ant-admin (Claude Console, Settings › Admin keys); quella di Mistral è una chiave Admin API; la chiave di gestione di OpenRouter inizia con sk-or-; quella di CoreWeave è un token di accesso API; quella di Databricks è il segreto OAuth del service principal. Mai registrata nei log né restituita.
snowflakeobject
Snowflake, obbligatorio: { account, user, warehouse, role? }: l’identificativo dell’account (orgname-account_name), l’utente di servizio, il warehouse su cui gira la query di utilizzo e un ruolo facoltativo.
databricksobject
Databricks, obbligatorio: { host, clientId, warehouseId }: l’host del workspace (un dominio Databricks), il client id OAuth del service principal e il SQL warehouse su cui girano le letture della fatturazione; key è il segreto OAuth del principal. Il principal richiede SELECT su system.billing (e system.serving per i conteggi dei token).
creditPriceobject
Snowflake e Databricks, facoltativo: { amount, currency, kind } con kind on_demand, capacity o commit, il prezzo per credito (Snowflake) o per DBCU (Databricks) del tuo contratto. Senza di esso le voci di Snowflake restano in crediti e quelle di Databricks sono al prezzo di listino dell’account.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Collega un provider IA diretto. Per OpenAI, Anthropic e Mistral invia la chiave di amministrazione in sola lettura: Pleaxy esegue una lettura con essa e, solo se riesce, la memorizza cifrata, aggiunge la scheda fornitore del provider ai tuoi fornitori e restituisce la connessione. Per Snowflake invia dove accedere: Pleaxy genera una coppia di chiavi e restituisce la connessione in pending, con la chiave pubblica da assegnare all’utente di servizio; poi SyncAiProvider la verifica. Cinque verifiche fallite per provider in un’ora, poi bisogna attendere. Richiede l’accesso 'create' ai fornitori.

Errori

400 Bad Request - Convalida non riuscita; la chiave manca o non è la chiave di amministrazione di quel provider; il provider non l’ha accettata (non autorizzata, vietata, senza Admin API, occupato o irraggiungibile, e non è stato salvato nulla); cinque verifiche fallite nell’ultima ora; oppure il piano della regione ha raggiunto il limite di provider.
404 Not Found - Provider sconosciuto, oppure il suo connettore non è attivo in questa regione.
409 Conflict - Il provider è già collegato 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.
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}/ai-providers

Richiesta

POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/ai-providers

{ "provider": "anthropic", "key": "sk-ant-admin01-…" }

Risposta · 201 Created

{
   "id": "aip_01k8q2m4xv7c9n3p5t6r8w0yzb",
   "provider": "anthropic",
   "accountLabel": "Northwind Labs",
   "keyHint": "f3Qa",
   "status": "connected",
   "connectedAt": "2026-10-30T09:12:44.000Z",
   "supplierConnectionId": "sc_01k8q2m5a1b2c3d4e5f6g7h8j9"
}

Sincronizzare un provider IA

Legge ora costi e utilizzo di un provider IA.

POST/v1/workspaces/{regionId}/ai-providers/{id}/sync

Parametri

idstringObbligatorio
L’id della connessione al provider IA.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Legge ora i report di costo e utilizzo di un provider invece di attendere l’esecuzione giornaliera, e restituisce la connessione con il nuovo stato di sincronizzazione. Per una connessione Snowflake in pending verifica prima che la coppia di chiavi riesca ad accedere, e la contrassegna come connected. Una volta ogni 15 minuti per provider. Non accetta un corpo. Richiede l’accesso 'create' ai fornitori o l’accesso 'edit' alle fatture.

Errori

400 Bad Request - Sincronizzato meno di 15 minuti fa, oppure una coppia di chiavi Snowflake in pending non riesce ancora ad accedere (non è cambiato nulla).
404 Not Found - Questa connessione non esiste nel workspace, oppure il connettore del provider è stato disattivato.
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}/ai-providers/{id}/sync

Richiesta

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers/{id}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Risposta · 201 Created

{
   "id": "string",
   "provider": "openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave",
   "status": "connected" | "pending",
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled",
   "lastSyncError": "string"
}

Eliminare un provider IA

Disconnette un provider IA.

DELETE/v1/workspaces/{regionId}/ai-providers/{id}

Parametri

idstringObbligatorio
L’id della connessione al provider IA.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Disconnette un provider IA diretto: la connessione e la sua chiave cifrata vengono eliminate, e viene registrato chi l’ha disconnesso. Le voci di IA già lette restano come storico, e la scheda fornitore resta. Revoca la chiave anche presso il provider (per Snowflake, rimuovi la chiave pubblica dell’utente).

Sessione con accesso effettuato con accesso 'edit' ai fornitori; una chiave API riceve 403.

Errori

403 Forbidden - Il chiamante è una chiave API o non ha 'edit' sui fornitori.
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}/ai-providers/{id}

Richiesta

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers/{id}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Risposta · 200 OK

{
   "id": "string",
   "provider": "openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave"
}

Aggiungere un provider IA come fornitore

Aggiunge un emittente IA come fornitore senza collegarlo.

POST/v1/workspaces/{regionId}/ai-providers/{provider}/supplier

Parametri

providerstringObbligatorio
Uno tra openai, anthropic, mistral, cohere, xai, openrouter, snowflake, databricks, coreweave, lambda, nebius, crusoe, cursor, github o microsoft (ListAiInvoicers li elenca).

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Aggiunge un emittente IA al tuo elenco fornitori a partire dalla scheda che Pleaxy crea in anticipo, senza collegare nulla, così puoi emettere ordini d’acquisto verso di esso e registrarne le fatture. Funziona per ogni emittente IA, compresi quelli che Pleaxy non può leggere (la loro spesa deriva dalle loro fatture). Restituisce la scheda esistente, se c’è, e un collegamento successivo si aggancia alla stessa scheda. Non accetta un corpo. Richiede l’accesso 'create' ai fornitori.

Errori

404 Not Found - Emittente IA 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}/ai-providers/{provider}/supplier

Richiesta

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers/{provider}/supplier" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Risposta · 201 Created

{
   "id": "string",
   "buyerOrgId": "string",
   "supplierName": "string",
   "aiProvider": "string",
   "status": "pending_invite" | "invited" | "in_progress" | "submitted" | "approved" | "rejected",
   "createdAt": "string"
}

Elencare gli emittenti IA

Elenca gli emittenti IA che Pleaxy crea in anticipo come fornitori.

GET/v1/workspaces/{regionId}/ai-invoicers

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Gli emittenti IA per cui Pleaxy mantiene una scheda fornitore: i loro nomi, le entità legali da cui fatturano per regione, le valute in cui fatturano, se fatturano tramite fattura, crediti prepagati o entrambi, i domini da cui arrivano le loro email di fattura, come Pleaxy legge la loro spesa e se quel lettore è attivo nella tua regione (connectable). Pleaxy gestisce l’elenco; entità legali e domini sono un’indicazione per l’intestatario della fattura, mai una verifica. Richiede l’accesso 'view' ai fornitori o alle fatture.

Campi della risposta

legalEntitiesArray<object>
L’entità che fattura a un acquirente in ogni regione, default per ogni regione non elencata, con il suo paese.
credentialstring
Come Pleaxy legge la spesa dell’emittente: admin_key (una chiave in sola lettura che incolli), key_pair (una coppia di chiavi generata da Pleaxy) o none (nessuna API di lettura; la sua spesa deriva dalle sue fatture).
shapestring
In cosa sono misurate le sue voci: tokens, credits (Snowflake, Databricks) o capacity (ore GPU).
connectableboolean
Se CreateAiProvider può collegarlo ora in questa regione.

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}/ai-invoicers

Richiesta

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-invoicers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Risposta · 200 OK

[
   {
      "id": "string",
      "name": "string",
      "legalEntities": [ { "region": "us" | "eu" | "default", "name": "string", "country": "string" } ],
      "billingCurrencies": [ "string" ],
      "billing": [ "invoice" | "prepaid_credits" ],
      "senderDomains": [ "string" ],
      "credential": "admin_key" | "key_pair" | "none",
      "tier": "direct" | "data_platform" | "host" | "neocloud" | "seats",
      "shape": "tokens" | "credits" | "capacity" | "seats",
      "contactHint": "string",
      "connectable": boolean
   }
]