Panoramica dell'API
L'API di Snapbyte è un'API REST che comunica in JSON su HTTPS. È pensata per i team che vogliono collegare Snapbyte ai propri sistemi — sincronizzare i menu, reagire agli ordini o estrarre dati in un altro strumento. Questa pagina copre le convenzioni che si applicano a ogni endpoint; i singoli endpoint sono documentati nelle loro pagine dedicate.
URL di base
https://api.snapbyte.app/api/v1
Il segmento v1 è la versione dell'API. Snapbyte non interromperà mai una
versione pubblicata; i nuovi comportamenti vengono rilasciati sotto un nuovo
prefisso di versione.
Autenticazione
Tutte le richieste devono includere un token bearer:
Authorization: Bearer sk_live_replace_me
Le chiavi sono associate a un ambiente (sandbox o production).
Struttura di richieste e risposte
- Tutti i corpi delle richieste sono in JSON. Imposta
Content-Type: application/json. - Tutte le risposte sono in JSON, anche in caso di errore.
- I timestamp sono stringhe ISO 8601 in UTC.
- Gli ID hanno un prefisso (ad esempio
job_01h...) così da essere autodescrittivi nei log.
Formato degli errori
Gli errori vengono restituiti con uno stato non-2xx e un corpo strutturato:
{
"error": {
"code": "invalid_request",
"message": "payload.message is required",
"param": "payload.message"
}
}
Il campo code è stabile e può essere usato in sicurezza per la logica
condizionale; message è destinato alle persone e può cambiare.
Limiti di frequenza
Snapbyte applica limiti di frequenza per chiave. Ogni risposta include:
| Header | Significato |
|---|---|
x-snapbyte-ratelimit | Richieste consentite nella finestra. |
x-snapbyte-remaining | Richieste rimanenti nella finestra. |
x-snapbyte-reset | Timestamp Unix di reimpostazione della finestra. |
In caso di 429, attendi fino al momento indicato da reset. L'SDK lo fa
automaticamente per te.
Paginazione
Gli endpoint di tipo elenco usano la paginazione a cursore:
GET /v1/jobs?limit=50&cursor=eyJ...
La risposta include un next_cursor (oppure null quando hai raggiunto la
fine). I cursori sono opachi — non cercare di analizzarli.
Dove andare ora
- Guide per procedure guidate dell'Admin Hub orientate alle attività.
- Risoluzione dei problemi per sapere cosa fare quando una richiesta fallisce.