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:
freenon può essere combinato con un’altra modalità.creditsrichiede un modo per ottenere crediti: pacchetti, piani con crediti, osignupCredits.subscriptionrichiede 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:
| Cosa | Prezzo | Quando |
|---|---|---|
| Un’esecuzione dal modulo | costs["agent:<key>"], altrimenti costs.run | Trattenuto all’avvio, liquidato alla fine. Vedi Esecuzioni. |
| Un messaggio in chat | costs["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 modello | il cost.perRun del modello | Prelevato all’avvio, restituito se l’esecuzione non produce un risultato. |
| Un evento | il charge di un trigger | Una 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:
| Forma | Significato |
|---|---|
5 | Un 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
- Trattenuta. All’avvio, la stima (o il prezzo fisso) viene prelevata dal saldo. Senza crediti sufficienti l’esecuzione non parte.
- L’avvio fallisce. La trattenuta viene restituita subito.
- L’esecuzione termina senza report. L’intera trattenuta viene restituita.
- 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
| Campo | Significato | Predefinito |
|---|---|---|
creditEur | Il valore di un credito in euro | 0.01 |
markupPct | Il tuo margine sul costo | 50 |
drivers | Cosa viene prezzato: llm_tokens e compute (vm conta come compute) | entrambi |
allowNegative | Lascia scendere il saldo sotto zero quando l’utilizzo supera la stima | false |
- 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,proxyestoragesono 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" }
credits1–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
cronowebhooknon può addebitare. - L’addebito viene prelevato anche quando porta il saldo sotto zero.
Pacchetti e piani
I pacchetti sono acquisti singoli che aggiungono crediti.
| Campo | Significato |
|---|---|
key | Il suo nome. |
price | In billing.currency (predefinito eur). |
credits | Crediti aggiunti al pagamento. |
label | Quello che vede l’utente. |
I piani sono abbonamenti.
| Campo | Significato |
|---|---|
key, price, label | Come per i pacchetti. |
interval | month o year. |
credits | Crediti 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
- L’utente preme Buy (compra, per un pacchetto) o Subscribe (abbonati, per un piano) nella pagina account.
- Il runtime crea una sessione di Stripe Checkout. Il prezzo viene dal manifest pubblicato, mai dal browser. L’email dell’utente è già compilata.
- 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.platformFeePctnel manifest non viene usato. - 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 Stripe | Effetto |
|---|---|
| Checkout completato | La sessione viene riletta da Stripe. Un pacchetto pagato aggiunge i suoi crediti; un piano viene attivato per l’utente. |
| Fattura pagata | Il piano resta attivo, e i credits del piano vengono aggiunti per il periodo. |
| Abbonamento cancellato | Il 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.
action | Cosa viene contato | per rispettato |
|---|---|---|
run | Le esecuzioni da modulo di un utente, tutti gli agenti | user |
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 |
agents | Ogni agente avviato da eventi | app, user |
create:<collection> | I record che un utente crea, tramite moduli e strumenti degli agenti | user |
window | Significato |
|---|---|
minute, hour, day | L’ultimo minuto, l’ultima ora, l’ultimo giorno |
month | Gli ultimi 30 giorni |
total | Da 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] }
plansdà 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.rolesrestringe 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: ipeper: org, e le azionichatelogin, sono accettati dallo schema ma non applicati tramitespec.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.