Documentazione

Aziende, regioni e persone

Ogni workspace di Pleaxy appartiene a una sola azienda. Il dominio della tua email non fa parte dell'albero: Pleaxy lo usa solo come indizio quando qualcuno si registra.

• Azienda - l'organizzazione su Pleaxy. Sopra non c'è nulla: né gruppo né capogruppo. I suoi amministratori sono gli amministratori di uno qualsiasi dei suoi profili acquirente o fornitore.
• Regione - un workspace all'interno di un'azienda, per esempio EMEA. Una regione non passa mai a un'altra azienda.
• Profili acquirente e fornitore - i due lati di una regione, che ne ha uno o entrambi. Ognuno ha i propri utenti e ruoli, ordini di acquisto, fatture e connessioni con acquirenti o fornitori.

Chi finisce in quale azienda

• La prima persona di un dominio aziendale crea una nuova azienda e ne diventa amministratore.
• Un collega che si registra dopo vede, dopo aver confermato l'email, le aziende su Pleaxy che hanno già persone con il suo dominio, ciascuna con le sue regioni. Può chiedere a un amministratore di una di queste aziende un invito in una regione, oppure confermare che la sua è un'altra azienda e crearne una separata. Le aziende separate non vedono ordini, fatture né fornitori delle altre.
• Un amministratore che aggiunge una regione la aggiunge alla propria azienda.
• Le aziende non si possono unire. Se per errore è stata creata un'azienda separata, invita le sue persone nelle regioni della tua azienda.

Guida rapida

Accedi, collega un provider cloud e crea il tuo primo ordine d’acquisto. La console e gli SDK chiamano la stessa API /v1, che puoi chiamare anche con una chiave API con ambiti limitati (vedi Agenti IA per generarne una). Alcune azioni richiedono sempre una persona che ha effettuato l’accesso a Pleaxy, mai una chiave API: approvare, modificare i flussi di approvazione o l’autonomia e registrare un pagamento.

import { Pleaxy } from "@pleaxy/sdk";

// The base URL is the origin only: the SDK adds /v1/workspaces/<Workspace ID>.
const pleaxy = new Pleaxy({
  baseUrl: "https://api.pleaxy.ai",
  apiKey: process.env.PLEAXY_API_KEY, // "<keyId>.<secret>"
  workspaceId: process.env.PLEAXY_WORKSPACE_ID, // Company profile → Workspace ID
});

// AWS: start the connection, run the returned setup script in your own
// account, then pass back the read-only IAM role it created.
const setup = await pleaxy.cloudConnections.initAwsCloudConnection();
await pleaxy.cloudConnections.createCloudConnection({
  provider: "aws",
  accountLabel: "Production payer",
  awsConnectionId: setup.connectionId,
  roleArn: "arn:aws:iam::912345678901:role/PleaxyBillingRead",
});

const po = await pleaxy.purchaseOrders.createPurchaseOrder({
  supplier: "Amazon Web Services",
  provider: "aws",
  lineItems: [
    {
      scopeType: "sku",
      scopeId: "AWS-EC2-M5LG",
      name: "EC2 m5.large",
      ruleType: "quantity",
      unit: "hr",
      unitPrice: 0.096,
      qty: 5_000,
      nteAmount: 0,
      paymentTerms: "Net 30",
      validFrom: "2026-01-01",
      validUntil: "2026-12-31",
    },
  ],
});

// po.status is "pending_approval" while your approval flow runs, then
// "awaiting_fulfillment". Autonomy, if on, can approve it straight away.

Ordini d’acquisto e righe d’ordine

Un OdA è composto da una o più righe d’ordine, ciascuna con prezzo e monitoraggio indipendenti:

• Righe SKU: un articolo specifico del catalogo di un fornitore, fatturato come quantità × prezzo unitario. Quando il fornitore pubblica un catalogo in Pleaxy, l’ID dell’articolo sulla riga viene convalidato lato server.
• Righe quadro per servizio o per account: un tetto massimo da non superare che copre un intero servizio o un intero account cloud.
• Righe personalizzate: per tutto ciò che non è nel catalogo di un fornitore, a quantità oppure come importo fisso da non superare.

