L'API Grand Shooting è un'API REST che scambia JSON. Dà accesso agli stessi dati dell'applicazione: Catalogo, Produzioni, media, Specifiche, stock, diffusione.

• URL di base: https://api.grand-shooting.com/v3
• Formato: JSON (Content-Type: application/json), tranne l'upload di file (multipart/form-data)
• Riferimento completo: api.grand-shooting.com, specifica OpenAPI su /swagger.json

1. Ottenere un token API

Un token (chiamato "chiave API" nell'interfaccia) è collegato a un utente API del vostro account. Un amministratore dell'account lo crea nell'amministrazione dell'account, menu Team > API, con Aggiungi una chiave API.

Due livelli di diritti:

Diritto	Cosa permette
api	Lettura e scrittura
api_ro	Sola lettura: le richieste POST, PUT, PATCH e DELETE vengono rifiutate (401)

Scegliete api_ro quando l'integrazione si limita a leggere (reporting, sincronizzazione verso un DAM): in caso di fuga, il token non permette di modificare nulla.

Il token viene mostrato una sola volta, alla sua creazione: conservatelo in un archivio di segreti, mai nel codice. Non scade: resta valido finché l'utente API è attivo. Per revocarlo, bloccate la chiave in Team > API.

2. Prima chiamata

Il token si passa nell'intestazione Authorization, preceduto da Bearer:

curl -H "Authorization: Bearer $GS_TOKEN" https://api.grand-shooting.com/v3/account/me

/account/me descrive l'utente del token e gli account a cui ha accesso. Per ogni account, il campo api_host indica l'indirizzo dell'API da usare: la piattaforma è distribuita su più server, e un account può essere servito da un indirizzo diverso da api.grand-shooting.com (per esempio https://api-19.grand-shooting.com). Leggete api_host all'avvio della vostra integrazione invece di scrivere l'indirizzo nel codice.

3. Leggere i dati

Elencare le Produzioni dell'account:

curl -H "Authorization: Bearer $GS_TOKEN" https://api.grand-shooting.com/v3/production

Cercare i media approvati (picturestatus 50) modificati dal 1° ottobre, dai più recenti:

curl -i -H "Authorization: Bearer $GS_TOKEN" \
  "https://api.grand-shooting.com/v3/picture?picturestatus=50&date_mod=gte:2026-10-01&sort_by=-date_mod"

L'opzione -i mostra le intestazioni della risposta: X-Total-Count indica il numero totale di risultati. Paginazione, filtri e stati sono spiegati in Concetti dell'API.

4. Scrivere i dati

Creare o aggiornare una Referenza del Catalogo (la Referenza è identificata da ref: se esiste, viene aggiornata):

curl -X POST -H "Authorization: Bearer $GS_TOKEN" -H "Content-Type: application/json" \
  -d '{"ref":"SS26-ABITO-110","smalltext":"Abito bohémien"}' \
  https://api.grand-shooting.com/v3/reference

Caricare una foto nella fase Live di una Produzione:

curl -X POST -H "Authorization: Bearer $GS_TOKEN" -F "file=@photo.jpg" -F "path=/" \
  https://api.grand-shooting.com/v3/production/{bench_root_id}/bench/{bench_id}/upload

Oppure far caricare a Grand Shooting dei file a partire dai loro URL (fino a 200 per chiamata), associandoli direttamente a una Referenza:

curl -X POST -H "Authorization: Bearer $GS_TOKEN" -H "Content-Type: application/json" \
  -d '{"urls":[{"url":"https://cdn.example.com/a.jpg","filename":"a.jpg","ref":"SS26-ABITO-110"}]}' \
  https://api.grand-shooting.com/v3/production/{bench_root_id}/bench/{bench_id}/upload/url

5. Agire per conto di un altro account

Un fornitore (studio, produttore) lavora spesso per conto dei suoi clienti. Se il cliente gli ha concesso una delega, il suo token può agire sull'account del cliente: aggiungete l'intestazione account_id con l'identificativo dell'account di destinazione.

curl -H "Authorization: Bearer $GS_TOKEN" -H "account_id: 57" https://api.grand-shooting.com/v3/production

Senza questa intestazione, le richieste riguardano l'account del token. Gli account accessibili sono elencati da /account/me.

E poi?

• Concetti dell'API: oggetti, stati, paginazione, filtri, errori.
• Cookbook: le integrazioni comuni, passo dopo passo.
• Webhook: essere avvisati dei cambiamenti invece di interrogare l'API.