> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Crea una Piattaforma API AI con Fatturazione Basata su Crediti > Costruisci un servizio API AI a livelli con crediti token — emetti crediti tramite piani di abbonamento e pacchetti di ricarica una tantum, e detrai automaticamente quando i clienti chiamano la tua API. Lascia che Sentra scriva il tuo codice di integrazione per te.
Usa il nostro assistente AI in VS Code, Cursor o Windsurf per generare codice SDK/API, gestori di webhook, concessioni di crediti e altro — semplicemente descrivendo ciò che desideri. Prova Sentra: Integrazione potenziata da AI → In questo tutorial, creerai **NeuralAPI** — una piattaforma AI a livelli in cui ogni piano di abbonamento include un credito mensile di token, i clienti possono acquistare pacchetti di ricarica quando sono a corto di crediti, e il tuo backend detrae automaticamente i crediti mentre le richieste vengono elaborate da OpenAI. Questo tutorial utilizza Node.js/Express + l'SDK OpenAI. I concetti di Dodo Payments (crediti, misuratori, webhook) si applicano a qualsiasi framework o fornitore AI — adatta liberamente. Alla fine di questo tutorial, saprai come: * Creare un diritto di credito personalizzato (token) e un misuratore che detrae automaticamente da esso * Collegare i crediti ai piani di abbonamento (con e senza sforamento) e a un prodotto di ricarica una tantum * Collegare un endpoint di completamento OpenAI reale che fattura i token tramite Dodo Payments * Interrogare il saldo del credito live di un cliente tramite l'SDK * Verificare le firme del webhook e indirizzare gli eventi di credito di Dodo Payments ## Cosa Stiamo Costruendo Ecco il modello di pricing per NeuralAPI: | Prodotto | Prezzo | Token | Sforamento | | --------------------------- | --------------- | ---------------------- | -------------------- | | Piano Iniziale | \$29/mese | 10,000,000 token/ciclo | Bloccato a zero | | Piano Pro | \$99/mese | 40,000,000 token/ciclo | \$0.005 per 1K token | | Pacchetto di Ricarica Token | \$19 una tantum | +5,000,000 token | — | Prima di iniziare, assicurati di avere: * Un account Dodo Payments (va bene la modalità di test) * Una chiave API OpenAI * Node.js 18+ * Conoscenza di base di TypeScript/Node.js ## Passaggio 1: Crea il Tuo Diritto di Credito Token Per prima cosa, crea il diritto di credito che condivideranno entrambi i piani di abbonamento e il pacchetto di ricarica. Pensa a questo come alla definizione dell'unità "token" che utilizza la tua piattaforma. Pagina di elenco dei crediti che mostra i diritti di credito creati 1. Accedi alla tua dashboard di Dodo Payments 2. Clicca su **Prodotti** nella barra laterale sinistra 3. Seleziona la scheda **Crediti** 4. Clicca su **Crea Credito** Compila i dettagli di base per il tuo credito token: **Nome Credito**: `API Tokens` **Tipo di Credito**: Seleziona **Unità Personalizzata** **Nome Unità**: `token` **Precisione**: `0` (i token sono sempre numeri interi) **Scadenza Credito**: `30 days` (i crediti si azzerano a ogni ciclo di fatturazione) La precisione non può essere modificata dopo la creazione di un credito. Per i conteggi dei token, `0` (numeri interi) è quasi sempre corretto. Lascia **disabilitato** lo sforamento qui — lo configurerai per piano quando aggancerai il credito ai prodotti. Ciò consente al piano Iniziale di bloccare l'uso a zero mentre il piano Pro consente lo sforamento. Le impostazioni di sforamento configurate qui sono *predefinite*. Ogni collegamento del prodotto può sovrascriverle — ed è esattamente ciò che faremo nel Passaggio 3. Clicca su **Crea Credito**. Una volta salvato, apri il credito e copia il suo ID — sembra `cent_xxxxxxxxxxxx`. Il tuo diritto di credito `API Tokens` è pronto. Successivamente, crea un misuratore affinché gli eventi di utilizzo possano guidare le detrazioni automaticamente. ## Passaggio 2: Crea un Misuratore per l'Uso dei Token Un misuratore aggrega gli eventi di utilizzo in arrivo e li converte in detrazioni di credito. Ti serve questo *prima* di creare i prodotti del piano, poiché lo aggancerai durante la creazione del prodotto nel Passaggio 3. 1. Nella barra laterale della dashboard, vai su **Prodotti → Misuratori** 2. Clicca su **Crea Misuratore** Compila: **Nome Misuratore**: `Token Usage Meter` **Nome Evento**: `api.tokens_used` *(questo deve corrispondere esattamente a ciò che invia la tua app)* **Tipo di Aggregazione**: `Sum` — sommiamo il conteggio dei token da ogni evento **Sopra la Proprietà**: `tokens` — la chiave dei metadati su ciascun evento il cui valore verrà sommato **Unità di Misura**: `tokens` I nomi degli eventi sono case-sensitive. `api.tokens_used` ≠ `Api.Tokens.Used` — scegline uno e attieniti a esso. Salva il misuratore e copia il suo ID — lo citerai quando lo agganci ai prodotti. Il misuratore è creato. Ora possiamo collegarlo al credito quando configuriamo i prodotti. ## Passaggio 3: Crea i Prodotti del Piano Entrambi i piani devono essere prodotti **Usage Based Billing**, non semplici Abbonamenti — i misuratori possono essere agganciati solo ai prodotti UBB, e hai bisogno del misuratore per detrarre automaticamente i crediti quando i clienti chiamano la tua API. I prodotti UBB supportano ancora una tariffa base ricorrente (la `$29` / `$99`); l'uso al di sopra di tale soglia viene fatturato in crediti. Configurazione della tariffazione Basata sull'Uso ### Piano Iniziale (\$29/mese — 10M token, nessuno sforamento) 1. Vai su **Prodotti → Crea Prodotto** 2. Seleziona **Usage Based Billing** come tipo di tariffazione 3. Compila: **Nome Prodotto**: `NeuralAPI Starter` **Descrizione**: `10 million API tokens per month. Perfect for individual developers and small projects.` **Prezzo Fisso**: `29.00` (la tariffa base ricorrente — fatturata mensilmente anche prima di qualsiasi utilizzo) **Ciclo di Fatturazione**: `Monthly` **Valuta**: `USD` Nella sezione **Seleziona Misuratore**, clicca su **+** e aggiungi `Token Usage Meter`. Poi sul misuratore: 1. Attiva **Fattura utilizzo in Crediti** 2. **Diritto di Credito**: seleziona `API Tokens` 3. **Unità di Misura per Credito**: `1` — ogni token nell'evento mappa a 1 credito detratto 4. **Soglia Gratuita**: `0` — la stessa allocazione del credito è il "livello gratuito" del cliente; non abbiamo bisogno di una banda gratuita extra Misuratore con usare il fatturato nei crediti abilitati e token API selezionati Questo è il collegamento che fa sì che gli eventi `api.tokens_used` in arrivo detraggano effettivamente dal saldo del cliente. Ancora sul prodotto, scorri alla sezione di configurazione del credito che appare una volta agganciato un misuratore fatturato in crediti: **Crediti emessi per ciclo di fatturazione**: `10000000` **Consentire Sforamento**: **Disabilitato** — i clienti Iniziali sono bloccati quando i token si esauriscono **Importa Impostazioni di Credito Predefinite**: Abilitato — usa la scadenza di 30 giorni dal diritto di credito Modulo di configurazione dei crediti con importo per ciclo e impostazioni di sforamento Clicca **Salva** e copia l'ID del prodotto. Piano Iniziale: tariffa base di \$29/mese, 10M token/ciclo, bloccato a zero, detrazioni automatiche tramite misuratore. ### Piano Pro (\$99/mese — 40M token, sforamento abilitato) Stesso flusso del Piano Iniziale, con numeri maggiori: **Nome Prodotto**: `NeuralAPI Pro` **Descrizione**: `40 million API tokens per month with overage. Built for production applications.` **Prezzo Fisso**: `99.00` **Ciclo di Fatturazione**: `Monthly` **Valuta**: `USD` Identico al Piano Iniziale: aggiungi `Token Usage Meter`, attiva **Fattura utilizzo in Crediti**, seleziona `API Tokens`, **Unità di Misura per Credito** `1`, **Soglia Gratuita** `0`. Configura l'emissione del credito, questa volta abilitando lo sforamento: **Crediti emessi per ciclo di fatturazione**: `40000000` **Importa Impostazioni di Credito Predefinite**: **Disabilitato** — dobbiamo personalizzare le impostazioni di sforamento per prodotto **Consenti Sforamento**: **Abilitato** **Prezzo per Unità**: `0.000005` USD per token (cioè, $0.005 per 1K token, o $5 per 1M token — sopra la tariffa effettiva per token del piano per scoraggiare gli spurghi) **Comportamento dello Sforamento**: `Bill overage at billing` — lo sforamento viene addebitato sulla fattura successiva, quindi il saldo si azzera Salva il prodotto e copia l'ID del prodotto. Piano Pro: tariffa base di $99/mese, 40M token/ciclo, sforamento a $0.005/1K token, detrazioni automatiche tramite misuratore. ## Passaggio 4: Crea il Pacchetto di Ricarica Token Il pacchetto di ricarica è un acquisto una tantum che aggiunge 5,000,000 token al saldo di un cliente esistente. Sezione dei prezzi del prodotto con Pagamento Singolo selezionata 1. Vai su **Prodotti → Crea Prodotto** 2. Seleziona **Pagamento Singolo** come tipo di tariffazione 3. Compila: **Nome Prodotto**: `Token Top-Up Pack` **Descrizione**: `Instantly add 5 million tokens to your NeuralAPI balance.` **Prezzo**: `19.00` **Valuta**: `USD` 1. Nella sezione **Diritti**, clicca su **Collega** accanto a **Crediti** 2. Seleziona `API Tokens` 3. Imposta **Crediti emessi**: `5000000` 4. **Disabilita** *Importa Impostazioni di Credito Predefinite* — vogliamo sovrascrivere la scadenza predefinita di 30 giorni 5. Imposta **Scadenza Credito**: `365 days` 6. Salva il prodotto Copia l'ID del prodotto. Perché una scadenza più lunga sulle ricariche? I crediti di abbonamento si azzerano ogni 30 giorni perché è il ciclo. Le ricariche sono *acquisti prepagati* — il cliente ha pagato \$19 in anticipo e si aspetta ragionevolmente che quei token durino più di un mese. 365 giorni corrispondono a come funzionano davvero i crediti prepagati su OpenAI, AWS e Anthropic, pur limitando la tua responsabilità in modo che i clienti non possano accumulare indefinitamente. Pacchetto di Ricarica configurato — l'acquisto concede 5,000,000 token che rimangono validi per 365 giorni. ## Passaggio 5: Costruisci il Backend Ora costruiamo il server Express che gestisce il checkout dell'abbonamento, il checkout della ricarica, i completamenti OpenAI reali con fatturazione dei token, le query del saldo e gli eventi di webhook del credito. ```bash theme={null} mkdir neural-api-billing cd neural-api-billing npm init -y npm install dodopayments openai express dotenv npm install -D @types/node @types/express typescript tsx ``` Crea un `tsconfig.json`: ```json tsconfig.json theme={null} { "compilerOptions": { "target": "ES2022", "module": "commonjs", "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true } } ``` Aggiorna `package.json` scripts: ```json package.json theme={null} { "scripts": { "dev": "tsx watch src/server.ts", "build": "tsc", "start": "node dist/server.js" } } ``` Crea `.env` con le tue credenziali e gli ID dai passaggi precedenti: ```bash .env theme={null} DODO_PAYMENTS_API_KEY=your_dodo_api_key_here DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_secret_here DODO_ENVIRONMENT=test_mode OPENAI_API_KEY=sk-... CREDIT_ENTITLEMENT_ID=cent_xxxxxxxxxxxx STARTER_PLAN_PRODUCT_ID=pdt_xxxxxxxxxxxx PRO_PLAN_PRODUCT_ID=pdt_xxxxxxxxxxxx TOPUP_PRODUCT_ID=pdt_xxxxxxxxxxxx BASE_URL=http://localhost:3000 ``` Non commettere mai `.env` nel controllo della versione. Aggiungilo immediatamente a `.gitignore`. Compilerai `DODO_PAYMENTS_WEBHOOK_KEY` nel Passaggio 7 dopo aver registrato il tuo endpoint di webhook. Crea `src/server.ts`: ```typescript src/server.ts expandable theme={null} import 'dotenv/config'; import DodoPayments from 'dodopayments'; import OpenAI from 'openai'; import express, { Request, Response } from 'express'; const app = express(); // IMPORTANT: webhook route needs the raw body for signature verification. // We register the raw parser ONLY on /webhooks/dodo, then JSON for everything else. app.use('/webhooks/dodo', express.raw({ type: 'application/json' })); app.use(express.json()); app.use(express.static('public')); const dodo = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY!, webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY, environment: (process.env.DODO_ENVIRONMENT as 'test_mode' | 'live_mode') ?? 'test_mode', }); const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! }); const CREDIT_ENTITLEMENT_ID = process.env.CREDIT_ENTITLEMENT_ID!; const BASE_URL = process.env.BASE_URL!; const PLAN_PRODUCTS: Record = { starter: process.env.STARTER_PLAN_PRODUCT_ID!, pro: process.env.PRO_PLAN_PRODUCT_ID!, }; // ──────────────────────────────────────────────────────────────────────────── // Subscription checkout // Body: { plan: 'starter' | 'pro', email: string, name: string } // ──────────────────────────────────────────────────────────────────────────── app.post('/checkout/subscribe', async (req: Request, res: Response) => { const { plan, email, name } = req.body; if (!PLAN_PRODUCTS[plan]) { return res.status(400).json({ error: `Unknown plan: ${plan}` }); } try { const session = await dodo.checkoutSessions.create({ product_cart: [{ product_id: PLAN_PRODUCTS[plan], quantity: 1 }], customer: { email, name }, return_url: `${BASE_URL}/?subscribed=1`, }); res.json({ checkout_url: session.checkout_url, session_id: session.session_id }); } catch (err) { console.error('Subscription checkout error:', err); res.status(500).json({ error: 'Failed to create subscription checkout' }); } }); // ──────────────────────────────────────────────────────────────────────────── // Top-up checkout — buyer must already be a customer // Body: { customer_id: string } // ──────────────────────────────────────────────────────────────────────────── app.post('/checkout/topup', async (req: Request, res: Response) => { const { customer_id } = req.body; if (!customer_id) return res.status(400).json({ error: 'customer_id required' }); try { const session = await dodo.checkoutSessions.create({ product_cart: [{ product_id: process.env.TOPUP_PRODUCT_ID!, quantity: 1 }], customer: { customer_id }, return_url: `${BASE_URL}/?topup=1`, }); res.json({ checkout_url: session.checkout_url }); } catch (err) { console.error('Top-up checkout error:', err); res.status(500).json({ error: 'Failed to create top-up checkout' }); } }); // ──────────────────────────────────────────────────────────────────────────── // Live token balance for a customer // ──────────────────────────────────────────────────────────────────────────── app.get('/credits/:customerId', async (req: Request, res: Response) => { try { const result = await dodo.creditEntitlements.balances.retrieve(req.params.customerId, { credit_entitlement_id: CREDIT_ENTITLEMENT_ID, }); res.json({ balance: result.balance, overage: result.overage, last_transaction_at: result.last_transaction_at, }); } catch (err) { console.error('Balance fetch error:', err); res.status(500).json({ error: 'Failed to fetch credit balance' }); } }); // ──────────────────────────────────────────────────────────────────────────── // AI completion — calls OpenAI, then ingests a usage event with the real // token count. The meter aggregates these and deducts credits automatically. // Body: { customer_id: string, prompt: string } // ──────────────────────────────────────────────────────────────────────────── app.post('/api/generate', async (req: Request, res: Response) => { const { customer_id, prompt } = req.body; if (!customer_id || !prompt) { return res.status(400).json({ error: 'customer_id and prompt required' }); } // Best-effort balance gate for Starter (no overage). Note: balance updates // are eventually consistent (~1 min lag from event ingestion), so a Starter // customer can technically squeeze through a few extra requests right after // running out. Use a stricter rate-limiter on top if you need hard cutoffs. try { const balance = await dodo.creditEntitlements.balances.retrieve(customer_id, { credit_entitlement_id: CREDIT_ENTITLEMENT_ID, }); if (Number(balance.balance) <= 0 && Number(balance.overage) <= 0) { return res.status(402).json({ error: 'Out of tokens. Top up or upgrade to continue.', }); } } catch { // Fall through — if the balance lookup fails, don't block; rely on metering. } let completion; try { completion = await openai.chat.completions.create({ model: 'gpt-5-mini', messages: [{ role: 'user', content: prompt }], }); } catch (err) { console.error('OpenAI error:', err); return res.status(502).json({ error: 'Upstream AI provider failed' }); } const tokensUsed = completion.usage?.total_tokens ?? 0; // Fire-and-forget — don't block the response on metering. ingestTokenUsage(customer_id, tokensUsed, completion.model).catch((err) => console.error('Usage ingest failed:', err), ); res.json({ text: completion.choices[0]?.message?.content ?? '', tokens_used: tokensUsed, model: completion.model, }); }); async function ingestTokenUsage(customerId: string, tokens: number, model: string) { await dodo.usageEvents.ingest({ events: [ { // event_id is the idempotency key. Use a stable, unique value per request. event_id: `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`, customer_id: customerId, event_name: 'api.tokens_used', timestamp: new Date().toISOString(), metadata: { tokens, model }, }, ], }); } // ──────────────────────────────────────────────────────────────────────────── // Webhook handler — verifies signature using the SDK, then routes events. // ──────────────────────────────────────────────────────────────────────────── app.post('/webhooks/dodo', async (req: Request, res: Response) => { const rawBody = (req.body as Buffer).toString('utf8'); const headers = { 'webhook-id': req.header('webhook-id') ?? '', 'webhook-signature': req.header('webhook-signature') ?? '', 'webhook-timestamp': req.header('webhook-timestamp') ?? '', }; let event: { type: string; data: any }; try { event = dodo.webhooks.unwrap(rawBody, { headers }) as any; } catch (err) { console.error('Webhook verification failed:', err); return res.status(401).json({ error: 'Invalid signature' }); } switch (event.type) { case 'credit.added': console.log(`[credit.added] customer=${event.data.customer_id} amount=${event.data.amount}`); break; case 'credit.deducted': console.log(`[credit.deducted] customer=${event.data.customer_id} amount=${event.data.amount}`); break; case 'credit.overage_charged': console.log(`[credit.overage_charged] customer=${event.data.customer_id}`); break; default: // Ignore other event types break; } res.json({ received: true }); }); app.listen(3000, () => { console.log('NeuralAPI billing server running on http://localhost:3000'); }); ``` ```json package.json theme={null} { "name": "neural-api-billing", "version": "1.0.0", "scripts": { "dev": "tsx watch src/server.ts", "build": "tsc", "start": "node dist/server.js" }, "dependencies": { "dodopayments": "latest", "openai": "^4.0.0", "express": "^4.18.0", "dotenv": "^16.0.0" }, "devDependencies": { "@types/node": "^20.0.0", "@types/express": "^4.17.0", "typescript": "^5.0.0", "tsx": "^4.0.0" } } ``` Backend completato: checkout dell'abbonamento, checkout della ricarica, completamento OpenAI con fatturazione dei token misurati, query del saldo e un gestore del webhook verificato. [`@dodopayments/ingestion-blueprints`](/features/usage-based-billing/ingestion-blueprints) fornisce tracker drop-in che automatizzano la chiamata `usageEvents.ingest` per te — incluso il [LLM Blueprint](/developer-resources/ingestion-blueprints/llm), [API gateway](/developer-resources/ingestion-blueprints/api-gateway), [object storage](/developer-resources/ingestion-blueprints/object-storage), [streams](/developer-resources/ingestion-blueprints/stream), e [time-range](/developer-resources/ingestion-blueprints/time-range) usage. Potresti aver notato che non c'è alcuna chiamata esplicita "detrarre N crediti". Questo è voluto: 1. Il tuo gestore chiama OpenAI e riceve `usage.total_tokens` (es. 1532). 2. Inserisci un singolo evento di utilizzo: `event_name: api.tokens_used`, `metadata: { tokens: 1532 }`. 3. `Token Usage Meter` aggrega gli eventi per cliente. 4. Poiché il misuratore è collegato al credito `API Tokens` con **Fattura utilizzo in Crediti**, Dodo Payments detrae 1532 crediti dal grant non scaduto più vecchio del cliente (FIFO). 5. Se lo sforamento è abilitato e il cliente va sotto zero, il deficit viene tracciato e fatturato sulla fattura successiva. Il misuratore gestisce tutto ciò. Il tuo codice inserisce solo eventi. ## Passaggio 6: Aggiungi un Frontend Demo Crea `public/index.html` per testare tutti i flussi nel tuo browser. Persistiamo l'ID cliente su `localStorage` in modo che abbonamento → generazione → ricarica condividano tutti la stessa identità, imitando un'app con accesso: ```html public/index.html expandable theme={null} NeuralAPI Demo

