API pubbliche

1. Ambito di utilizzo dell’API

a. Funzioni supportate tramite API

L’API pubblica consente di interagire con le funzioni principali dell’app Wholesale, tra cui:

• Funzioni di base: Wholesale Pricing, Volume Pricing, Registration form, Quick Order Form, Quick Buy Collection, Quick Buy Variant
• Funzioni aggiuntive: Order Limit, Shipping Rate, Extra Fee, Payment Term (in arrivo)

b. Metodi supportati

L’API supporta tutte le operazioni CRUD con i seguenti metodi HTTP:

• GET – Recupera i dati
• POST – Crea nuovi dati
• PUT – Aggiorna i dati esistenti
• DELETE – Rimuove i dati

Alle chiavi API possono essere concessi i seguenti livelli di autorizzazione: Read Only/Write Only, Read & Write

Azioni supportate: Get list - Get item - Create item - Update item - Delete item

c. Piani Shopify supportati:

L’API pubblica dell’applicazione Wholesale è disponibile per i negozi Shopify che soddisfano i seguenti requisiti:

• Deve essere un negozio di produzione (non valido per i negozi di sviluppo o di prova)
• Deve avere un abbonamento al piano Gold

---

2. Autenticazione

Tutte le richieste API devono essere autenticate correttamente prima di essere elaborate.

a. Parametri obbligatori

Ogni richiesta API deve includere i seguenti parametri obbligatori:

Parametro	Descrizione
shop	Dominio del negozio Shopify (ad es. mystore.myshopify.com)
api_key	Chiave API generata dall’app Wholesale

Se manca uno di questi parametri, la richiesta viene rifiutata.

b. Gestione delle chiavi API

Le chiavi API vengono create e gestite direttamente nell’interfaccia di amministrazione dell’app Wholesale.
Chi gestisce il negozio può configurare autorizzazioni specifiche per ogni chiave API: Read only/Write only, Read & Write

---

3. Struttura dell’API e formato della risposta

a. Endpoint dell’API

Tutte le richieste API devono usare il seguente URL di base:

https://wholesale.samita.io/v1/

b. Endpoint specifici per funzione

Ogni gruppo di funzioni ha un proprio endpoint specifico. Ad esempio:

• Funzione Wholesale:

  https://wholesale.samita.io/v1/wholesale/

• Funzione Volume Pricing:

  https://wholesale.samita.io/v1/volume/

(Gli endpoint effettivi possono variare in base alla funzionalità specifica.)

c. Parametri di query supportati

L’API supporta diversi parametri di query comuni:

Parametro	Descrizione
status	Stato dei record
page	Numero di pagina per la paginazione
limit	Numero di record per pagina
sort	Criteri di ordinamento
query	Condizione di ricerca o filtro

Esempio di richiesta:

GET /wholesale?page=1&limit=20&sort=created_at

---

4. Codici di risposta

Ogni richiesta API restituisce uno dei seguenti codici di stato:

a. Risposte di errore comuni

401 – Unauthorized

Possibili motivi:

• URL del negozio mancante
• Chiave API mancante
• URL del negozio non valido
• Chiave API non valida
• La chiave API non corrisponde al negozio

---

403 – This action is unauthorized

• La chiave API non ha l’autorizzazione per eseguire l’azione richiesta
• Autorizzazioni View / Create / Update / Delete insufficienti

---

429 – Too Many Requests

• Limite di richieste superato
• La frequenza delle chiamate API supera il limite consentito

---

b. Risposta di successo

200 – Success

• La richiesta è valida
• L’azione API è stata eseguita correttamente
• I dati vengono restituiti nel formato corretto

---

5. Limite di frequenza

Per garantire prestazioni e stabilità del sistema, l’uso dell’API è soggetto a un limite giornaliero di richieste. Non esiste più alcun limite per singola richiesta o per brevi intervalli: puoi chiamare l’API tutte le volte che vuoi, purché resti entro la quota giornaliera del tuo piano.

Il limite giornaliero dipende dal piano tariffario del negozio:

Piano	Limite giornaliero di richieste
Free	5 richieste al giorno
Starter	50 richieste al giorno
Growth	250 richieste al giorno
Enterprise	500 richieste al giorno

Il contatore giornaliero si azzera ogni giorno a mezzanotte (ora del server).

Se il limite giornaliero viene superato, il sistema restituisce:

429 – Too Many Requests

{
  "message": "Daily request limit exceeded (X requests/day)."
}