Come configurare la ricarica automatica del saldo nel pannello SMM tramite API

Cosa preparare prima di configurare la ricarica automatica

La ricarica automatica collega il saldo del pannello SMM a un servizio di pagamento o alla fatturazione interna. Il servizio controlla il saldo residuo, crea un pagamento al raggiungimento della soglia impostata e accredita i fondi solo dopo la conferma del pagamento. Per funzionare servono la documentazione API del pannello, l'accesso all'API di pagamento, chiavi separate per l'ambiente di test e quello di produzione, oltre a un registro di tutte le operazioni.

Prima dello sviluppo verificate se l'API del pannello è in grado di restituire il saldo, accettare una richiesta di accredito, mostrare la cronologia delle ricariche e ricevere un identificatore esterno dell'operazione. Se il pannello non supporta l'accredito tramite API, l'automazione potrà solo creare una richiesta o inviare una notifica all'operatore. Il difetto di questa soluzione è che i fondi andranno comunque versati manualmente.

Separate il controllo del saldo dalla decisione di pagamento

È meglio avviare il controllo del saldo residuo come attività separata secondo una pianificazione. Questa ottiene il saldo, lo confronta con la soglia e trasmette il risultato al gestore della ricarica. Non create il pagamento direttamente al momento della risposta API senza verificare le operazioni in corso non ancora completate: attività parallele potrebbero vedere lo stesso saldo basso e creare più pagamenti.

Prima di un nuovo pagamento il gestore deve verificare se esiste un'operazione con stato "creata", "in attesa di pagamento" o "in conferma". Se tale record esiste, un nuovo tentativo non viene avviato fino al completamento della verifica. Il difetto dell'elaborazione sequenziale è che, in caso di risposta lenta dell'API esterna, la ricarica può iniziare più tardi rispetto a più richieste parallele.

Scegliete la soglia e la logica dell'importo di ricarica

La soglia del saldo va scelta con un margine per gli ordini attivi, la coda presso i fornitori e i ritardi dei pagamenti. Per un canale con attività irregolare è rischioso basarsi solo sulla spesa media: dopo uno stream, l'avvio della pubblicità o un ordine massivo gli addebiti possono aumentare bruscamente. Si imposta separatamente un livello critico al quale arriva la notifica, ma il pagamento non viene necessariamente creato in automatico.

L'importo della ricarica può essere fisso o calcolato in base alla spesa del periodo scelto. Un importo fisso è più semplice da controllare e verificare. Il suo difetto è che in un periodo tranquillo sul saldo possono restare fondi in eccesso, mentre con una crescita brusca degli ordini una sola ricarica può non bastare. L'importo calcolato è più flessibile, ma richiede di ripulire le statistiche da addebiti anomali e rimborsi.

Configurate i limiti finanziari separatamente dalla soglia

La soglia risponde solo alla domanda su quando il sistema è autorizzato ad avviare il processo di ricarica. I limiti rispondono a un'altra domanda: quanti fondi è autorizzato ad addebitare. Impostate l'importo massimo di una singola operazione, il limite complessivo per periodo e il saldo consentito dopo l'accredito. Queste regole vengono verificate prima della creazione del pagamento, non dopo il suo pagamento.

La ricarica automatica non deve addebitare fondi senza un limite per operazione e periodo. Se l'importo calcolato supera quello consentito, è meglio spostare l'operazione in verifica manuale e inviare una notifica. Il difetto dei limiti rigidi è che, con una rapida crescita delle spese, il saldo può esaurirsi prima che il dipendente responsabile confermi l'aumento del limite.

Create chiavi separate e proteggete l'accesso

Per lo script di ricarica automatica usate chiavi API separate con privilegi minimi: lettura del saldo, creazione del pagamento, verifica dello stato e accredito dell'operazione confermata. L'accesso a utenti, impostazioni dei servizi, ordini e prelievi non è necessario per tale chiave. Se il servizio supporta la restrizione per indirizzi IP, consentite le richieste solo dal server dell'integrazione.

Le chiavi si conservano in variabili d'ambiente o in un archivio protetto dei segreti. Non trasferitele nel codice del browser, nei log, nei repository pubblici e nei messaggi di errore. Ogni chiave deve avere un proprietario e una procedura di sostituzione chiara. Il difetto della rotazione frequente delle chiavi è che la ricarica si ferma se il nuovo segreto non viene aggiornato in tutti i processi operativi.

Create il pagamento con un identificatore univoco

A ogni ricarica viene assegnato un identificatore interno prima di chiamare l'API di pagamento. Viene salvato nel registro e trasmesso come chiave di idempotenza o numero esterno dell'operazione. In caso di timeout di rete la stessa richiesta può essere ripetuta con lo stesso identificatore: il servizio di pagamento deve restituire l'operazione già creata, non addebitare di nuovo il denaro.

Di seguito un esempio generico di richiesta. Sostituite i nomi dei campi e gli indirizzi con i valori della documentazione del provider specifico. Nella variabile PAYMENT_ID è memorizzato un ID univoco creato in anticipo, mentre CALLBACK_URL punta al gestore dei webhook.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Non determinate l'unicità del pagamento solo in base all'importo e all'ora di creazione. Due ricariche identiche possono essere legittime, mentre una richiesta ripetuta dopo un guasto no. Il difetto dell'ID esterno nel proprio database è che va conservato in modo affidabile e non va riutilizzato dopo l'annullamento dell'operazione.

Verificate il saldo e salvate lo stato dell'operazione

