Come usare l'API di un pannello SMM: guida al collegamento API v2 per rivenditori

L'API di un pannello SMM è il collegamento che permette di inviare ordini in automatico e controllarne lo stato da un altro pannello o da un tuo programma. 1PANEL PLUS usa l'API v2 standard dei pannelli SMM: se hai già del codice collegato a un altro pannello, ti basta cambiare indirizzo e chiave per collegarti subito. API e sito web usano gli stessi servizi, lo stesso prezzo per 1,000 e lo stesso saldo.

Chi usa l'API di un pannello SMM?

• Rivenditori: pubblicano i servizi sul proprio pannello e inoltrano in automatico gli ordini dei clienti
• Agenzie: inviano in una volta, a orari stabiliti, gli ordini di più canali
• Sviluppatori: creano script che ordinano all'avvio di una diretta o al caricamento di un nuovo video
• Gestori: riuniscono saldo e stato degli ordini nella propria schermata di gestione

Come si ottiene una chiave API?

Dopo che la prima ricarica è accreditata, creala nella schermata Chiave API della dashboard. La chiave viene mostrata una sola volta al momento della creazione, quindi copiala subito e conservala in un posto sicuro. Quando crei una nuova chiave, quella precedente smette subito di funzionare: se pensi che la chiave sia stata esposta, creane una nuova per sostituirla.

Come si inviano le richieste API?

Tutte le richieste si inviano in POST a un unico indirizzo, https://1panelplus.com/api/v2. Usa il formato che preferisci tra campi del form (application/x-www-form-urlencoded o multipart) e corpo JSON (Content-Type: application/json), e includi key e action in ogni richiesta. Tutte le risposte sono in JSON.

Esempio di richiesta (campi del form): key=YOUR_API_KEY&action=balance

Esempio di richiesta (JSON): {"key": "YOUR_API_KEY", "action": "balance"}

Come si ottiene l'elenco servizi con services?

Inviando action=services ricevi in un array tutti i servizi in vendita. Ogni servizio contiene service (numero del servizio), name, type, category, rate, min, max, refill e cancel. rate è il prezzo per 1,000 (USD), e se type è Package è il prezzo di un pacchetto. refill è true per i servizi con periodo di refill, e cancel è sempre false. category riporta insieme nome della piattaforma e categoria, quindi puoi ricreare le stesse categorie sul tuo pannello.

Esempio di risposta: [{"service": SERVICE_ID, "name": "Nome del servizio", "type": "Default", "category": "YouTube - Nome della categoria", "rate": "Prezzo per 1,000", "min": "Quantità minima", "max": "Quantità massima", "refill": true, "cancel": false}]

Prezzi e servizi possono cambiare, quindi se sei un rivenditore conviene scaricare di nuovo services a intervalli regolari e allineare prezzi e quantità minime e massime del tuo pannello.

Come si effettua un ordine con add?

Inviando action=add insieme a service (numero del servizio), link (link pubblico) e quantity (quantità), l'ordine viene registrato e l'importo viene subito scalato dal saldo. order nella risposta è il numero dell'ordine: salvalo e usalo per status e refill. Gli ordini si possono effettuare dagli account con la prima ricarica accreditata.

• Servizi normali: invia service, link e quantity
• Servizi Custom Comments: invia comments al posto di quantity. Un commento per riga, fino a 500 caratteri per riga, e il numero di righe è la quantità
• Servizi Package: non serve inviare la quantità. Si ordina un pacchetto

Esempio di richiesta: key=YOUR_API_KEY&action=add&service=SERVICE_ID&link=https://www.youtube.com/watch?v=videoid&quantity=1000

Esempio di risposta: {"order": ORDER_ID}

Come si controlla lo stato degli ordini con status?

Inviando action=status con order (un numero d'ordine) ricevi lo stato di quell'ordine, e inviando in orders i numeri d'ordine separati da virgole puoi controllarne fino a 100 in una volta. Se gestisci molti ordini, raggrupparli con orders ti fa risparmiare molte richieste.

Esempio di risposta (singolo): {"charge": "Importo addebitato", "start_count": "Conteggio iniziale", "status": "In progress", "remains": "Quantità restante", "currency": "USD"}

Esempio di risposta (multiplo): {"ORDER_ID_1": {"charge": "...", "start_count": "...", "status": "Completed", "remains": "0", "currency": "USD"}, "ORDER_ID_2": {"error": "Incorrect order ID"}}

charge è l'importo pagato meno l'importo rimborsato, quindi dopo un ordine parziale o annullato vedi subito quanto hai speso davvero. Lo stato degli ordini si aggiorna automaticamente circa ogni minuto, quindi basta interrogare status a intervalli di circa un minuto.

Come si usano refill e refill_status?

Inviando action=refill con order chiedi un refill e ricevi refill (numero del refill). Viene accettato per gli ordini Completati o Parziali di servizi con periodo di refill, entro il periodo contato dal giorno in cui l'ordine si è concluso, se non c'è un refill in corso e sono passate 24 ore dall'ultima richiesta. Inviando action=refill_status con refill ti indichiamo lo stato tra Pending, In progress, Completed e Rejected.

Esempi di risposta: {"refill": REFILL_ID} e {"status": "Completed"}

Le regole del refill sono le stesse del sito web. Le condizioni dettagliate sono in Il periodo di refill spiegato.

Come si controlla il saldo con balance?

Inviando action=balance ricevi il saldo attuale e la valuta (USD). Se sei un rivenditore, controlla il saldo prima di inoltrare gli ordini e imposta un avviso quando scende sotto una certa cifra: così gli ordini continuano senza interruzioni.

Esempio di risposta: {"balance": "Saldo attuale", "currency": "USD"}

Cosa significano i messaggi di errore dell'API?

Gli errori arrivano come JSON con una frase in inglese nel campo error. Ogni frase corrisponde a una causa precisa, quindi puoi confrontarla così com'è nel tuo programma e gestirla.

Per le richieste di refill possono arrivare Refill is not available for this service (servizio senza periodo di refill), Order is not finished yet (ordine non ancora concluso), Refill period has ended (periodo di refill scaduto) e Refill already requested, try again later (refill già in corso o 24 ore non ancora trascorse).

Quante richieste API si possono inviare?

Ogni chiave può inviare fino a 300 richieste al minuto. Se raggruppi i controlli di stato a 100 alla volta con orders e scarichi l'elenco servizi solo quando serve, il limite è più che sufficiente. Ad esempio, con 1,000 ordini in corso puoi controllarli tutti con 10 richieste una volta al minuto.

Come stabilisce un rivenditore i prezzi di vendita?

Il rate che ricevi dall'API è il prezzo per 1,000 di 1PANEL PLUS, e il prezzo di vendita sul tuo pannello lo decidi tu. Ad esempio, se vendi un servizio con rate di $2.00 aggiungendo il 25%, il prezzo diventa $2.50 per 1,000; se un cliente ordina 4,000 unità, l'importo di vendita è $10.00 e l'importo scalato su 1PANEL PLUS è $8.00. Questi prezzi sono un esempio per mostrare il calcolo.

In che ordine conviene collegare l'API?

1. 1Ricarica il saldo e crea una chiave API nella dashboard
2. 2Verifica chiave e collegamento con balance
3. 3Scarica l'elenco servizi con services e pubblicalo sul tuo pannello
4. 4Invia un add con la quantità minima e ricevi un numero d'ordine
5. 5Verifica con status che lo stato cambi, poi attiva gli ordini automatici

Esempi in curl, PHP, Python e Node.js e la descrizione completa dei campi sono nella documentazione API, e le altre domande sono nel gruppo API delle Domande frequenti.