Espace Attraction pour développeurs

Attraction publie une API produits publique en lecture seule ainsi que des miroirs Markdown de ce site, pour que les personnes et les agents IA puissent intégrer des données produit à jour et le contexte de l'entreprise dans leurs propres outils. Cette page est le point de départ; la référence API complète couvre chaque point d'accès, paramètre et champ de réponse.

Commencer

GET /v1/products?locale=fr-CA

curl "https://api.attraction.com/v1/products?locale=fr-CA"

Référence complète des points d'accès : attraction.com/api/
Description OpenAPI : api.attraction.com/openapi.json
Aucune clé API n'est requise pour les données produit publiques.

Authentification

Les données produit publiques ne demandent ni clé ni compte connecté — listes de produits, détail, couleurs, tailles, inventaire en temps réel, prix de détail suggéré, images et compatibilité de décoration sont toutes en lecture libre.

La lecture des prix nets de votre compte passe par une clé API, créée sur la page des clés API et envoyée dans un en-tête Authorization: Bearer. Elle fonctionne sur trois routes :

GET /v1/products/{sku} — porte pricing.net à côté du prix de détail suggéré.
GET /v1/products/{sku}/pricing — les prix d'un seul produit.
GET /v1/products/pricing — les prix de tous les produits en une réponse, pour remettre à jour un catalogue stocké.

La liste de produits, /v1/products, reste au prix de détail suggéré dans tous les cas. Aucune des deux routes de prix n'a de repli anonyme : en appeler une sans authentification retourne 401 key_required.

Un compte Studio Attraction associé à des prix de distributeur est nécessaire pour créer une clé. Tout le monde peut créer un compte sur studio.attraction.com : s'il est déjà rattaché à un distributeur Attraction, le palier de prix s'applique aussitôt et les clés se créent tout de suite; sinon, la demande passe à notre équipe, et l'accès à Studio comme la création de clés s'ouvrent dès son acceptation.

Une clé lit les prix du compte qui l'a créée, et d'aucun autre. Chaque réponse authentifiée renvoie pricing.priceTier, le palier qui a établi ces prix. La clé suit le palier en vigueur du compte, donc s'il change, elle continue de fonctionner et retourne simplement les nouveaux prix.

Les clés n'expirent jamais et se révoquent en tout temps; un compte en détient au plus 10 actives. Une clé malformée ou inconnue reçoit 401 invalid_key; une clé révoquée, ou dont le compte n'a plus de prix distributeur, reçoit 401 key_revoked. Aucune ne retombe sur le prix de détail suggéré : mieux vaut refuser la requête que de servir un mauvais prix.

GET /v1/products/{sku}/pricing

curl -H "Authorization: Bearer $ATTRACTION_API_KEY" \
  "https://api.attraction.com/v1/products/100386U/pricing?locale=fr-CA"

Limites de débit

Chaque réponse de /v1/products et /v1/products/{sku} porte des en-têtes de limite de débit pour une politique nommée default : 600 requêtes par minute par IP cliente. Une requête portant une clé API est plutôt comptée par clé, sous keyed : 1200 requêtes par minute. Ces chiffres sont indicatifs et suivis par instance de l'API, pas par un compteur global — pas une garantie de dimensionnement pour une intégration. L'infrastructure applique aussi un plafond strict de 100 requêtes par seconde (rafale de 200), peu importe le compteur indicatif. Ces en-têtes suivent draft-ietf-httpapi-ratelimit-headers; une requête au-delà de la limite reçoit 429 avec Retry-After et une erreur rate_limited, qui doit toujours être respecté.

RateLimit-Policy: "default";q=600;w=60
RateLimit-Policy: "keyed";q=1200;w=60 (requêtes authentifiées par clé API)
RateLimit: "default";r=<remaining>;t=<seconds>

Les points d'accès de catalogue servent aussi le gzip : quand Accept-Encoding: gzip est envoyé, la liste de produits d'environ 274 Ko se compresse à environ 24 Ko.

Versions et dépréciation

L'API est versionnée dans l'URL : les points d'accès actuels sont sous /v1. Les changements non rétrocompatibles sont publiés sous /v2 plutôt que de modifier /v1 en place; les changements additifs, comme un nouveau champ ou un nouveau paramètre optionnel, ne changent jamais la version.

Quand une version est dépréciée, l'annonce se fait au moins trois mois à l'avance, et chaque réponse porte un en-tête Deprecation (RFC 9745) et un en-tête Sunset (RFC 8594) indiquant la date de retrait.

Erreurs

Les erreurs sont des objets problem+json conformes à la RFC 9457, servis en application/problem+json :

product_not_found — 404

