Passa al contenuto principale

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:

HeaderSignificato
x-snapbyte-ratelimitRichieste consentite nella finestra.
x-snapbyte-remainingRichieste rimanenti nella finestra.
x-snapbyte-resetTimestamp 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.