NeuralAPI Demo

After completing checkout, copy the customer ID from your Dodo Payments dashboard (Customers → most recent) and paste here.

1. Subscribe to a Plan

2. Generate AI Response (deducts tokens)

3. Live Token Balance

4. Buy a Top-Up Pack

``` ## Passaggio 7: Collegare il Webhook I webhook consentono al tuo server di reagire ai cambiamenti di saldo — li utilizzerai per inviare email di "saldo in esaurimento" prima che i clienti raggiungano lo zero. I webhook necessitano di un URL pubblico. Per lo sviluppo locale, usa [ngrok](https://ngrok.com) o qualsiasi tunnel: ```bash theme={null} ngrok http 3000 ``` Copia l'URL `https://...ngrok-free.app`. 1. Nella dashboard, vai su **Sviluppatori → Webhook → Aggiungi Endpoint** 2. **URL**: `https://your-tunnel.ngrok-free.app/webhooks/dodo` 3. Iscriviti a (al minimo): * `credit.added` * `credit.deducted` * `credit.overage_charged` 4. Salva e copia il **Segreto della Firma** 5. Incollalo in `.env` come `DODO_PAYMENTS_WEBHOOK_KEY`, quindi riavvia `npm run dev` L'SDK `dodo.webhooks.unwrap()` valida i valori `webhook-id`, `webhook-timestamp` e `webhook-signature` usando il tuo segreto per la firma. Non devi realizzare un HMAC a mano — e non dovresti, perché Dodo Payments utilizza [Standard Webhooks](https://www.standardwebhooks.com/), che firma `id.timestamp.body` invece del solo body. ## Passaggio 8: Testa il Flusso Completo 1. Esegui `npm run dev` 2. Apri `http://localhost:3000` 3. Scegli **Piano Pro**, inserisci un'email e un nome di test, clicca **Ottieni Link per il Checkout**, completa il checkout con [dettagli della carta di test](/miscellaneous/testing-process) 4. Nella dashboard, vai su **Clienti → il più recente** e copia l'ID `cus_...` 5. Incollalo nel campo "ID cliente loggato" nel demo e clicca **Salva** Il cliente dovrebbe avere 40,000,000 token. Clicca **Aggiorna Saldo** per confermare. Digita un prompt e clicca **Genera**. Il server chiama OpenAI, ottiene indietro il valore effettivo `total_tokens`, inserisce un evento di utilizzo e restituisce la risposta. Gli eventi di utilizzo vengono elaborati da un lavoratore in background ogni \~minuto. Il saldo non calerà istantaneamente — attendi 30–90 secondi e clicca di nuovo su **Aggiorna Saldo**. Non concludere che sia rotto se il primo aggiornamento non mostra movimento. Clicca **Acquista 5M Token — \$19** e completa il checkout. Dopo che il pagamento è avvenuto, aggiorna il saldo — dovrebbe aumentare di 5,000,000 token. Il registro del server dovrebbe mostrare un evento `credit.added`. ## Risoluzione dei Problemi **Cause Possibili:** * Il nome dell'evento del misuratore non corrisponde a `event_name` che stai inviando (`api.tokens_used` è case-sensitive) * Il misuratore non è collegato al credito `API Tokens` sul prodotto — vai alla configurazione del misuratore del prodotto e conferma che **Fattura utilizzo in Crediti** è attivato * La chiave `metadata.tokens` non corrisponde al campo "Sopra la Proprietà" del misuratore * Il grant del cliente è scaduto (controlla la cronologia dei crediti del cliente) **Cosa Controllare:** 1. **Prodotti → Misuratori**: apri il misuratore e conferma che mostra il nome del credito collegato sul collegamento del prodotto 2. La scheda **Eventi** sul misuratore — gli eventi inseriti dovrebbero apparire lì anche prima della detrazione 3. **Clienti → \[Cliente] → Crediti**: le voci del registro dovrebbero apparire entro un minuto o due **Cause Possibili:** * Il cliente non ha ancora completato il checkout — i crediti vengono emessi solo dopo un pagamento riuscito * Stai interrogando con il `customer_id` sbagliato (usa l'ID `cus_...` dalla dashboard, non il tuo ID DB) * Il `CREDIT_ENTITLEMENT_ID` in `.env` non corrisponde al credito attaccato al prodotto **Cosa Controllare:** Apri **Clienti → \[Cliente] → Crediti**. Se non appaiono crediti lì, il diritto del prodotto non è stato attaccato o il pagamento non è stato completato. **Cause Possibili:** * Lo sforamento non è stato abilitato sul **collegamento del credito del prodotto Pro** (l'impostazione a livello di credito è solo un predefinito) * Il cliente è effettivamente sul Piano Iniziale, non sul Pro * Il limite di sforamento è stato impostato a 0 **Cosa Controllare:** Modifica Pro → Diritti → Crediti → conferma che **Consenti Sforamento** sia attivato e che **Prezzo per Unità** sia `0.000005` (= \$5 per milione di token; ricontrolla gli zeri principali — il campo accetta il prezzo per token, non per 1K). **Cause Possibili:** * Ordine di parsing del corpo: `express.json()` è stato applicato a `/webhooks/dodo` prima di `express.raw()` — l'SDK ha bisogno dei **byte grezzi** della richiesta, non del JSON parsato * Segreto di firma errato in `DODO_PAYMENTS_WEBHOOK_KEY` * Il proxy inverso sta riscrivendo le intestazioni **Cosa Controllare:** Conferma che la linea `app.use('/webhooks/dodo', express.raw(...))` venga *prima* di `app.use(express.json())` in `server.ts`. ## Hai Bisogno di Aiuto? * [Discord Community](https://discord.gg/bYqAp4ayYh) * [support@dodopayments.com](mailto:support@dodopayments.com) ## Congratulazioni! Hai Costruito la Fatturazione Basata su Crediti per NeuralAPI La tua piattaforma ora ha un sistema di fatturazione a crediti completo e pronto per la produzione: Un credito `API Tokens` riutilizzabile con scadenza di 30 giorni, condiviso tra tutti i piani e il pacchetto di ricarica Piano Iniziale (10M, limite rigido) e Pro (40M + sforamento) configurati per prodotto senza duplicazione del credito I clienti aggiungono 5M token per \$19 senza cambiare il loro abbonamento I conteggi reali dei token OpenAI vengono inseriti come eventi; il misuratore detrae i crediti FIFO senza tracciamento manuale Saldo in tempo reale tramite l'SDK per regolare l'accesso, visualizzare l'uso o avvisare i clienti nell'app Eventi del registro crediti (`credit.added`, `credit.deducted`, `credit.overage_charged`) instradati tramite un gestore verificato dal SDK **Vai in produzione?** Stringi queste: * **Autenticazione su `/credits/:customerId` e `/api/generate`** — attualmente chiunque può colpire questi con qualsiasi ID cliente. Autentica gli utenti e cerca *il loro* ID cliente lato server. * **Stable `event_id`s** — l'esempio utilizza `Date.now() + random`. In produzione, usa il tuo ID richiesta in modo che i tentativi siano idempotenti (Dodo Payments deduplica per `event_id`). * **Mantieni la mappatura cliente↔utente** — memorizza `customer_id` nel tuo DB dopo il primo checkout in modo da non avere bisogno di un passaggio di copia manuale. * **Decidi cosa succede quando un abbonamento termina.** I crediti del piano rimangono nel registro del cliente fino alla loro scadenza naturale (30 giorni dall'emissione) e i crediti di ricarica restano validi per 365 giorni — ma il cookbook `/api/generate` controlla solo *saldo*, non stato dell'abbonamento. Quindi un cliente annullato può ancora consumare i token rimanenti. Questo è il default amichevole per il consumatore. Se desideri un controllo dell'accesso più rigoroso, o (a) ascolta il webhook `subscription.cancelled` e regola `/api/generate` in base allo stato dell'abbonamento, o (b) chiama l'API del registro di Dodo per addebitare i crediti inutilizzati del piano in caso di cancellazione lasciando intatti i crediti di ricarica. * **Monitora il dashboard Usage Billing** per rilevare precocemente anomalie di misurazione. Documentazione completa CBB: rollover, modalità di sforamento, gestione del registro, tutti gli endpoint API. Schemi dei payload per ogni evento di credito che il tuo server potrebbe ricevere.