Ogni riga è nella valuta della regione, ha propri termini di pagamento e un proprio periodo di validità, e monitora un saldo in tempo reale (consumato rispetto a residuo) su quel periodo, segnalando le righe che, al ritmo attuale, si esauriranno in anticipo.

Connessioni cloud

Pleaxy si collega in sola lettura alla fatturazione di Amazon Web Services (AWS), Google Cloud, Microsoft Azure e Oracle Cloud Infrastructure (OCI), tramite un accesso che crei nel tuo account con uno script di configurazione e che puoi revocare in qualsiasi momento. Pleaxy conserva ogni ordine d’acquisto come record a sé e non scrive ordini d’acquisto presso alcun provider cloud:

• Amazon Web Services (AWS): un ruolo IAM cross-account che Pleaxy assume. Legge le fatture emesse e Cost Explorer. Perché AWS stampi un numero di OdA Pleaxy sulle sue fatture, aggiungilo in Purchase orders nella console AWS Billing and Cost Management.
• Google Cloud: Workload Identity Federation verso un service account che può solo leggere l’esportazione della fatturazione in BigQuery. Google non ha un’API per le fatture, quindi Pleaxy usa il totale mensile dell’esportazione.
• Microsoft Azure: una credenziale federata su un’app nel tuo tenant. Legge le fatture del tuo profilo di fatturazione e il costo del mese in corso. Pleaxy non associa numeri di OdA alle fatture EA.
• Oracle Cloud Infrastructure (OCI): una chiave di firma API generata da Pleaxy; tu carichi solo la chiave pubblica. Legge le fatture di consumo se il tuo account le prevede, altrimenti il costo di ogni mese chiuso.

Spesa in IA

La spesa in IA è quanto costano i servizi di IA sulla fatturazione cloud che hai collegato: Amazon Bedrock, SageMaker, Vertex AI, Azure OpenAI, OCI Generative AI e i modelli del marketplace sulla stessa fattura. Pleaxy la mostra per emittente della fattura, produttore del modello, modello e contatore (token di input, di output e in cache, ore provisionate), mese in corso e previsione per il periodo, rispetto all’ultimo mese chiuso, e accanto a ogni emittente le righe di ordine d’acquisto aperte emesse a suo nome e quanto vi resta: così sai che Bedrock costerà più di quanto resta su PO-8842 prima che lo dica la fattura. Ogni importo è nella valuta di fatturazione dell’emittente, mai convertito né sommato tra valute.

• Il fornitore è chi emette la fattura. L’azienda il cui modello è stato usato è il vendor della voce. Claude su Bedrock è spesa AWS con vendor anthropic, mai spesa Anthropic: raggruppare per emittente corrisponde alle tue fatture, e raggruppare per produttore risponde a quanto spendi per Claude, chiunque lo fatturi. Nulla viene contato due volte.
• Da dove viene: dalle voci dei servizi di IA sulla fatturazione AWS, Google Cloud, Azure e OCI che hai collegato, lette con lo stesso accesso in sola lettura del resto della fattura e con la stessa scelta delle fonti di dati: una connessione che consente current_cost dà il mese in corso e una previsione; una che consente invoices, il mese chiuso. AWS fornisce le sue voci di IA solo tramite Cost Explorer, quindi un account AWS ha bisogno di current_cost per vederle, e allora mostra anche il mese chiuso. Al tuo account non viene chiesto nulla di nuovo, e un tipo di utilizzo che Pleaxy non conosce ancora viene conservato con il suo nome grezzo, mai scartato.
• Listini: Pleaxy mantiene i prezzi di listino pubblici di ogni produttore ed emittente che mappa, con date di validità: una variazione di prezzo è una nuova voce, così una voce di spesa è giudicata rispetto al prezzo in vigore nel suo giorno. La tariffa negoziata di un contratto o il suo sconto sul listino prevale; i listini in sé non si possono modificare.

