Crea bot, overlay, strumenti di streaming e integrazioni con i dati D1Arena.
Autenticazione
Tutte le richieste API richiedono una chiave API passata nell'intestazione X-API-Key / Authorization: Bearer.
Per creare una chiave API, vai su Impostazioni sviluppatore nella tua dashboard. Puoi avere fino a 5 chiavi.
429 Too Many Requests con un'intestazione Retry-After.
URL di base
Tutti gli endpoint restituiscono JSON. Gli endpoint impaginati includono un oggetto meta con current_page, last_page e total.
Flussi
| Parametro | Tipo | Descrizione |
|---|---|---|
category_id | integer | Filtra per ID gioco/categoria |
limit | integer | Risultati per pagina (predefinito: 20) |
page | integer | Numero di pagina |
Categorie
| Parametro | Tipo | Descrizione |
|---|---|---|
search | string | Filtra le categorie per nome |
limit | integer | Risultati per pagina (impostazione predefinita: 50) |
Utenti
Clip
| Parametro | Tipo | Descrizione |
|---|---|---|
streamer_id | integer | Filtra le clip in base all'ID utente dello streamer |
category_id | integer | Filtra per ID gioco/categoria |
limit | integer | Risultati per pagina (predefinito: 20) |
Tornei
| Parametro | Tipo | Descrizione |
|---|---|---|
status | string | Filtra per stato (ad es. open, in_progress, completed) |
league_id | integer | Filtra per ID campionato |
limit | integer | Risultati per pagina (predefinito: 20) |
Classifiche ELO
| Parametro | Tipo | Descrizione |
|---|---|---|
category_id | integer | Filtra per ID gioco/categoria |
limit | integer | Numero di risultati (predefinito: 50) |
Leghe
| Parametro | Tipo | Descrizione |
|---|---|---|
status | string | Filtra per stato del campionato |
category_id | integer | Filtra per ID gioco/categoria |
limit | integer | Risultati per pagina (predefinito: 20) |
Risposte agli errori
Tutti gli errori restituiscono una busta JSON coerente. L'oggetto error contiene sempre un code leggibile dalla macchina e un message leggibile dall'uomo.
Codici di stato
Riferimento ai codici di errore
| Codice | Stato HTTP | Descrizione |
|---|---|---|
invalid_api_key | 401 | La chiave API è mancante, non valida o non esiste |
api_key_disabled | 403 | La chiave API è stata revocata o disabilitata |
not_found | 404 | Impossibile trovare la risorsa richiesta |
validation_error | 422 | Uno o più parametri della richiesta non sono validi |
rate_limited | 429 | È stato superato il limite di frequenza delle richieste per questa chiave API |
server_error | 500 | Errore interno del server: riprova o contatta l'assistenza |
Limiti di velocità
Le richieste API hanno una velocità limitata per chiave API. Quando superi il limite, le richieste restituiscono 429 Too Many Requests con un'intestazione Retry-After.
Limiti per livello
| Livello | Richieste/Minuto (Predefinito) | Chiavi massime |
|---|---|---|
| Antipasto (Gratuito) | 60 | 5 |
| PRO | 60 | 5 |
| Definitivo | 60 | 5 |
| Partner | 60 | 5 |
Intestazioni dei limiti di velocità
Le richieste API hanno una velocità limitata per chiave API. Quando superi il limite, le richieste restituiscono 429 Too Many Requests con un'intestazione Retry-After.
| Intestazione | Descrizione |
|---|---|
Retry-After | Secondi di attesa prima di riprovare (presente solo su 429 risposte) |
Migliori pratiche
- Cache responses locally — stream and tournament data doesn't change every second.
- Iscriviti a webhooks per eventi in tempo reale invece di eseguire il polling degli endpoint.
- Richieste batch ove possibile: utilizza i parametri di filtro per ottenere esattamente ciò di cui hai bisogno con meno chiamate.
Webhook (EventSub)
Iscriviti alle notifiche push in tempo reale invece dei sondaggi. Quando si verifica un evento, D1Arena invia un POST HTTP al tuo URL di richiamata con un payload JSON firmato con HMAC-SHA256.
Impostare
Crea sottoscrizioni webhook in Impostazioni sviluppatore. Ogni abbonamento richiede:
- URL di richiamata — Un endpoint HTTPS accessibile pubblicamente sul tuo server.
- Eventi — Uno o più tipi di eventi a cui iscriversi.
You'll receive a whsec_ signing secret upon creation. Store it securely — it's shown only once.
Formato del carico utile
Ogni consegna del webhook invia un corpo JSON con questa struttura:
Intestazioni
Ogni consegna include le seguenti intestazioni per l'instradamento e la verifica:
| Intestazione | Descrizione |
|---|---|
Content-Type | application/json |
X-D1Arena-Event | Tipo di evento (ad esempio stream.online) |
X-D1Arena-Signature | Digest esadecimale HMAC-SHA256 del corpo della richiesta non elaborata |
X-D1Arena-Signature-Version | Formato della chiave di firma: v2 per gli abbonamenti attuali o v1-hashed-secret per gli abbonamenti legacy |
X-D1Arena-Delivery-Id | UUID di consegna univoco: da utilizzare per la deduplicazione |
X-D1Arena-Timestamp | Timestamp Unix di quando è stato inviato l'evento |
Verifica delle firme
Verifica sempre l'intestazione X-D1Arena-Signature prima di elaborare un webhook. La firma viene calcolata come HMAC-SHA256(raw_body, webhook_secret).
Per le consegne v2, utilizza il segreto whsec_ mostrato al momento della creazione dell'abbonamento. Per una consegna pre-aggiornamento v1-hashed-secret, calcola prima SHA256(whsec_secret) da quel segreto originale e utilizza il digest esadecimale minuscolo risultante come chiave HMAC. Ricrea l'abbonamento quando possibile per passare a v2.
Eventi disponibili
| Evento | Descrizione |
|---|---|
| stream.online | Uno streamer è andato in diretta |
| stream.offline | Uno streamer è andato offline |
| channel.follow | Un utente ha seguito un canale |
| channel.subscribe | Nuova iscrizione come sostenitore su un canale |
| channel.tip | È stato inviato un suggerimento a uno streamer |
| tournament.started | È iniziato un match play del torneo |
| tournament.ended | Un torneo si è concluso |
| tournament.match.completed | È stato registrato il risultato di una partita |
| clip.created | È stata creata una nuova clip da un live streaming |
| overdrive.started | D1 Frenzy è iniziato su un canale |
| overdrive.level_up | D1 Frenzy è avanzato al livello successivo |
| overdrive.ended | D1 Frenesia completata o scaduta |
Esempi di payload di eventi
stream.online
stream.offline
channel.follow
channel.tip
tournament.match.completed
clip.created
Politica di consegna e nuovo tentativo
| Tentativo | Ritardo | Note |
|---|---|---|
| 1° (iniziale) | Immediato | Inviato entro pochi secondi dall'evento |
| 2° (riprova) | 30 secondi | Se il primo tentativo fallisce o scade |
| 3° (riprova) | 2 minuti | Backoff esponenziale |
| 4° (finale) | 10 minuti | Ultimo tentativo prima di essere contrassegnato come fallito |
2xx status within 10 secondi. Non-2xx responses or timeouts trigger a retry. After 10 fallimenti consecutivi, the subscription is automatically disabled. You'll receive an email notification and can re-enable it in Impostazioni sviluppatore.
Migliori pratiche
- Verifica sempre le firme prima di elaborare i payload per prevenire eventi di spoofing.
- Utilizzare il Delivery-Id per la deduplicazione — i tentativi inviano lo stesso ID, quindi archivia gli ID elaborati per evitare la doppia elaborazione.
- Rispondi rapidamente, elabora in modo asincrono — restituisci immediatamente
200 OKe gestisci la logica aziendale in un lavoro in background. - Utilizza solo endpoint HTTPS — Gli URL webhook devono utilizzare TLS. Le richiamate HTTP vengono rifiutate.
- Gestisci gli eventi sconosciuti con garbo — potrebbero essere aggiunti nuovi tipi di eventi. Restituisce
200per eventi non riconosciuti invece che per errori.
D1 Frenesia
D1 Frenzy viene attivato da suggerimenti rapidi e abbonamenti mentre uno streamer è in diretta. Progredisce attraverso 5 livelli con obiettivi crescenti.
GET /api/overdrive/{streamerId}
Ottieni il D1 Frenzy attivo per uno streamer. Restituisce {"active": false} se nessuno.
Obiettivi di livello
| Livello | Punti |
|---|---|
| 1 | 100 |
| 2 | 250 |
| 3 | 500 |
| 4 | 1,000 |
| 5 | 2,000 |
D1 Frenesia — Punti: Suggerimento $1 → 100; Abbonamento 500 × Livello. Durata: 5 Minuti; Raffreddamento: 30 Minuti.
SDK di estensione
Crea pannelli personalizzati ed estensioni sovrapposte che gli streamer possono installare sulle loro pagine canale. Le estensioni vengono eseguite in iframe sandbox e comunicano con la pagina host tramite postMessage.
Come iniziare
- Crea una chiave API in Impostazioni sviluppatore.
- Crea la tua estensione come pagina HTML autonoma ospitata sul tuo dominio (è richiesto HTTPS).
- Invialo per la revisione nella sezione Le mie estensioni.
- Una volta approvato, gli streamer possono installarlo dal Marketplace delle estensioni.
Tipi di estensione
| Tipo | Posizione | Comportamento |
|---|---|---|
panel | Sotto lo stream player | Visibile quando lo streaming è live. Scheda a larghezza intera, altezza predefinita 300 px. |
overlay | Sul lettore video | Visibile in diretta. Posizione/dimensione controllata dallo streamer tramite lo strumento di posizionamento sovrapposto. |
API postMessage
La tua estensione riceve automaticamente i dati contestuali quando viene caricata. Implementa questi eventi:
Utilizza l'esatta origine principale D1Arena per ogni messaggio. Il SDK ufficiale deriva e convalida automaticamente questa origine dalla pagina di incorporamento.
Poiché gli iframe di estensione utilizzano intenzionalmente un'origine sandbox opaca, l'host D1Arena autentica l'esatta finestra iframe registrata. Il codice dell'estensione deve comunque autenticare la finestra principale e l'esatta origine D1Arena prima di accettare il contesto.
1. Prontezza del segnale
2. Ricevi il contesto
3. Invia azioni (facoltativo)
Ambiti di autorizzazione
Dichiara di quali dati ha bisogno la tua estensione. I revisori verificano che il tuo codice corrisponda alle autorizzazioni dichiarate.
| Ambito | Concede l'accesso a |
|---|---|
read:stream | Stato dello streaming, titolo, categoria |
read:viewers | Conteggio ed elenco degli spettatori |
read:chat | Messaggi di chat (tramite canale Pusher) |
read:clips | Clip del canale tramite /api/clips/{slug} |
read:tournaments | Informazioni sulla partita attiva tramite /api/active-match/{id} |
read:channel | Profilo del canale, follower, pianificazione |
Requisiti di sicurezza
sandbox="allow-scripts". La tua estensione non può accede ai cookie, localStorage o effettua richieste autenticate a d1arena.com.
- Pubblico HTTPS obbligatorio — L'URL iframe deve utilizzare TLS e risolvere solo indirizzi di rete pubblici.
- Fonte leggibile dall'uomo — Nessun JavaScript offuscato o minimizzato. I revisori devono essere in grado di leggere il tuo codice.
- Nessun caricamento di script esterno a meno che non sia dichiarato nella tua presentazione. Le librerie CDN (jQuery, Chart.js, ecc.) Vanno bene.
- Nessuna esfiltrazione di dati — Le estensioni non devono inviare dati sui visualizzatori a servizi di analisi o di monitoraggio di terze parti.
- Politica sui contenuti — Nessuna pubblicità, contenuto NSFW, mining di criptovaluta o comportamento dannoso.
Processo di revisione
| Stato | Significato |
|---|---|
| pending | Inviato, in attesa di revisione da parte dell'amministratore (in genere 1-3 giorni lavorativi). |
| approved | Approvato e visibile nel Marketplace delle estensioni. |
| rejected | Rifiutato con motivazione. Risolvi i problemi e invia nuovamente. |
| suspended | Rimosso temporaneamente per violazione delle norme. Contatta l'assistenza. |
Aggiornamenti della versione
Per aggiornare un'estensione approvata, elimina la versione corrente e inviane una nuova con un numero di versione incrementato. La nuova versione viene nuovamente sottoposta a revisione.
Registro delle modifiche
Tieni traccia delle modifiche API e delle nuove funzionalità. Seguiamo il controllo delle versioni semantico e annunciamo le modifiche sostanziali con almeno 30 giorni di anticipo.
- Rilascio iniziale dell'API pubblica con autenticazione della chiave API.
- Streaming: elenca gli streaming live, ottieni i dettagli dello streamer tramite slug.
- Categorie: cerca ed elenca tutte le categorie di giochi.
- Utenti: profili pubblici con statistiche competitive, valutazione ELO e conteggio delle medaglie.
- Clip: sfoglia e recupera i dettagli dei clip con le informazioni dello streamer/creatore.
- Tornei: elenca, filtra per stato/campionato, ottieni il conteggio dei partecipanti.
- Classifica ELO: classifiche globali e per categoria.
- Legati: elenca i campionati con classifiche e suddivisione dei punti.
- D1 Frenzy: stato Frenzy in tempo reale per qualsiasi streamer.
- Webhook (EventSub): 12 tipi di eventi tra cui streaming, canali, tornei, clip e eventi Frenzy.
- Limiti di velocità
Hai bisogno di aiuto?
Domande sul API? Contattaci.