Il modello

Produzioni e fasi

Una Produzione è un insieme di media che segue un workflow. Ogni fase del workflow è un bench; i bench vengono creati con la Produzione, a partire dal suo template (/production/template).

Il campo benchsteptype indica il ruolo di ogni fase:

benchsteptype	Fase
10	Live (scatto)
20	Post-produzione, Fase 1
30	Post-produzione, Fase 2
40	Esportazioni / Validazione

Il Live e la fase Esportazioni / Validazione esistono sempre; la Post-produzione è facoltativa (zero, una o due fasi). Ogni account può rinominare le sue fasi: basatevi su benchsteptype, non sull'etichetta.

Una Produzione è identificata da bench_root_id, l'identificativo della sua prima fase; ogni fase ha il proprio bench_id. I media si caricano nelle fasi Live e Post-produzione. Non si carica mai un file nella fase 40: i media vi arrivano quando si avviano le esportazioni (POST /production/{bench_root_id}/export), e vi vengono poi sottoposti a validazione.

Lo stato della Produzione (benchstatus):

benchstatus	Significato
10	Attiva
20	In corso
30	Terminata
35	In archiviazione
40	Archiviata
50	Svuotata

Media

Un media (picture) è il file lavorato: foto, video, PDF e 3D condividono lo stesso oggetto. Porta la Referenza (ref), il Codice di vista (view_type_code), la fase in cui si trova (bench_id), i suoi tag (taginfo) e il suo picturestatus:

picturestatus	Significato	Fasi in cui si applica
1	Ignorato
5	Da riscattare	Live
10	Non selezionato	Live
30	Selezionato	Live, Post-produzione
35	Rifiutato da un ritoccatore	Post-produzione
31	Rifiutato in validazione	Validazione
40	Sottoposto a validazione	Validazione
50	Validato	Validazione
51	Pronto per la diffusione	Validazione (Diffusione)
52	Errore di diffusione	Validazione (Diffusione)
55	Diffuso	Validazione (Diffusione)
80	Archiviato	Validazione

Per recuperare il file: thumbnail fornisce una miniatura, GET /picture/{id}/download il file originale e POST /picture/{id}/publicurl un link temporaneo utilizzabile senza token (un'ora per impostazione predefinita, sette giorni al massimo), comodo per trasmetterlo a un sistema terzo.

Referenze e Specifiche

Una Referenza (reference) è un prodotto del Catalogo, identificato dal suo codice ref. POST /reference la crea o la aggiorna; POST /reference/bulk importa un lotto. Le Specifiche descrivono i media attesi: /specification/category (Codici di vista attesi per categoria prodotto) e /specification/format (dimensioni, risoluzione, profilo ICC, peso, formato di file).

Altre famiglie

Endpoint	Contenuto
/account/me	Utente, account accessibili, api_host di ogni account
/shootingmethod	Metodi di shooting
/shotlist	Shotlist
/stock, /stock/batch, /stock/zone	Logistica: Articoli, scaffali, zone
/broadcast	Diffusione dei media validati
/webhook	Abbonamenti ai webhook

L'elenco completo è su api.grand-shooting.com.

Le convenzioni

Paginazione

/picture e /reference restituiscono 100 elementi per pagina. La pagina successiva si richiede con l'intestazione offset (0, 100, 200…); la risposta indica il totale in X-Total-Count e la posizione in X-Offset e X-Count.

curl -i -H "Authorization: Bearer $GS_TOKEN" -H "offset: 100" \
  "https://api.grand-shooting.com/v3/picture?bench_root_id=1234"

offset è limitato a 10.000. Oltre, paginate con un cursore: ordinate sull'identificativo e ripartite dall'ultimo ricevuto.

curl -H "Authorization: Bearer $GS_TOKEN" \
  "https://api.grand-shooting.com/v3/picture?sort_by=picture_id&picture_id=gt:987654"

Filtri e ordinamento

Qualsiasi campo dell'oggetto può servire da filtro come parametro dell'URL:

Sintassi	Effetto
picturestatus=50	Uguaglianza
picturestatus=40&picturestatus=50	Campo ripetuto: OR
date_mod=gte:2026-10-01	Operatori gt:, gte:, lt:, lte: (due limiti sullo stesso campo si combinano in AND)
ref=null:true	Valore vuoto (null:false: valore compilato)
search=abito	Ricerca a testo libero
sort_by=-date_mod	Ordinamento decrescente (+ o niente: crescente)

Le date sono in formato ISO 8601 (2026-10-01T07:00:00.000Z).

Errori

L'API segue i codici HTTP standard. Gli errori hanno un corpo JSON:

{
  "code": 404,
  "error": "Not Found",
  "message": "Resource was not found"
}

I più frequenti: 400 (campo mancante o non valido, il messaggio indica quale), 401 (token assente o non valido, oppure scrittura con un token in sola lettura), 403 (azione non autorizzata per questo account), 429 (quota superata). Alcuni endpoint di massa rispondono 207 con il risultato di ogni elemento.

Quote

La quota è di 5 richieste al secondo per account, condivisa da tutti i token dell'account. Oltre, l'API risponde 429. Le intestazioni X-RateLimit-UserLimit, X-RateLimit-UserRemaining e X-RateLimit-UserReset permettono di rallentare prima di essere bloccati. Preferite gli endpoint di massa (/reference/bulk, /upload/url, POST /picture/picturestatus) ai cicli di chiamate unitarie, e i webhook alle interrogazioni ripetute.