Store Platforms

Intégration de l’API Squarespace : clés, OAuth et webhooks

Intégration de l’API Squarespace : clé API ou OAuth, renouvellement des tokens, limite de 300 requêtes/min, webhooks et code fonctionnel.

Photo de profil de Long Nguyen

Long Nguyen

Développeur fullstack · Ingénieur IA · Chercheur

• • 4 min de lecture •

Ce qu’une intégration de l’API Squarespace permet réellement

Une intégration de l’API Squarespace relie vos logiciels à un site marchand via les Commerce APIs de Squarespace : des endpoints REST accessibles en HTTPS depuis api.squarespace.com, qui renvoient exclusivement du JSON et s’authentifient avec une clé API ou un token d’accès OAuth 2.0. Elles couvrent la partie e-commerce d’un site (produits, commandes, stocks, contacts, remises et transactions) et peuvent transmettre à votre serveur les événements liés aux commandes et aux contacts par webhook.

Le modèle mental le plus pratique consiste à voir une API par objet métier, avec son propre niveau d’autorisation :

API Fonction Point d’attention
Orders Lire les commandes ponctuelles et les abonnements, importer des commandes provenant d’autres canaux de vente, marquer les commandes comme expédiées et déclencher les notifications d’expédition Les dons ne sont pas inclus ; utilisez Transactions
Products Créer, modifier et supprimer des produits, des variantes et des images La version v2 est actuelle ; v1.0 et v1.1 sont obsolètes
Inventory Lire et ajuster les stocks des variantes de produits Autorisation distincte de celle de Products
Contacts Gérer les clients, abonnés et donateurs, les carnets d’adresses et les préférences marketing Remplace Profiles API pour les nouveaux projets
Discounts Gérer les codes de réduction, les conditions d’éligibilité et les montants Les accès en lecture et en écriture correspondent à des scopes distincts
Transactions Gérer les transactions financières liées aux commandes et aux dons Lecture seule
Webhook Subscriptions Abonner votre endpoint aux événements du site OAuth uniquement ; les clés API sont refusées

Deux détails permettent d’éviter du travail inutile. Profiles API est en mode maintenance : tout nouveau projet devrait donc utiliser Contacts. Par ailleurs, comme Orders API n’inclut pas les dons, une intégration de reporting ou de comptabilité qui doit enregistrer chaque paiement a également besoin de Transactions API.

Clé API Squarespace ou OAuth : faites le choix avant de coder

C’est la décision qui conditionne tout le reste, car elle détermine si vous pouvez utiliser des webhooks, quelles limites de débit s’appliquent et comment stocker vos identifiants.

  Clé API OAuth 2.0
Prévue pour Une application personnalisée sur un seul site marchand Des applications commerciales et des Extensions utilisées par plusieurs sites
Condition Le site doit disposer de l’offre Commerce Advanced Votre application doit être enregistrée auprès de Squarespace comme client OAuth
Obtenir l’accès Générer une clé dans les paramètres du site Le propriétaire du site autorise votre application sur une page de confirmation Squarespace
Durée de validité N’expire pas tant que le site reste actif Token d’accès : 30 minutes ; token de renouvellement : 7 jours
Autorisations Lecture seule ou lecture et écriture par API, définies lors de la création Scopes tels que website.orders, demandés à chaque autorisation
Webhooks Non pris en charge Pris en charge
Limite de création de commande 100 requêtes par heure et par site Cette limite ne s’applique pas

Ma règle générale : si l’intégration sert plusieurs marchands, vous devez utiliser OAuth. Si elle concerne exactement une boutique que vous contrôlez ou gérez, la clé API est la solution la plus directe, mais vous renoncez aux webhooks et devez interroger régulièrement l’API pour détecter les changements. Ce compromis convient généralement à la synchronisation des commandes et des stocks d’une petite boutique, mais pas si l’entreprise attend une réaction quasi immédiate aux nouvelles commandes.