Nell’API, la spesa in IA è una risorsa solo per acquirenti: GetAiSpend per le cifre per emittente, produttore, modello o centro di costo, ListAiUsageLines per le voci che le compongono, ListAiRateCards per il prezzo in vigore in un dato giorno e CheckAiSpend per sapere se la previsione rientra nelle righe di ordine d’acquisto aperte e nel budget. Il server MCP espone lo stesso come get_ai_spend e check_ai_spend (vedi Agenti IA).

Oltre alla fatturazione cloud, la spesa in IA copre i provider di IA che paghi direttamente, le voci IA dei tuoi ordini e delle tue fatture, i centri di costo e i limiti presso il provider:

• Provider di IA diretti: OpenAI e Anthropic si collegano con una chiave di amministrazione in sola lettura che crei nella loro console e puoi revocare; anche Mistral, se la tua organizzazione ha la sua Admin API (una funzione Enterprise). OpenRouter si collega con una chiave di gestione, CoreWeave con un token API con il ruolo Billing Viewer e Databricks con un service principal; per Snowflake, Pleaxy genera una coppia di chiavi e tu assegni la chiave pubblica a un utente di servizio. La chiave viene verificata con una lettura prima di essere salvata, conservata cifrata e mai usata per modificare nulla presso il provider. Le voci di ogni provider vengono lette ogni giorno e compaiono come emittente a sé (ListAiProviders, CreateAiProvider).
• Fatture di IA riconciliate riga per riga: una voce IA su un ordine, una condizione di contratto o una fattura indica il modello e il contatore, e ogni riga di fattura viene confrontata con la riga d’ordine e la condizione del contratto per quel modello: la tariffa rispetto al contratto e al prezzo di listino del mese, la quantità rispetto al consumo dichiarato dal provider, e quanto attinge da un impegno. Le righe non vengono mai riconciliate in base alla descrizione. SuggestAiPoLines precompila le voci IA di un ordine con il consumo del mese precedente, e ListAiCommitments mostra quanto di ogni impegno è stato usato.
• Centri di costo e budget: le regole di attribuzione associano tag, etichette, progetti e workspace dei provider ai centri di costo (GetAiAttribution). Ogni budget conta così il consumo IA attribuito del mese come spesa in maturazione, e Pleaxy avvisa quando la previsione arriva all’80% o al 100% del budget (ListAiCostCenters).
• Limiti presso il provider: facoltativi. Una riga d’ordine approvata può impostare il tetto mensile del provider stesso: un budget AWS, un limite di progetto OpenAI, un limite di workspace Anthropic dove Anthropic lo offre sul tuo account, un budget o un tetto di spesa Google Cloud, o un budget Azure, che si limita ad avvisare. Serve una credenziale separata che crei tu, mai quella del collegamento in sola lettura (SetAiSpendLimit).
• IA a postazione: le fatture a postazione di ChatGPT Enterprise, Claude Enterprise, Microsoft 365 Copilot, GitHub Copilot e Cursor vengono confrontate con gli utenti attivi registrati per il mese (SetAiSeatCount). Pleaxy non legge il tuo provider di identità: una persona, uno script o un agente registra il numero.

Approvazioni e autonomia

Ogni regione ha un flusso di approvazione per gli ordini d’acquisto e uno per il pagamento delle fatture, che modifichi in Flussi di lavoro in Pleaxy. Una nuova regione parte con un unico passaggio assegnato a un amministratore della regione. Costruisci un flusso con tre tipi di passaggio:

• Approvatore: una persona dà il suo benestare.
• Approvatori in parallelo: più persone diverse danno ciascuna il proprio benestare, in qualsiasi ordine.
• Approvatore condizionale: interviene solo quando tutte le sue condizioni sono soddisfatte. Le condizioni possono verificare l’importo (nella valuta della regione), il fornitore o il richiedente.

