WebRobot
App Builder · pagine

Documentazione · App Builder

Pagamenti e crediti

Gli utenti di un’app pagano te, l’organizzazione proprietaria dell’app. Comprano crediti o si abbonano a piani tramite Stripe; il denaro va all’account Stripe della tua organizzazione e WebRobot trattiene una commissione di piattaforma. Il lavoro che l’app svolge con i crediti (esecuzioni degli agenti, messaggi in chat, istanze, eventi) è prezzato in spec.billing. L’elenco dei campi è nel riferimento.

Questo è separato da quanto la tua organizzazione paga a WebRobot per l’uso della piattaforma.

Modalità di fatturazione

billing:
  modes: [credits, subscription]
  currency: eur
  signupCredits: 20
  costs:
    "agent:analyst": 5
  packs:
    - { key: small, credits: 100, price: 9, label: "100 credits" }
  plans:
    - { key: pro, price: 29, interval: month, credits: 400, label: Pro }

modes elenca uno o più valori tra free, credits, subscription, per_transaction. La validazione controlla che abbiano senso:

  • free non può essere combinato con un’altra modalità.
  • credits richiede un modo per ottenere crediti: pacchetti, piani con crediti, o signupCredits.
  • subscription richiede dei piani.

Quanto viene addebitato agli utenti dipende da costs, non da modes: un’app senza costi non addebita nulla.

per_transaction, transactionFeePct, sellers, revenueShare, i campi dei piani includes, creditsReset, transactionFeePct e roles, e il campo dei pacchetti unlocks sono accettati dallo schema ma non ancora applicati dal runtime.

Crediti

Ogni utente dell’app ha un saldo di crediti. Ogni movimento viene scritto nel registro dell’utente con un motivo, e ogni movimento viene applicato una sola volta (un pagamento o una liquidazione ripetuti non contano mai due volte).

Gli utenti ottengono crediti da:

  • signupCredits, una volta, al primo accesso;
  • i pacchetti che comprano, e i crediti di un piano a ogni periodo pagato;
  • una ricarica manuale da parte di un amministratore (1–100.000 crediti alla volta, dalla vista admin).

I crediti vengono spesi da:

CosaPrezzoQuando
Un’esecuzione dal modulocosts["agent:<key>"], altrimenti costs.runTrattenuto all’avvio, liquidato alla fine. Vedi Esecuzioni.
Un messaggio in chatcosts["agent:<key>"] (il numero, o il suo estimate)Prelevato quando il messaggio viene inviato, restituito se non arriva una risposta. Non addebitato quando risponde il server di chat dell’organizzazione durante l’orario di servizio.
Un’esecuzione di un’istanza di modelloil cost.perRun del modelloPrelevato all’avvio, restituito se l’esecuzione non produce un risultato.
Un eventoil charge di un triggerUna volta per evento.

Senza crediti sufficienti, l’azione viene rifiutata con 402 "not enough credits"; la risposta contiene needed e balance.

Costi

Un costo è un numero di crediti, oppure un oggetto:

FormaSignificato
5Un prezzo fisso.
{estimate: 20, metered: true}Pagamento per uso: 20 crediti trattenuti, l’utilizzo reale addebitato alla fine.
{requiresPlan: pro, …}Solo gli utenti con il piano pro possono eseguirlo (402 "needs the plan pro").
{perUnit: {field, credits, min, max}}Il prezzo segue un campo numerico del modulo: credits × value, arrotondato per eccesso, poi mantenuto tra min e max.
costs:
  "agent:survey":
    perUnit: { field: hectares, credits: 2, min: 10, max: 500 }

perUnit deve nominare un campo numerico del modulo, e non può essere anche metered.

Gli amministratori non pagano

Gli utenti con un ruolo di amministratore (assegnato dalle email degli amministratori dell’app) eseguono, usano la chat e usano l’app gratuitamente: non viene trattenuto nulla, l’esecuzione è segnata come gratuita. Un amministratore che esegue a mano la propria istanza di un modello non paga nulla.

Come viene addebitata un’esecuzione

  1. Trattenuta. All’avvio, la stima (o il prezzo fisso) viene prelevata dal saldo. Senza crediti sufficienti l’esecuzione non parte.
  2. L’avvio fallisce. La trattenuta viene restituita subito.
  3. L’esecuzione termina senza report. L’intera trattenuta viene restituita.
  4. L’esecuzione termina con un report. L’esecuzione viene liquidata una volta:
    • prezzo fisso: la trattenuta è il prezzo;
    • prezzo a consumo: l’utilizzo reale viene prezzato (vedi sotto). Se è inferiore alla trattenuta, la differenza viene restituita; se è superiore, la differenza viene prelevata.