Le guide officiel sur l’authentification et les autorisations répertorie les niveaux d’accès de chaque API et confirme qu’une requête ne peut voir que les données du site auquel appartient la clé ou le token.

Obtenir une clé API Squarespace et effectuer sa première requête

  1. Connectez-vous au site Squarespace, qui doit être associé à l’offre Commerce Advanced.
  2. Ouvrez Settings, puis Advanced, puis Developer API Keys, et cliquez sur Generate Key.
  3. Nommez la clé et sélectionnez les API ainsi que le niveau d’autorisation nécessaires. Accordez le minimum requis : une synchronisation d’expédition a généralement besoin de Orders (Read and Write), et de rien d’autre.
  4. Copiez immédiatement la clé. Elle ne s’affiche qu’une seule fois.

Chaque requête doit inclure un en-tête Authorization: Bearer et un en-tête User-Agent décrivant votre application. Les requêtes sans User-Agent sont refusées, et des valeurs par défaut comme curl/7.54.0 peuvent entraîner une limitation de débit plus stricte : définissez donc votre propre valeur. Les requêtes HTTP non chiffrées sont refusées.

curl 'https://api.squarespace.com/1.0/commerce/orders?paymentStates=PAID,PARTIALLY_PAID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: acme-orders-sync/1.0'

Stockez la clé dans un gestionnaire de secrets, jamais dans le dépôt de code. Comme elle n’expire pas, une clé divulguée reste valide jusqu’à sa suppression dans le tableau de bord.

Fonctionnement du flux OAuth Squarespace et du renouvellement des tokens

Squarespace utilise le flux standard authorization-code. Vous enregistrez le client, redirigez le propriétaire du site vers l’URL d’autorisation, recevez un code à usage unique sur votre URI de redirection, puis l’échangez contre des tokens. L’enregistrement demande un nom de client, une icône, des URI de redirection ainsi que des liens vers vos conditions d’utilisation et votre politique de confidentialité ; Squarespace fournit ensuite un identifiant client et un secret.

Le centre d’aide de Squarespace indique que l’ancien formulaire de demande pour les nouvelles applications OAuth sera supprimé le , au profit d’un processus en libre-service. La documentation pour développeurs renvoie encore vers la page des applications développeur : vérifiez donc le parcours d’inscription actuel avant de planifier votre calendrier.

https://login.squarespace.com/api/1/login/oauth/provider/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://app.example.com/oauth/callback
  &scope=website.orders.read,website.inventory
  &state=RANDOM_CSRF_VALUE
  &access_type=offline
Scope Autorisations accordées
website.orders / website.orders.read Envoyer les données de commande et marquer les commandes comme expédiées / consulter les commandes et leur traitement
website.products / website.products.read Consulter et modifier les produits / consulter les produits
website.inventory / website.inventory.read Consulter et mettre à jour les stocks / consulter les stocks
website.contacts / website.contacts.read Gérer les contacts et les carnets d’adresses / les consulter
website.discounts / website.discounts.read Consulter et gérer les remises / consulter les remises
website.transactions.read Consulter les données transactionnelles des commandes et des dons

Quatre détails du guide OAuth expliquent la plupart des premiers échecs :

  • Le code d’autorisation est valide pendant deux minutes et ne peut être utilisé qu’une fois. Il arrive encodé dans l’URL : décodez-le avant de l’envoyer à l’endpoint de tokens.
  • L’endpoint de tokens attend un en-tête Basic construit à partir de client_id:client_secret, ainsi qu’un User-Agent. L’absence de User-Agent génère une erreur faisant référence à SEC-43.
  • Les tokens d’accès sont valides pendant 30 minutes. Sans access_type=offline, vous ne recevez jamais de refresh token et l’utilisateur doit s’authentifier de nouveau.
  • Les refresh tokens sont valides pendant 7 jours et à usage unique : chaque renouvellement renvoie un nouveau refresh token, et l’ancien est invalidé dès que le nouveau token d’accès est utilisé.

