Le modèle de données (Productions, étapes, médias, Références), les statuts, et les conventions communes à tous les endpoints : pagination, filtres, erreurs, quotas.
Une Production est un lot de médias qui suit un workflow. Chaque étape du workflow est un bench ; les benches sont créés avec la Production, à partir de son template (/production/template).
Le champ benchsteptype indique le rôle de chaque étape :
benchsteptype | Étape |
|---|---|
| 10 | Live (prise de vue) |
| 20 | Post-production, Phase 1 |
| 30 | Post-production, Phase 2 |
| 40 | Exports / Validation |
Le Live et l'étape Exports / Validation existent toujours ; la Post-production est facultative (zéro, une ou deux phases). Chaque compte peut renommer ses étapes : fiez-vous à benchsteptype, pas au libellé.
Une Production est identifiée par bench_root_id, l'identifiant de sa première étape ; chaque étape a son propre bench_id. Les médias se chargent sur les étapes Live et Post-production. On ne charge jamais de fichier sur l'étape 40 : les médias y arrivent quand on déclenche les exports (POST /production/{bench_root_id}/export), puis y sont soumis à validation.
Le statut de la Production (benchstatus) :
benchstatus | Signification |
|---|---|
| 10 | Active |
| 20 | En cours |
| 30 | Terminée |
| 35 | En cours d'archivage |
| 40 | Archivée |
| 50 | Purgée |
Un média (picture) est le fichier travaillé : photo, vidéo, PDF ou 3D partagent le même objet. Il porte la Référence (ref), le Code de vue (view_type_code), l'étape où il se trouve (bench_id), ses tags (taginfo) et son statut picturestatus :
picturestatus | Signification | Étapes où il s'applique |
|---|---|---|
| 1 | Ignoré | |
| 5 | À reshooter | Live |
| 10 | Non sélectionné | Live |
| 30 | Sélectionné | Live, Post-production |
| 35 | Refusé par un retoucheur | Post-production |
| 31 | Refusé à la validation | Validation |
| 40 | Soumis à validation | Validation |
| 50 | Validé | Validation |
| 51 | Prêt à diffuser | Validation (Diffusion) |
| 52 | Erreur de diffusion | Validation (Diffusion) |
| 55 | Diffusé | Validation (Diffusion) |
| 80 | Archivé | Validation |
Pour récupérer le fichier : thumbnail donne une vignette, GET /picture/{id}/download le fichier original, et POST /picture/{id}/publicurl un lien temporaire utilisable sans jeton (une heure par défaut, sept jours au plus), pratique pour le transmettre à un système tiers.
Une Référence (reference) est un produit du Catalogue, identifiée par son code ref. POST /reference la crée ou la met à jour ; POST /reference/bulk importe un lot. Le Cahier des charges décrit les médias attendus : /specification/category (Codes de vue attendus par catégorie de produits) et /specification/format (dimensions, résolution, profil ICC, poids, format de fichier).
| Endpoint | Contenu |
|---|---|
/account/me | Utilisateur, comptes accessibles, api_host de chaque compte |
/shootingmethod | Méthodes de shooting |
/shotlist | Shotlists |
/stock, /stock/batch, /stock/zone | Logistique : Articles, rayons, zones |
/broadcast | Diffusion des médias validés |
/webhook | Abonnements aux webhooks |
La liste complète est sur api.grand-shooting.com.
/picture et /reference renvoient 100 éléments par page. La page suivante se demande avec l'en-tête offset (0, 100, 200…) ; la réponse indique le total dans X-Total-Count, et la position dans X-Offset et X-Count.
curl -i -H "Authorization: Bearer $GS_TOKEN" -H "offset: 100" \
"https://api.grand-shooting.com/v3/picture?bench_root_id=1234"offset est limité à 10 000. Au-delà, paginez par curseur : triez sur l'identifiant et repartez du dernier reçu.
curl -H "Authorization: Bearer $GS_TOKEN" \
"https://api.grand-shooting.com/v3/picture?sort_by=picture_id&picture_id=gt:987654"Tout champ de l'objet peut servir de filtre en paramètre d'URL :
| Syntaxe | Effet |
|---|---|
picturestatus=50 | Égalité |
picturestatus=40&picturestatus=50 | Champ répété : OU |
date_mod=gte:2026-10-01 | Opérateurs gt:, gte:, lt:, lte: (deux bornes sur le même champ se combinent en ET) |
ref=null:true | Valeur vide (null:false : valeur renseignée) |
search=robe | Recherche plein texte |
sort_by=-date_mod | Tri décroissant (+ ou rien : croissant) |
Les dates sont au format ISO 8601 (2026-10-01T07:00:00.000Z).
L'API suit les codes HTTP standard. Les erreurs ont un corps JSON :
{
"code": 404,
"error": "Not Found",
"message": "Resource was not found"
}Les plus fréquentes : 400 (champ manquant ou invalide, le message dit lequel), 401 (jeton absent ou invalide, ou écriture avec un jeton en lecture seule), 403 (action non autorisée pour ce compte), 429 (quota dépassé). Certains endpoints de masse répondent 207 avec le résultat de chaque élément.
Le quota est de 5 requêtes par seconde par compte, partagé par tous les jetons du compte. Au-delà, l'API répond 429. Les en-têtes X-RateLimit-UserLimit, X-RateLimit-UserRemaining et X-RateLimit-UserReset permettent de ralentir avant d'être bloqué. Préférez les endpoints de masse (/reference/bulk, /upload/url, POST /picture/picturestatus) aux boucles d'appels unitaires, et les webhooks à l'interrogation répétée.
Les endpoints n'ont pas de clé d'idempotence. POST /reference est un upsert sur ref : le rejouer ne crée pas de doublon. Pour les uploads, vérifiez la réponse de chaque fichier avant de relancer.