Quando l’utilizzo supera la stima e il saldo non basta a coprirlo:

  • con metering.allowNegative: true, il saldo scende sotto zero;
  • altrimenti, il runtime preleva quello che c’è nel saldo; il resto viene registrato sull’esecuzione come non pagato.

La pagina dell’esecuzione mostra i crediti addebitati, "pay per use: what the run really consumed" per un’esecuzione a consumo, e i crediti oltre il saldo quando ce ne sono.

Misurazione del pagamento per uso

Un costo con metered: true viene liquidato su quanto l’esecuzione ha davvero usato, con billing.metering:

billing:
  modes: [credits]
  metering: { creditEur: 0.01, markupPct: 50 }
  costs:
    "agent:research": { estimate: 40, metered: true }
  packs:
    - { key: p500, credits: 500, price: 5 }

Il prezzo di un’esecuzione:

cost    = LLM tokens × the model's rate  +  compute (whole hours started) × the hourly VM rate
price   = cost × (1 + markupPct / 100)
credits = price / creditEur, rounded up
CampoSignificatoPredefinito
creditEurIl valore di un credito in euro0.01
markupPctIl tuo margine sul costo50
driversCosa viene prezzato: llm_tokens e compute (vm conta come compute)entrambi
allowNegativeLascia scendere il saldo sotto zero quando l’utilizzo supera la stimafalse
  • I token sono prezzati secondo il listino della piattaforma per la famiglia del modello (Opus, Sonnet, Haiku), letture e scritture della cache incluse. Un modello sconosciuto viene prezzato come la famiglia più costosa.
  • Il calcolo conta i minuti dell’esecuzione arrotondati per eccesso a ore intere, almeno un’ora.
  • I driver browser, proxy e storage sono accettati ma non prezzati.
  • Se la piattaforma non ha registrato alcun utilizzo di token per l’esecuzione, viene addebitata la stima.

Ogni esecuzione a consumo conserva la sua misurazione: token, modello, minuti, costo e crediti.

La misurazione si applica alle esecuzioni da modulo. Un messaggio in chat costa il suo prezzo fisso o la sua stima, senza liquidazione.

Crediti addebitati da un trigger

Un trigger con charge preleva crediti dall’utente dell’evento: una commissione di successo quando una pratica viene approvata, una tariffa per contatto.

triggers:
  - key: success_fee
    on: { approval: offer, decision: approved }
    charge: { credits: 50, reason: "Success fee" }
  • credits 1–100.000; reason (fino a 120 caratteri) è la riga del registro, per impostazione predefinita la chiave del trigger.
  • Addebitato una volta per evento (lo stesso record allo stesso aggiornamento viene addebitato una volta).
  • L’evento richiede un utente: un record, un’approvazione, un pagamento o una data. Un trigger cron o webhook non può addebitare.
  • L’addebito viene prelevato anche quando porta il saldo sotto zero.

Pacchetti e piani

I pacchetti sono acquisti singoli che aggiungono crediti.

CampoSignificato
keyIl suo nome.
priceIn billing.currency (predefinito eur).
creditsCrediti aggiunti al pagamento.
labelQuello che vede l’utente.

I piani sono abbonamenti.

CampoSignificato
key, price, labelCome per i pacchetti.
intervalmonth o year.
creditsCrediti aggiunti a ogni fattura pagata.

Finché un abbonamento è attivo, l’utente ha il piano. I piani sbloccano ciò che il manifest vincola a un piano: il requiresPlan di un costo, il gatedBy di un campo o di un’opzione, i plans di un limite, l’anteprima di una vista dati (preview.unlessPlan).

Stripe

Attivare i pagamenti

I pagamenti vanno all’account Stripe Connect (Express) della tua organizzazione. Un amministratore dell’organizzazione attiva i pagamenti in App Studio: la console crea l’account al primo tentativo e apre l’onboarding di Stripe. L’account può ricevere pagamenti quando Stripe vi ha abilitato i pagamenti con carta e i trasferimenti.

Fino ad allora, l’app mostra i suoi pacchetti e piani senza pulsanti, e dice "Payments are not enabled for this app yet."