C’est cette dernière règle qui fait échouer les intégrations en production. Si deux workers renouvellent le token simultanément, l’un d’eux présente un refresh token déjà consommé et la chaîne est interrompue, ce qui oblige le marchand à se reconnecter. Sérialisez les renouvellements derrière un verrou et enregistrez la nouvelle paire de tokens dans un stockage persistant avant de l’utiliser. Chaque renouvellement produisant un nouveau token valable sept jours, un worker exécuté en continu reste connecté ; en revanche, un worker arrêté plus d’une semaine perd l’accès.

import base64
import threading
import time
import requests

TOKEN_URL = 'https://login.squarespace.com/api/1/login/oauth/provider/tokens'
USER_AGENT = 'acme-orders-sync/1.0'
_lock = threading.Lock()  # use a database row lock if you run several processes


def _basic(client_id, client_secret):
    raw = f'{client_id}:{client_secret}'.encode()
    return 'Basic ' + base64.b64encode(raw).decode()


def get_access_token(store, client_id, client_secret):
    # store: dict with access_token, access_token_expires_at, refresh_token
    with _lock:
        if store['access_token_expires_at'] - time.time() > 10:
            return store['access_token']
        resp = requests.post(
            TOKEN_URL,
            headers={
                'Authorization': _basic(client_id, client_secret),
                'Content-Type': 'application/json',
                'User-Agent': USER_AGENT,
            },
            json={'grant_type': 'refresh_token', 'refresh_token': store['refresh_token']},
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        store['access_token'] = data['access_token']
        store['access_token_expires_at'] = float(data['access_token_expires_at'])
        store['refresh_token'] = data['refresh_token']  # persist before using the token
        return store['access_token']

Lorsqu’un appel renvoie 401, le token a expiré ou le marchand a révoqué l’accès. Arrêtez les nouvelles tentatives et affichez à l’utilisateur une invitation à reconnecter le compte.

Développer vous-même l’intégration Squarespace ou la confier à une équipe

Les endpoints ne sont pas particulièrement complexes. Le coût se situe surtout dans le travail périphérique : enregistrement et validation du client OAuth, stockage des tokens résistant aux accès concurrents, traitements de rapprochement pour les événements manqués et tests sur de vraies données de boutique, notamment les échéanciers de paiement, les abonnements et les catalogues comportant de nombreuses variantes. Si l’intégration constitue une fonctionnalité secondaire de votre produit et qu’un développeur dispose de quelques semaines, développez-la en interne. Si elle relie Squarespace à une marketplace, un ERP ou un système logistique dont l’activité dépend, il est généralement plus économique de demander d’abord à une équipe spécialisée dans les intégrations d’API de plateformes e-commerce d’en définir le périmètre.

Limites de débit de l’API Squarespace et moyens de les respecter

Limite Valeur S’applique à
Limite générale 300 requêtes par minute, soit environ 5 par seconde Commerce APIs
Réponse en cas de dépassement 429 Too Many Requests, avec une période d’attente d’une minute Commerce APIs
Create Order 100 requêtes par heure et par site Authentification par clé API uniquement ; ne s’applique pas à OAuth

Ces limites sont confortables pour la synchronisation, mais contraignantes pour les opérations en masse. Interroger les commandes une fois par minute utilise moins de 1 % du quota ; une migration de catalogue qui crée les produits et téléverse les images appel par appel peut l’atteindre en quelques secondes. La limite de Create Order est plus restrictive qu’il n’y paraît : avec une clé API, importer l’historique des commandes d’un autre canal est limité à 100 commandes par heure et par site, ce qui transforme un important retard en opération de plusieurs jours. Si vous devez importer en masse, c’est un argument en faveur d’OAuth.

Comme une réponse 429 impose une attente complète d’une minute, patientez une minute avant de réessayer plutôt que de relancer rapidement les requêtes, ce qui ne ferait que prolonger l’attente.

import time
import requests

USER_AGENT = 'acme-orders-sync/1.0'


def sqsp_get(path, token, params=None):
    url = f'https://api.squarespace.com{path}'
    headers = {'Authorization': f'Bearer {token}', 'User-Agent': USER_AGENT}
    for _ in range(3):
        r = requests.get(url, headers=headers, params=params, timeout=30)
        if r.status_code == 429:
            time.sleep(60)  # documented cool-down is one minute
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError('still rate limited after 3 attempts')

Squarespace documente également l’en-tête Idempotency-Key. Consultez ce guide avant d’ajouter des tentatives automatiques à un appel qui crée une ressource, afin qu’un délai d’attente suivi d’une nouvelle tentative ne crée pas de doublon.

Webhooks Squarespace : événements déclenchés et événements absents

Les webhooks sont gérés par Webhook Subscriptions API, qui nécessite un token d’accès OAuth. Une clé API ne peut ni créer, ni lister, ni supprimer des abonnements. Vous enregistrez un endpoint HTTPS et une liste de sujets ; les sujets documentés concernent principalement order.create, order.update, extension.uninstall, ainsi que les événements de création, de modification et de suppression des contacts et des adresses. Le token doit disposer du scope correspondant : website.orders ou website.orders.read pour les sujets de commande, website.contacts pour les contacts et adresses, et aucun scope pour extension.uninstall.

import requests

resp = requests.post(
    'https://api.squarespace.com/1.0/webhook_subscriptions',
    headers={
        'Authorization': f'Bearer {access_token}',
        'User-Agent': 'acme-orders-sync/1.0',
        'Content-Type': 'application/json',
    },
    json={
        'endpointUrl': 'https://sync.example.com/hooks/squarespace',
        'topics': ['order.create', 'order.update', 'extension.uninstall'],
    },
    timeout=30,
)
resp.raise_for_status()
secret = resp.json()['secret']  # returned only on create and on secret rotation

La réponse contient un secret, une valeur hexadécimale qui permet de vérifier qu’une notification provient bien de Squarespace. Il n’est affiché que lors de la création de l’abonnement ou de la rotation du secret : stockez-le immédiatement. Suivez le guide de vérification des notifications dans la documentation des webhooks pour appliquer le contrôle de signature exact et refusez toute requête qui échoue à ce contrôle. Après une rotation, l’ancien secret ne fonctionne plus.

Utilisez l’action send-test-notification pour tester votre endpoint. Il s’agit d’un appel unique, qui n’est pas relancé en cas d’échec ou d’expiration. Pour les livraisons réelles, vérifiez le comportement de confirmation et de nouvelle tentative dans la documentation des webhooks et rendez votre handler idempotent dans tous les cas : accusez rapidement réception, placez l’identifiant de commande dans une file, puis effectuez le traitement de manière asynchrone.

Abonnez-vous à extension.uninstall même si seules les commandes vous intéressent. C’est ce qui vous informe qu’un marchand s’est déconnecté, afin que vous puissiez arrêter la synchronisation et supprimer ses tokens.

Synchroniser les commandes Squarespace sans en manquer

Considérez les webhooks comme une sonnette et l’endpoint de liste comme la source de vérité. Les propres règles de Orders API l’expliquent :

  • Par défaut, la liste des commandes renvoie uniquement les états de paiement NOT_CHARGED, AUTHORIZED, PAID et REFUNDED. Les commandes PENDING, FAILED, PARTIALLY_PAID, REFUND_PENDING ou REFUND_FAILED sont exclues, sauf si vous les indiquez dans le paramètre paymentStates.
  • Les échéanciers de paiement — un acompte au moment du paiement, puis des versements planifiés — correspondent à une seule commande dont le paymentState évolue à mesure que les versements arrivent. Pour ces commandes, order.create ne se déclenche que lorsque l’état atteint PAID, c’est-à-dire après l’encaissement de tous les versements. Aucun webhook n’est envoyé pour l’acompte ni pour les versements intermédiaires.
  • order.update couvre l’expédition, les remboursements, l’annulation, le passage à l’état pending et les modifications d’adresse e-mail.

Une intégration fondée uniquement sur les webhooks ignore donc silencieusement les nouvelles commandes avec échéancier pendant plusieurs semaines. Le modèle fiable consiste à traiter les événements order.create et order.update en récupérant la commande par son identifiant puis en effectuant un upsert, et à exécuter séparément une tâche planifiée qui liste les commandes en incluant PARTIALLY_PAID dans paymentStates, afin de rapprocher celles qui manquent dans votre base. Utilisez l’identifiant de commande Squarespace comme clé de vos enregistrements pour que les doublons liés aux répétitions restent sans conséquence.

Dans l’autre sens, Orders API peut marquer une commande comme expédiée et déclencher la notification d’expédition : c’est le point d’intégration naturel pour un système de livraison ou de 3PL. L’API peut également importer des commandes provenant de canaux tiers, dans la limite de Create Order indiquée plus haut.

Synchroniser les produits et les stocks avec Products API v2

Utilisez v2 pour les nouveaux projets. Cette version prend en charge quatre types de produits : physiques, services, cartes cadeaux et téléchargements. Les anciennes versions v1.0 et v1.1 restent prises en charge, mais leurs possibilités sont plus limitées. Les produits physiques fonctionnent avec toutes les versions ; les produits de type service et carte cadeau sont disponibles uniquement dans v2 ; les produits téléchargeables sont les plus restreints : dans v2, ils peuvent être consultés et modifiés, mais pas créés ni supprimés, et ils ne peuvent pas avoir de variantes.

Les éléments qui structurent une synchronisation de catalogue :

  • Chaque produit appartient à une seule page de boutique et n’est achetable que si la page de boutique est activée et que le produit est défini comme visible. Lorsqu’un produit est importé correctement mais n’est pas vendu, l’un de ces deux paramètres est généralement en cause.
  • Un produit peut contenir jusqu’à 100 images. Le téléversement des images est asynchrone et un endpoint distinct permet d’en vérifier le traitement : interrogez-le avant de considérer une image comme disponible ou de l’associer à une variante.
  • Les catégories utilisées par une page de boutique pour regrouper les produits ne sont pas accessibles via l’API. Prévoyez une étape manuelle ou une autre méthode pour gérer la structure des catégories.
  • Les stocks sont associés aux variantes et gérés par Inventory API, avec sa propre autorisation ou son propre scope. Une synchronisation qui modifie les prix et les stocks a donc besoin des deux accès.

Déterminez à l’avance quel système est propriétaire de chaque champ. Une répartition courante consiste à confier les titres, descriptions et images au système de merchandising, et les quantités en stock au système d’inventaire. Les sujets de webhook documentés par Squarespace sont centrés sur les commandes et les contacts : vérifiez la liste actuelle avant de concevoir une synchronisation des stocks déclenchée par push ; l’interrogation planifiée d’Inventory API reste l’option la plus sûre par défaut.

Ce que l’API Squarespace ne peut pas faire

  • Pas de webhooks avec une clé API. Les abonnements aux webhooks nécessitent OAuth.
  • Pas de données de dons dans Orders. Utilisez Transactions API.
  • Pas de catégories de pages de boutique. Products API ne les expose pas.
  • Pas de nouveaux projets avec Profiles. Cette API est en mode maintenance ; utilisez Contacts.
  • Pas d’accès ouvert aux soumissions de formulaires. La clé Forms API est documentée uniquement pour l’intégration Zapier.
  • Pas d’accès intersites. Une clé ou un token ne peut voir que le site auquel il appartient : une intégration multisite nécessite donc un jeu d’identifiants par boutique.

Checklist avant de mettre en production une intégration Squarespace

  1. Choisir délibérément une clé API ou OAuth, en connaissant les conséquences pour les webhooks et Create Order.
  2. Demander le jeu d’autorisations minimal nécessaire.
  3. Définir un User-Agent explicite sur chaque requête, y compris les appels de tokens.
  4. Sérialiser l’utilisation des refresh tokens et enregistrer la nouvelle paire avant de l’utiliser.
  5. Attendre une minute complète après une réponse 429.
  6. Vérifier les signatures des webhooks, stocker le secret et rendre les handlers idempotents.
  7. Ajouter une tâche de rapprochement qui inclut les commandes PARTIALLY_PAID.
  8. Traiter 401 et extension.uninstall en déconnectant proprement le marchand.

Si vous préférez obtenir un plan adapté plutôt qu’une simple checklist, indiquez-nous les systèmes avec lesquels Squarespace doit communiquer : nous vous proposerons une approche et un devis via le formulaire de devis gratuit.

FAQ

Questions fréquentes

Squarespace propose-t-il une API publique ?

Oui. Squarespace propose des Commerce APIs pour les commandes, les produits, les stocks, les contacts, les remises, les transactions et les abonnements aux webhooks. Ce sont des API REST accessibles depuis api.squarespace.com, qui renvoient du JSON et s’authentifient avec une clé API ou un token d’accès OAuth 2.0.

Ai-je besoin d’une offre Squarespace payante pour utiliser l’API ?

Pour une application personnalisée qui utilise une clé API, le site doit disposer de l’offre Commerce Advanced. OAuth fonctionne différemment : les applications développées comme Squarespace Extensions peuvent être utilisées par des clients avec n’importe quelle offre, mais le développeur doit enregistrer l’application auprès de Squarespace comme client OAuth.

Quelle est la limite de débit de l’API Squarespace ?

Les Commerce APIs autorisent 300 requêtes par minute, soit environ cinq requêtes par seconde. En cas de dépassement, l’API renvoie une réponse 429 avec une période d’attente d’une minute. L’endpoint Create Order a une limite distincte de 100 requêtes par heure et par site lorsque vous utilisez une clé API ; cette limite ne s’applique pas à OAuth.

Puis-je utiliser les webhooks Squarespace avec une clé API ?

Non. Webhook Subscriptions API nécessite un token d’accès OAuth et ne prend pas en charge les clés API. Avec une clé API, vous devez interroger Orders API selon un calendrier pour détecter les changements.

Combien de temps les tokens OAuth Squarespace restent-ils valides ?

Les tokens d’accès sont valides pendant 30 minutes. Si vous demandez access_type=offline, vous recevez également un refresh token valable 7 jours. Les refresh tokens sont à usage unique : chaque renouvellement renvoie un nouveau refresh token et invalide l’ancien. Enregistrez donc la paire la plus récente et évitez que plusieurs workers renouvellent le token simultanément.

Pourquoi mon webhook de commande Squarespace ne s’est-il pas déclenché pour une nouvelle commande ?

Pour une commande avec échéancier de paiement, le webhook order.create ne se déclenche que lorsque la commande devient entièrement PAID, et non lorsque l’acompte est encaissé. Pour détecter ces commandes dès leur création, listez les commandes en configurant le paramètre paymentStates afin d’y inclure PARTIALLY_PAID.

Dois-je utiliser Profiles API ou Contacts API ?

Utilisez Contacts API pour les nouvelles intégrations. Squarespace a placé Profiles API en mode maintenance et oriente les nouveaux projets vers Contacts, qui gère les clients, abonnés et donateurs ainsi que les carnets d’adresses et les préférences marketing.

Restez informé avec Netalith

Recevez des ressources de développement, des mises à jour produit et des offres spéciales directement dans votre boîte mail.