Ogni passaggio indica una persona specifica, e solo quella persona può agire su di esso. Contrassegna un passaggio con Solo oltre la soglia per importi elevati e gli importi pari o inferiori alla soglia lo saltano. Un flusso deve avere almeno un passaggio senza condizioni, in modo che ogni ordine e ogni fattura arrivi a una persona. Se hai emesso tu il documento, il tuo passaggio va a un altro amministratore. Puoi approvarlo tu stesso solo se nessun altro nella regione potrebbe farlo, e in tal caso viene contrassegnato come Autoapprovato.

Con il piano Autonomous puoi attivare l’autonomia, sempre in Flussi di lavoro. Pleaxy approva quindi in autonomia un ordine d’acquisto o una fattura fino al tuo importo di approvazione automatica, come Pleaxy Autonomy, con lo stesso audit trail. Non lo fa mai quando si applica un passaggio condizionale o sopra la soglia di valore elevato, o quando un ordine d’acquisto supera il limite di spesa del richiedente. Per le fatture è più restrittivo: può essere approvata automaticamente solo una fattura riconciliata con una fattura AWS emessa, e mai una inserita da un acquirente o una in un’altra valuta. Le regole di automazione ti permettono di trattare un fornitore in modo diverso: inviare sempre i suoi documenti a una persona oppure, con il piano Autonomous, approvarli automaticamente fino a un certo importo.

Una chiave API può leggere i flussi di approvazione e le impostazioni di autonomia, ma solo una persona che ha effettuato l’accesso a Pleaxy può modificarli, e una chiave API non approva mai un passaggio.

const flow = await pleaxy.approvalChains.get("purchase_order"); // or "invoice_payment"

const autonomy = await pleaxy.settlement.getAutonomy();
// { enabled, maxAutoApproveAmount, approvalThreshold }
// approvalThreshold is the high-value threshold. Change these in Pleaxy, under Workflows.

Riconciliazione delle fatture

Una fattura emessa a fronte di un ordine d’acquisto, per un provider cloud con cui hai una connessione di fatturazione attiva, parte con lo stato di riconciliazione pending. Eseguire la riconciliazione confronta l’importo fatturato con il consumo riportato dal provider:

• Entro il 3% → matched, e la fattura passa al tuo flusso di approvazione delle fatture.
• Scostamento superiore al 3%, o valuta diversa → discrepancy. Pleaxy non converte le valute. Qualcuno la confronta con la bolletta del provider, poi la invia al flusso di approvazione o la rifiuta. Se l’autonomia è attiva e la differenza rientra nel tuo importo di approvazione automatica, è invece Pleaxy ad approvarla, entro i limiti per le fatture descritti in Approvazioni e autonomia.

Una fattura senza ordine d’acquisto, o senza una connessione di fatturazione con cui verificarla, è unverified. Una persona che ha effettuato l’accesso a Pleaxy la esamina, poi la invia al flusso di approvazione o la rifiuta.

Note di credito e di debito

Una nota di credito riduce quanto deve l’acquirente: merce resa, una correzione di prezzo, un rimborso. Il fornitore la emette sulla fattura che corregge, o solo a nome dell’acquirente, e un acquirente può registrarne una che il fornitore ha inviato fuori da Pleaxy. Una nota di credito che corregge una fattura senza superarla viene accettata subito; ogni altra attende che l’acquirente la accetti o la rifiuti. Accettando un credito per merce resa o una correzione di prezzo, il suo importo al netto delle imposte torna alla riga dell’ordine d’acquisto, e quel saldo si può riutilizzare.

Chi regola i crediti è un’impostazione del workspace:

• Li regola Pleaxy. I crediti accettati vengono applicati alle fatture non pagate e ne riducono l’importo da pagare, e una nota di credito su una fattura non pagata le viene applicata quando è accettata. I crediti possono coprire una fattura per intero: una volta approvata, è saldata con il credito, senza nulla da pagare. Rifiutare una fattura restituisce i crediti applicati.
• Li regola il tuo sistema contabile. In Pleaxy non si compensa nulla, e ogni nota di credito accettata esce una volta nell’esportazione dei pagamenti, come riga negativa.