Checkout

  1. L’utente preme Buy (compra, per un pacchetto) o Subscribe (abbonati, per un piano) nella pagina account.
  2. Il runtime crea una sessione di Stripe Checkout. Il prezzo viene dal manifest pubblicato, mai dal browser. L’email dell’utente è già compilata.
  3. Il pagamento è un addebito con destinazione verso il tuo account collegato. WebRobot trattiene la sua commissione: una quota del prezzo del pacchetto, o una percentuale di ogni fattura dell’abbonamento. La percentuale della commissione è fissata dalla piattaforma; billing.platformFeePct nel manifest non viene usato.
  4. Stripe rimanda l’utente all’app. I crediti vengono aggiunti subito, e la pagina account dice "Payment received — thank you!". Se il pagamento è ancora in conferma, dice "Payment being confirmed: the credits arrive shortly."

I versamenti dal tuo account collegato alla tua banca seguono le impostazioni del tuo account Stripe.

Cosa comunica Stripe all’app

Evento StripeEffetto
Checkout completatoLa sessione viene riletta da Stripe. Un pacchetto pagato aggiunge i suoi crediti; un piano viene attivato per l’utente.
Fattura pagataIl piano resta attivo, e i credits del piano vengono aggiunti per il periodo.
Abbonamento cancellatoIl piano viene tolto all’utente.

L’accredito è idempotente: la pagina di ritorno e la notifica di Stripe possono arrivare entrambe, e i crediti vengono aggiunti una volta. Un acquisto completato è anche un evento dell’app: scattano i trigger con on.payment (vedi Agenti e automazione).

Non ancora disponibile

  • Gli utenti non possono annullare un abbonamento dall’app.
  • I pagamenti sono disattivati sull’indirizzo di anteprima.

Limiti

spec.limits contiene le quote dell’app. Ogni limite ha un action, un max e una window.

actionCosa viene contatoper rispettato
runLe esecuzioni da modulo di un utente, tutti gli agentiuser
agent:<key>Le esecuzioni da modulo di quell’agente da parte di un utente (per assente o user); gli avvii di quell’agente da eventi (per: user o per: app, scritto esplicitamente)user, app
agentsOgni agente avviato da eventiapp, user
create:<collection>I record che un utente crea, tramite moduli e strumenti degli agentiuser
windowSignificato
minute, hour, dayL’ultimo minuto, l’ultima ora, l’ultimo giorno
monthGli ultimi 30 giorni
totalDa sempre: una quota, come "al massimo 3 progetti nel piano gratuito" (non per gli avvii da eventi)

Tutte le finestre sono scorrevoli: contano a ritroso da adesso. rolling è accettato ma non ha effetto.

limits:
  - { action: "create:projects", max: 3, window: total, plans: { pro: 50, agency: -1 } }
  - { action: run, max: 10, window: day, roles: [member] }
  • plans dà a ogni piano o pacchetto il suo massimo; -1 = illimitato; un utente con più piani ottiene il più alto. Si applica alle esecuzioni da modulo e ai record creati dagli strumenti degli agenti.
  • roles restringe un limite sulle esecuzioni da modulo a quei ruoli.
  • Gli amministratori dell’app non sono limitati sulle esecuzioni da modulo e sui record che creano.
  • per: ip e per: org, e le azioni chat e login, sono accettati dallo schema ma non applicati tramite spec.limits. Chat e accesso hanno limiti fissi: vedi Runtime.

Quando un limite viene raggiunto l’utente vede 429 con il motivo, per esempio "limit reached: 10 per day", "limit reached: 3 in your plan", o per uno strumento di un agente "limit reached: 3 projects in the user's plan — the user can upgrade their plan". Gli avvii da eventi sono spiegati in Agenti e automazione.

Cosa vedono gli utenti

La vista account (type: account) mostra:

  • il saldo;
  • un blocco Top up (ricarica): ogni pacchetto con prezzo e crediti e un pulsante Buy; ogni piano con il prezzo al mese o all’anno, i suoi crediti, un pulsante Subscribe, e un’etichetta active una volta sottoscritto;
  • le chiavi collegate dall’utente, quando l’app ha credenziali;
  • Movements (movimenti): ogni riga del registro, con data, motivo e importo.

Dai una vista account a un’app che vende pacchetti o piani: lì ci sono i pulsanti, ed è lì che Checkout rimanda l’utente.

Il modulo di esecuzione mostra disattivata un’opzione vincolata a un piano che l’utente non ha, con "needs the plan …". La pagina dell’esecuzione mostra quanto è stato addebitato una volta liquidata l’esecuzione.

La vista amministratore (type: admin) elenca ogni utente con la data di registrazione, i piani e il saldo, con un campo per aggiungere crediti a mano, e le ultime esecuzioni.