PayStars API per sviluppatori: il flusso completo per vendere Stars e Premium nel tuo bot
Come funziona l'API REST di PayStars dall'inizio alla fine: X-API-Key, controlli del nome utente, preventivi in USD con max_usd, ordini idempotenti, l'errore 409 price_changed e la verifica del TxId, come piano di integrazione.
Pubblicato: · Aggiornato:

Vuoi vendere Telegram Stars e Premium nel tuo bot, negozio o applicazione? La PayStars API ti offre un'unica interfaccia HTTPS e un saldo in USD condiviso con il sito. Invece di ripetere il riferimento dell'API, questo articolo mostra come costruire l'integrazione dall'inizio alla fine.
L'architettura a colpo d'occhio
Il tuo sistema fa tre cose: ricarica il saldo con USDT, richiede un prezzo e crea un ordine. Tutto il resto, compresa la consegna tramite il flusso di acquisto ufficiale di Telegram, avviene dal lato di PayStars.
| Parte | Cosa fa |
|---|---|
| Accesso | Intestazione X-API-Key; le chiavi si creano nel pannello di controllo |
| Saldo | USD, ricaricato con USDT (TON, BEP20 o TRC20) |
| Prezzo | Prezzo di Fragment × 1,05, arrotondato per eccesso al centesimo |
| Limite | 10 richieste al secondo per chiave |
| Trasparenza | Un TxId pubblico per ogni ordine completato |
Fase 1: ricarica il saldo
POST /usd/invoice con un importo e una rete ("ton", "bsc" o "trc20") restituisce un importo esatto valido per 30 minuti. Il minimo è 0,1 USDT.
Fase 2: verifica il destinatario
POST /api/v1/check-username controlla il destinatario e restituisce un token di verifica a breve durata. Questo evita pagamenti verso nomi utente inesistenti: se un cliente sbaglia a digitare, lo scopri prima che venga addebitato qualcosa.
Fase 3: ottieni il prezzo e fissane il tetto
POST /api/v1/usd/quote restituisce il prezzo attuale (usd) e il ricarico (markup_percent: 5). Il prezzo segue il mercato, quindi:
- richiedi un preventivo aggiornato prima di ogni ordine;
- passa max_usd uguale all'importo del preventivo;
- invia sempre currency: "USD", altrimenti si usa la preferenza salvata dell'account.
Fase 4: crea l'ordine
POST /api/v1/stars/buy oppure /api/v1/premium/buy. Ogni richiesta deve includere un'Idempotency-Key, così se la connessione si interrompe e riprovi non vieni addebitato due volte. Salva la chiave insieme all'ID dell'ordine nel database.
Fase 5: monitora lo stato
GET /api/v1/order/{id} e /api/v1/orders forniscono stati e cronologia. La maggior parte degli ordini viene consegnata entro pochi minuti. Un ordine completato riceve un TxId che sia tu sia il cliente potete verificare sul registro pubblico di PayStars.
Gestire correttamente gli errori
- 409 price_changed significa che il prezzo ha superato max_usd e non è stato addebitato nulla. Richiedi un nuovo preventivo e mostra al cliente il prezzo aggiornato.
- Limite di frequenza: non superare 10 richieste al secondo; aggiungi una coda o un ritardo progressivo.
- Nuovi tentativi: riutilizza sempre la stessa Idempotency-Key.
Prima di andare in produzione
- Conserva la chiave API in una variabile d'ambiente del server, non nel codice.
- Esegui l'intero flusso con un piccolo ordine reale di 50 Stars.
- Mostra ai clienti il loro TxId: rafforza la fiducia.
Documentazione completa e guide rapide: PayStars Stars API e prezzi in USD per l'API. Per i pagamenti nel bot, vedi i beni digitali nei bot si pagano solo in Stars.
Domande frequenti
Esiste un ambiente di prova?
Non c'è un ambiente di prova separato; durante l'integrazione testa con piccoli ordini reali (50 Stars).
Quali linguaggi di programmazione funzionano?
Qualsiasi linguaggio in grado di fare richieste HTTPS. Ci sono guide rapide per Python, Node.js e PHP.
Come ricarico il saldo?
Con USDT su TON, BEP20 o TRC20, minimo 0,1 USDT; ogni fattura ha un importo esatto valido per 30 minuti.
Fonti
Related pages
Acquista Stars e Premium con USD (USDT)
Con chiave API: prezzo Fragment, 0% (sito: 5%).
More news
Telegram Stars e Premium in Uzbekistan: paga con carta o con USDTAcquistare Telegram Stars o Premium in Uzbekistan: Uzcard e Humo tramite @StarKerakBot, USDT su paystars.uz/uz/, i canali ufficiali dell'app e le regole locali da conoscere.Leggi →
Come premiare i vincitori di un contest con Telegram Stars o Premium: una guida per gli organizzatoriConsegna di Telegram Stars o Premium ai vincitori del tuo quiz, concorso o hackathon: budget, raccolta di @usernames, consegna tramite PayStars e un resoconto successivo.Leggi →
Domande frequenti PayStars: accesso, ricariche USDT e ordini di Stars e PremiumLe domande più frequenti su PayStars in una sola pagina: accesso con Telegram, ricarica con USDT (TON, BEP20 o TRC20), ordini di Stars e Premium, tempi di consegna, sicurezza e API.Leggi →