Una nota di debito fattura di più su una fattura già inviata, per esempio un addebito dimenticato. Indica la fattura che modifica e ne prende ordine d’acquisto, riga e valuta, poi passa per riconciliazione, approvazione, pagamento ed esportazione come qualsiasi fattura. Non può modificare una fattura rifiutata né un’altra nota di debito.

Entrambe si trovano in Fatture nell’app, collegate alla fattura che modificano, e le note di credito di AWS e Azure arrivano da sole come note di credito. Nell’API sono la risorsa delle fatture con documentType credit_note o debit_note (vedi CreateInvoice), e un feed di fatture le invia come note di credito e di debito UBL, credit e debit memo cXML, oppure JSON con documentType.

Pagamenti

Pleaxy non paga le fatture. Una volta completato il flusso di approvazione di una fattura, l’acquirente la paga nel proprio ciclo di pagamento (le fatture approvate possono essere esportate a questo scopo) e registra il pagamento in Pleaxy. La registrazione non sposta denaro. Il fornitore vede il pagamento come registrato dall’acquirente e riceve un avviso di pagamento. Registrare un pagamento richiede una persona che ha effettuato l’accesso a Pleaxy, mai una chiave API.

Con il pagamento, o in qualsiasi momento dopo, l’acquirente può inviare al fornitore un avviso di pagamento: la prova di pagamento, come la ricevuta del bonifico della banca (PDF, PNG o JPEG, fino a 10 MB), e una nota fino a 1.000 caratteri. Il fornitore riceve una notifica, anche nel suo canale Slack o Teams se vi indirizza le notifiche di pagamento, e trova l’avviso sulla fattura. Come la registrazione di un pagamento, l’invio richiede una persona che ha effettuato l’accesso a Pleaxy (vedi SendRemittance). Esporta per il pagamento funziona anche su una singola fattura.

Agenti IA (MCP)

Per collegare un agente a nome tuo, senza una chiave API: Collegare un agente IA.

Il server MCP di Pleaxy espone ordini d’acquisto e fatture come strumenti per Claude o qualsiasi altro agente compatibile con MCP. È un livello sottile: ogni chiamata a uno strumento è una richiesta autenticata alla stessa API /v1 usata dalla console e dagli SDK, quindi un agente può fare esattamente ciò che la sua chiave API consente, niente di più.

1. Genera una chiave API con ambiti limitati con POST /v1/workspaces/:regionId/api-keys dopo aver effettuato l’accesso con il tuo utente: una chiave API esistente non può generarne un’altra (vedi Chiavi API). La chiave assume il tuo ruolo nel workspace, acquirente o fornitore, e solo un amministratore può generarne una. Una chiave acquirente è in sola lettura, a meno che tu non le assegni un procurementRole, ad esempio requisitions per creare ordini d’acquisto. La risposta contiene la chiave (mostrata una sola volta). Poi copia l’ID del workspace da Profilo aziendale nella console Pleaxy: ti servono entrambi qui sotto.
2. Verifica che funzioni (Node.js 22.18 o successivo). Il server è su npm come pleaxy-mcp, quindi non c’è niente da compilare né da clonare: lo scarica npx.
   shell

   npx -y pleaxy-mcp --version

3. Aggiungilo al tuo client MCP. Per Claude Desktop o Claude Code, aggiungi questo alla tua configurazione MCP. L’URL di base è solo l’origine: il server aggiunge da sé /v1.
   mcp config · json

   {
     "mcpServers": {
       "pleaxy": {
         "command": "npx",
         "args": ["-y", "pleaxy-mcp"],
         "env": {
           "PLEAXY_API_BASE_URL": "https://api.pleaxy.ai",
           "PLEAXY_API_KEY": "<keyId>.<secret>",
           "PLEAXY_WORKSPACE_ID": "<Company profile → Workspace ID>"
         }
       }
     }
   }

Un processo server serve un solo workspace: una chiave API, un ID del workspace. Le chiavi acquirente e fornitore vedono lo stesso elenco di strumenti, ma una chiamata al di fuori del ruolo della chiave (ad esempio una chiave fornitore che chiama create_purchase_order) viene rifiutata dall’API esattamente come avverrebbe via REST.