{
  "type": "https://www.attraction.com/developers/#error-product_not_found",
  "title": "Product not found",
  "status": 404,
  "detail": "No product matches SKU NOPE-NOT-A-SKU.",
  "instance": "/v1/products/nope-not-a-sku",
  "code": "product_not_found"
}

Chaque code ci-dessous a sa propre URI type sur cette page : https://www.attraction.com/developers/#error-<code>.

route_not_found — 404

Aucune route ne correspond au chemin demandé.

method_not_allowed — 405

La route existe mais pas pour cette méthode HTTP. La réponse porte Allow: GET, HEAD, OPTIONS.

invalid_request — 400

La requête ne correspond pas à ce qu'attend la route, par exemple un paramètre de requête malformé.

unsupported_locale — 400

locale doit être en-CA, en-US ou fr-CA.

invalid_sku — 400

Le paramètre de chemin sku n'est pas un SKU valide.

unauthorized — 401

Réservé aux routes privées /v1/sync/*; les points d'accès produits publics ne retournent jamais cette erreur.

key_required — 401

GET /v1/products/{sku}/pricing a été appelé sans authentification. Cette route tarife un compte précis; elle n'a donc aucun repli public, contrairement aux points d'accès produits, qui répondent anonymement avec le prix de détail suggéré. La réponse porte WWW-Authenticate: Bearer realm="api.attraction.com", sans paramètre error : rien n'a été présenté à rejeter.

invalid_key — 401

L'en-tête Authorization: Bearer porte une clé que l'API ne reconnaît pas. Le champ detail précise laquelle : non reconnue (souvent copiée de façon incomplète), ou malformée, c'est-à-dire qu'elle ne respecte pas la forme attr_sk_<16 caractères hexadécimaux>_<43 caractères>. Dans les deux cas, créez-en une nouvelle sur la page des clés API. La réponse porte WWW-Authenticate: Bearer realm="api.attraction.com", error="invalid_token". Une requête sans aucune authentification n'est pas une erreur : elle lit simplement les données publiques.

key_revoked — 401

La clé API n'est plus active : elle a été révoquée, ou le compte derrière elle n'a plus de prix distributeur (fermé, désactivé, ou sans palier de prix). La clé et le compte peuvent être vérifiés sur la page des clés API. Un changement de palier ne cause jamais cette erreur — une clé suit le palier en vigueur de son compte.

product_not_found — 404

Aucun produit ne correspond au SKU fourni.

rate_limited — 429

Le client dépasse la politique de limite de débit. La réponse porte Retry-After et les en-têtes RateLimit/RateLimit-Policy.

upstream_unavailable — 503

La source du catalogue est temporairement inaccessible. La réponse porte Retry-After: 30.

internal_error — 500

Une erreur serveur inattendue, sans trace d'exécution ni détail interne dans la réponse.

Ressources pour agents

Envoyer Accept: text/markdown à n'importe quelle URL de page, ou ajouter .md (par exemple attraction.com/products.md) retourne une copie Markdown de cette page.
llms.txt et llms-full.txt indexent le site pour les modèles de langage et les agents.
.well-known/api-catalog liste les points d'entrée machine-lisibles de l'API (RFC 9727).
.well-known/agent-skills/index.json publie les Agent Skills pour l'API produits et les pages Markdown du site.

Statut et soutien

/v1/health indique le statut de l'API. Pour toute autre question, écrivez-nous à service@attraction.com.

Journal des changements

2026-08-31 — Prix nets via l'API : une clé API de compte, créée et révoquée sur la page des clés API, ajoute les prix nets de votre compte à /v1/products/{sku} et à deux nouveaux points d'accès de prix — /v1/products/{sku}/pricing (un produit) et /v1/products/pricing (tout le catalogue). Les clés sont des jetons Bearer qui suivent le palier de prix en vigueur du compte, et apportent les codes d'erreur invalid_key et key_revoked ainsi que la politique de limite de débit keyed.
2026-08-31 — Matériaux par couleur : les couleurs du détail produit portent maintenant material (la composition, un libellé weight formaté selon la locale, le gsm numérique et, pour les produits Jameo, le name du tissu). L'ancien tableau materials du produit et la chaîne weight par couleur sont retirés.
2026-08-25 — Fraîcheur des produits : chaque produit rapporte maintenant updatedAt, mis à jour seulement quand son contenu de catalogue change réellement (les mouvements d'inventaire n'y jouent pas), et la liste rapporte catalogUpdatedAt quand un produit s'ajoute ou se retire.
2026-08-24 — Publication de cet espace développeurs. Les réponses d'erreur passent au format application/problem+json de la RFC 9457; ajout des en-têtes de limite de débit et d'une politique de versions et de dépréciation.
2026-06-26 — Lancement officiel : l'API produits publique en lecture seule sur api.attraction.com (liste et détail sous /v1, sans clé) avec sa description OpenAPI et sa documentation interactive.