La richiesta del saldo deve essere eseguita prima della decisione su una nuova ricarica e dopo un accredito riuscito. Una richiesta generica può essere così: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Nella risposta salvate non solo l'importo, ma anche l'ora del controllo, per non prendere decisioni su dati obsoleti.

Per ogni operazione tenete un record con ID interno, ID del pagamento presso il provider, importo, valuta, ora di creazione, stato, risposte API e causa dell'errore. Una catena di stati adeguata: "creata", "in attesa di pagamento", "pagata", "in accredito", "accreditata", "annullata", "richiede verifica".

L'accredito nel pannello è consentito solo per un pagamento confermato e non ancora elaborato. Non riscrivete gli stati senza cronologia: in caso di contestazione deve essere visibile quale richiesta è stata inviata e perché l'operazione è stata modificata. Il difetto del registro dettagliato è che può contenere dati sensibili, per cui l'accesso va limitato.

Ricevete il webhook e verificate lo stato del pagamento

La pagina di pagamento riuscito e il redirect dell'utente non confermano l'arrivo del denaro. La conferma è data dal webhook del servizio di pagamento o da una nuova verifica dello stato tramite la sua API. Al ricevimento del webhook verificate la firma, l'ora di invio, l'ID del pagamento, l'ID esterno, l'importo e la valuta. Solo dopo portate l'operazione allo stato di pagamento confermato.

Dopo la verifica del webhook è utile richiedere al provider lo stato attuale del pagamento. Ad esempio: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Confrontate lo stato con i dati del registro, poi inviate la richiesta di accredito al pannello SMM con lo stesso ID interno.

Un webhook ripetuto non deve creare un secondo accredito. Il gestore trova l'operazione tramite l'ID esterno, vede lo stato "accreditata" e restituisce una risposta di successo senza nuove azioni. Il difetto dei webhook è che possono ritardare o non arrivare se il gestore era non disponibile.

Gestite timeout, retry e pagamenti bloccati

In caso di timeout dopo la creazione del pagamento non inviate una nuova richiesta con un ID diverso. Prima trovate l'operazione tramite l'identificatore interno o ripetete la richiesta con la stessa chiave di idempotenza. Se il provider ha accettato la richiesta originale, restituirà il pagamento esistente. Questo protegge dal doppio addebito in caso di interruzione della connessione.

Se il webhook non è arrivato entro il tempo stabilito, un'attività in background richiede lo stato del pagamento tramite API. Le verifiche ripetute si effettuano con una pausa crescente e un numero limitato di tentativi, per non sovraccaricare l'API e il registro. L'operazione che resta a lungo in attesa viene spostata in verifica manuale, e non considerata annullata senza verifica.

In caso di risposte di errore temporaneo di rete o di indisponibilità dell'API i retry sono ammessi. In caso di rifiuto del pagamento, importo errato, firma del webhook non valida o superamento del limite, non conviene ripetere la richiesta automaticamente. Il difetto dei retry è che complicano la logica degli stati e possono creare un carico superfluo in caso di guasto massivo presso il provider.

Accreditate il pagamento confermato nel pannello SMM

Prima dell'accredito il gestore verifica ancora una volta: l'importo non supera il limite, la valuta coincide, l'operazione non è stata annullata e il suo stato non è ancora "accreditata". Nella richiesta si trasmettono l'importo e l'identificatore esterno del pagamento. Se l'API del pannello supporta la chiave di idempotenza, usate lo stesso ID interno dell'operazione.

Aspetto generico della richiesta: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

Dopo la risposta del pannello richiedete di nuovo il saldo e salvate il risultato nel registro. Se il denaro è stato addebitato dal servizio di pagamento ma l'API del pannello ha restituito un errore, non create un nuovo pagamento. L'operazione resta nello stato "richiede verifica" fino a un nuovo tentativo di accredito o a una verifica manuale. Il difetto di questo schema prudente è che il saldo può temporaneamente non essere ricaricato in automatico.

Aggiungete notifiche, interruttore e controllo dell'avvio

Le notifiche servono per le anomalie: il saldo è sceso sotto il livello critico, il pagamento è stato rifiutato, il webhook non è stato ricevuto, il limite è stato superato, l'API non è disponibile o l'operazione richiede una verifica manuale. Nel messaggio è sufficiente indicare l'ID interno, lo stato e la causa. Non includete chiavi API, firme dei webhook e dati di pagamento.

Lasciate un interruttore separato per la ricarica automatica senza rimuovere l'integrazione. Serve in caso di cambio fornitore, lavori tecnici, sospetto di errore o brusca variazione delle spese. Il difetto dell'interruttore è ovvio: se non viene riattivato dopo i lavori, il saldo può esaurirsi durante gli ordini attivi.

Checklist prima di attivare la ricarica automatica

• Il controllo del saldo non crea un pagamento finché esiste un'operazione non completata.
• Per ogni pagamento viene creato un ID interno univoco e una chiave di idempotenza.
• Sono impostati i limiti per una singola operazione e per il periodo scelto.
• I webhook vengono verificati per firma, importo, valuta e identificatore.
• In assenza del webhook viene avviata una nuova verifica dello stato tramite API.
• Il timeout non porta alla creazione di un secondo pagamento prima della verifica del primo.
• L'accredito nel pannello viene eseguito una sola volta e registrato nel log.
• La modalità di test è stata verificata su successo, rifiuto, webhook duplicato e indisponibilità dell'API.