Intégration de l’API Square : OAuth, catalogue et webhooks
Guide d’intégration de l’API Square : OAuth ou jetons personnels, synchronisation du catalogue, paiements idempotents et webhooks signés avec Python.
Long Nguyen
Développeur fullstack · Ingénieur IA · Chercheur
Ce que couvre réellement une intégration de l’API Square
Une intégration de l’API Square relie votre propre logiciel (boutique en ligne, ERP, outil de réservation ou application mobile) au compte Square d’un vendeur via REST. Square applique un même numéro de version à toutes ses API : Payments, Orders, Catalog et Inventory évoluent donc ensemble, et la plupart des intégrations réelles en utilisent quatre ou cinq à la fois. Le tableau ci-dessous associe chaque besoin à l’API correspondante.
| Besoin | API | À savoir avant de commencer |
|---|---|---|
| Connecter le compte d’un vendeur | OAuth API | Renvoie un jeton d’accès et un jeton d’actualisation. Les applications serveur utilisent le code flow ; les applications mobiles et monopages utilisent PKCE. |
| Catalogue de produits | Catalog API | Le catalogue alimente la bibliothèque d’articles du Square Dashboard et les articles affichés dans Square Point of Sale. |
| Niveaux de stock | Inventory API | Les quantités sont suivies uniquement au niveau des variations d’articles, par point de vente et par état. |
| Commandes et exécution | Orders API | Enregistre les lignes de commande, calcule les totaux, suit l’exécution et met à jour l’inventaire lorsque les commandes sont finalisées ou remboursées. |
| Accepter des paiements | Payments API | Débite les moyens de paiement collectés avec Square Web Payments SDK ou In-App Payments SDK. |
| Réagir aux changements | Webhooks | Notifications signées telles que catalog.version.updated, inventory.count.updated et oauth.authorization.revoked. |
Avant d’écrire la moindre ligne de code, répondez à une question essentielle : quel système est la source de vérité pour les produits, les prix et les stocks ? Les recommandations de Square sur la synchronisation du catalogue commencent par là. Toutes les décisions suivantes — sens de synchronisation, envoi de quantités ou d’ajustements, propagation des suppressions — en découlent. Négliger ce point est la meilleure façon de créer une intégration qui écrase les prix dans les deux sens.
Les sections suivantes suivent l’ordre dans lequel les problèmes apparaissent généralement en production : authentification, environnements, synchronisation, paiements, webhooks et gestion des versions.
OAuth ou jeton d’accès personnel : ce qu’il faut pour votre intégration Square
Square propose deux moyens d’obtenir un jeton d’accès. Un jeton d’accès personnel appartient à votre propre compte développeur ; il suffit donc si vous intégrez uniquement votre compte Square. Dès que d’autres vendeurs connectent leur compte à votre application, vous avez besoin d’OAuth : le vendeur approuve des autorisations précises sur une page Square, puis votre application reçoit des jetons associés à ce vendeur. Certains endpoints restent accessibles uniquement avec un jeton personnel, même dans une application OAuth ; la documentation de l’API OAuth de Square précise que les API Webhook Subscriptions et Events n’acceptent pas les jetons d’accès OAuth.
| Flux | À utiliser pour | Jeton d’actualisation | Secret client |
|---|---|---|---|
| Code flow | Applications côté serveur dont vous contrôlez l’hébergement | Réutilisable ; reste valide jusqu’à la révocation de l’accès par le vendeur | Requis |
| PKCE flow | Applications mobiles, applications monopages et applications desktop natives | À usage unique ; expire après 90 jours | Non utilisé (un code_verifier le remplace) |
Choisissez un flux et utilisez-le de bout en bout : la documentation indique clairement qu’ils ne peuvent pas être mélangés. Pour la plupart des intégrations web, il s’agit du code flow. Voici les limites qui posent le plus souvent problème :
- Les codes d’autorisation expirent après 5 minutes et ne peuvent être utilisés qu’une seule fois. Échangez donc le code directement dans la requête de callback plutôt que de le transmettre à une file d’attente.
- L’URL de redirection doit utiliser HTTPS. Le HTTP simple sur localhost n’est autorisé que dans le Sandbox.
- Les jetons d’accès expirent après 30 jours. Vous les renouvelez avec le jeton d’actualisation.
- Si vous perdez le jeton d’actualisation, le vendeur doit recommencer l’intégralité du processus d’autorisation.
- Un jeton d’actualisation du code flow peut générer plusieurs jetons d’accès, chacun ayant sa propre durée de vie de 30 jours et pouvant être révoqué individuellement. Cela convient à un vendeur qui gère plusieurs boutiques sur un même site e-commerce.
- OAuth Square n’est pas un système de connexion. Il ne prend pas en charge OpenID ni d’autres protocoles d’authentification unique par-dessus OAuth.
Le problème qui atteint les clients est l’expiration du jeton, car elle survient 30 jours après l’intégration, bien après que l’équipe a cessé de surveiller le compte. Renouvelez les jetons selon un calendrier plutôt qu’au premier code 401 : une tâche quotidienne qui actualise les jetons arrivant à expiration dans les sept prochains jours évite qu’un paiement en direct ne soit le premier à détecter un jeton invalide.
import os
import requests
def refresh_access_token(refresh_token):
# Code flow (confidential client). Under PKCE you omit client_secret
# and must store the new single-use refresh token that comes back.
resp = requests.post(
'https://connect.squareup.com/oauth2/token',
json={
'client_id': os.environ['SQUARE_APP_ID'],
'client_secret': os.environ['SQUARE_APP_SECRET'],
'grant_type': 'refresh_token',
'refresh_token': refresh_token,
},
headers={'Square-Version': os.environ['SQUARE_VERSION']},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
return {
'access_token': data['access_token'],
'expires_at': data['expires_at'],
'refresh_token': data.get('refresh_token', refresh_token),
}
Abonnez-vous également à oauth.authorization.revoked. Cet événement est déclenché lorsqu’un vendeur révoque tous les jetons qu’il a accordés à votre application. À sa réception, arrêtez de synchroniser ce marchand et supprimez les jetons enregistrés, au lieu de laisser la tâche d’actualisation échouer chaque nuit pour ce compte.
Square Sandbox et production : quelles différences ?
Le Sandbox et la production sont deux environnements distincts, avec des identifiants différents. Les mélanger renvoie une erreur AUTHENTICATION_ERROR accompagnée du code UNAUTHORIZED, qui ressemble exactement à un jeton invalide. Lorsqu’un appel échoue de cette façon, vérifiez l’environnement avant de vérifier les scopes.
| Production | Sandbox | |
|---|---|---|
| URL de base de l’API | https://connect.squareup.com/v2 |
https://connect.squareupsandbox.com/v2 |
| URL de base OAuth | https://connect.squareup.com/oauth2 |
https://connect.squareupsandbox.com/oauth2 |
| Application ID et jetons | ID de production et jetons de production | ID Sandbox et jetons Sandbox ; ils ne sont pas interchangeables |
| Connexion à la page d’autorisation | Connexion directe | Impossible ; ouvrez d’abord le Sandbox Dashboard pour un compte de test dans un autre onglet. Le paramètre session=false n’est pas pris en charge. |
| URL de redirection | HTTPS | HTTPS ou HTTP sur localhost |
Comme l’OAuth du Sandbox est peu pratique à piloter, testez une fois le flux d’autorisation de bout en bout, puis utilisez les comptes de test Sandbox et leurs jetons d’accès générés pour tout le reste (catalogue, commandes et paiements). Square permet de générer ces jetons pour un compte de test avec des autorisations précises, ce qui est bien plus rapide que de répéter l’écran de consentement.
Synchroniser un catalogue et un inventaire Square avec votre boutique
Envoyer les changements de Square vers votre système
Le guide de Square sur la synchronisation d’un catalogue avec une plateforme externe décrit deux déclencheurs : réagir au webhook catalog.version.updated ou effectuer une interrogation à intervalle fixe. Dans les deux cas, appelez SearchCatalogObjects avec begin_time afin que Square ne renvoie que les éléments modifiés. Trois détails déterminent la réussite de cette approche :
- Mettez en cache l’horodatage de l’événement précédent, pas celui de l’événement actuel. La valeur
catalog_version.updated_atde l’événement indique le moment où la nouvelle version a été créée ; les changements qui l’ont déclenché se trouvent donc après le marqueur précédent. - Les changements peuvent venir de partout : Dashboard, Square Point of Sale ou toute autre intégration utilisée par le vendeur. Votre logique ne doit pas supposer que votre application est l’unique système qui écrit des données.
- N’appelez jamais
ListCatalogselon un calendrier ou à chaque événement. Le volume de résultats augmente et finit par exposer votre application aux limites de débit.
Les suppressions sont renvoyées par les recherches suivantes avec is_deleted défini à true. Demandez donc les objets supprimés et répercutez-les, sinon votre boutique continuera à vendre des articles retirés par le vendeur.
import os
import requests
BASE = 'https://connect.squareup.com/v2'
def square_headers(access_token):
return {
'Authorization': f'Bearer {access_token}',
'Square-Version': os.environ['SQUARE_VERSION'],
'Content-Type': 'application/json',
}
def catalog_changes_since(access_token, begin_time):
cursor = None
while True:
body = {
'begin_time': begin_time,
'object_types': ['ITEM', 'ITEM_VARIATION'],
'include_deleted_objects': True,
}
if cursor:
body['cursor'] = cursor
resp = requests.post(f'{BASE}/catalog/search', json=body,
headers=square_headers(access_token), timeout=30)
resp.raise_for_status()
data = resp.json()
yield from data.get('objects', [])
cursor = data.get('cursor')
if not cursor:
break
def on_catalog_version_updated(event, state):
# state['last_sync'] holds the previous event's catalog_version.updated_at
new_marker = event['data']['object']['catalog_version']['updated_at']
for obj in catalog_changes_since(state['access_token'], state['last_sync']):
if obj.get('is_deleted'):
remove_from_store(obj['id']) # your function
else:
upsert_into_store(obj) # your function
state['last_sync'] = new_marker # advance only after success
Envoyer les changements de votre système vers Square
Lorsque votre plateforme détient le catalogue de référence, envoyez les modifications avec les endpoints de mise à jour et de suppression, en regroupant les opérations similaires. BatchUpsertCatalogObjects accepte jusqu’à 10 000 objets et produit une seule notification webhook au lieu de milliers, ce qui protège également votre propre gestionnaire de webhooks. Enregistrez l’identifiant externe comme valeur d’attribut personnalisé sur l’objet Square, et l’identifiant de l’objet Square dans votre système, afin que chaque mise à jour ultérieure commence par une recherche fiable plutôt que par une correspondance approximative.
La synchronisation bidirectionnelle est le principal piège. Les recommandations de Square signalent les risques de concurrence, de fusion et de suppressions en double, ainsi qu’un risque lié aux prix : une modification du prix sur le terminal peut réécrire silencieusement le prix en ligne, alors que le vendeur souhaite peut-être appliquer des prix différents selon le canal. Si une synchronisation bidirectionnelle est indispensable, définissez précisément, champ par champ, quel système est prioritaire.
L’inventaire est un ensemble d’états, pas un chiffre unique
L’inventaire suit les quantités qui passent entre des états tels que IN_STOCK, SOLD et WASTE dans un point de vente, plutôt que de décrémenter un compteur unique. Seules les variations d’articles peuvent être suivies, et l’API ne permet pas de gérer les composants, ingrédients ou lots ; un kit ou une recette nécessite donc sa propre logique dans votre système. La lecture requiert l’autorisation INVENTORY_READ et l’écriture INVENTORY_WRITE.
| Objet | Contenu | Qui le définit |
|---|---|---|
| InventoryCount | Quantité calculée d’une variation dans un point de vente et un état donnés | Square, recalculé après chaque ajustement ou inventaire physique |
| InventoryAdjustment | Quantité passant d’un état à un autre | Ventes, réception de stock, pertes ou votre application |
| InventoryPhysicalCount | Quantité vérifiée lors d’un comptage manuel ou provenant d’un système fiable | Vous |
| InventoryTransfer | Retiré dans la version Square . Un déplacement entre deux points de vente est désormais un ajustement dont from_location_id et to_location_id sont différents. |
Migrer vers les ajustements |
Conséquence pratique : un inventaire physique écrase le calcul de Square. Si votre système lit une quantité, prend quelques secondes pour la traiter, puis la réécrit comme inventaire physique, toute vente en magasin effectuée entre-temps est annulée. Une règle prudente consiste à envoyer des ajustements (écarts) tant que Square Point of Sale continue d’enregistrer des ventes, et à réserver les inventaires physiques à un rapprochement planifié ou à un système qui détient réellement le stock de référence. Abonnez-vous à inventory.count.updated pour être informé des changements de quantité au moment où ils surviennent.
Commandes, paiements et clés d’idempotence
Le flux le plus propre consiste à créer une commande avec l’Orders API, puis à la payer avec CreatePayment en la référençant. Les commandes peuvent être constituées à partir d’articles du catalogue ou de lignes personnalisées définies lors de leur création. Vous pouvez ensuite les rechercher, notamment par client. Lorsqu’une commande est finalisée ou remboursée, Square met à jour l’inventaire de ses articles. Si vous écrivez également des ajustements d’inventaire pour cette même vente, vous la comptabiliserez deux fois. Décidez quel système est responsable de cette décrémentation et tenez-vous-en à cette règle.
Les réseaux peuvent tomber en panne après la réussite du débit, c’est précisément à ce moment qu’une nouvelle tentative naïve risque de facturer deux fois le client. Square gère ce cas avec des clés d’idempotence : répétez une requête avec la même clé et le même corps, et vous obtenez la réponse d’origine au lieu d’un second débit. Réutilisez la clé avec un corps différent — un montant différent, par exemple — et vous obtiendrez une erreur, même si Square précise que le comportement peut varier selon l’API.
L’erreur classique consiste à générer un nouvel UUID aléatoire à chaque passage dans la boucle de nouvelle tentative, ce qui annule totalement la protection. Dérivez plutôt la clé de vos propres identifiants et ne changez-la que lorsque le client commence volontairement une nouvelle tentative de paiement, par exemple avec une autre carte.
import os
import uuid
import requests
NAMESPACE = uuid.UUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8') # any fixed UUID
def charge_order(access_token, order_id, location_id, source_token,
amount_cents, attempt=1, currency='USD'):
# Same order + same attempt = same key, so network retries cannot double-charge.
key = str(uuid.uuid5(NAMESPACE, f'payment:{order_id}:{attempt}'))
body = {
'idempotency_key': key,
'source_id': source_token,
'order_id': order_id,
'location_id': location_id,
'amount_money': {'amount': amount_cents, 'currency': currency},
}
resp = requests.post(
'https://connect.squareup.com/v2/payments',
json=body,
headers={
'Authorization': f'Bearer {access_token}',
'Square-Version': os.environ['SQUARE_VERSION'],
'Content-Type': 'application/json',
},
timeout=30,
)
resp.raise_for_status()
return resp.json()['payment']
Un point commercial doit être intégré dès la conception. Au , la documentation de l’Orders API de Square indique qu’il n’y a pas de frais de transaction pour les commandes payées avec Square, et qu’un frais de 1 % par transaction s’applique lorsque l’Orders API est utilisée avec un prestataire de paiement autre que Square. Vérifiez les conditions actuelles auprès de Square avant de concevoir un flux qui dépend de cette distinction.
Vérifier les webhooks Square et gérer les doublons
Votre URL de notification est publique : n’importe qui peut donc lui envoyer une requête. Chaque notification Square contient un en-tête x-square-hmacsha256-signature. Vous devez recalculer la signature et rejeter toute valeur qui ne correspond pas.
| Point de vigilance | Ce que fournit Square |
|---|---|
| Authenticité | Signature HMAC-SHA-256 construite à partir de la clé de signature de l’abonnement, de l’URL de notification et du corps brut de la requête |
| Comparaison | Utilisez une comparaison à temps constant. Square avertit qu’une comparaison qui s’arrête à la première différence est vulnérable aux attaques temporelles, et que la prise en charge du temps constant varie selon les assistants des SDK |
| Doublons | Un event_id dans le corps, fourni comme valeur d’idempotence ; ignorez les événements déjà traités |
| État de l’endpoint | Si votre endpoint ne renvoie aucun code 2xx pendant trois semaines, Square envoie des avertissements après la première, la deuxième et la troisième semaine, puis désactive l’abonnement |
Comme la signature couvre l’URL de notification et le corps brut, deux erreurs expliquent la plupart des rejets injustifiés. La première est un framework qui analyse le JSON, suivi d’un gestionnaire qui le sérialise à nouveau, ce qui modifie les octets. La seconde est un proxy ou un CDN qui modifie le protocole ou l’hôte : l’URL reconstruite par votre code depuis la requête ne correspond alors plus à celle que vous avez enregistrée. Lisez le corps brut et récupérez l’URL de notification dans la configuration, au lieu de la reconstruire à partir de la requête reçue.
import json
from django.conf import settings
from django.core.cache import cache
from django.http import HttpResponse, HttpResponseForbidden
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from square.utils.webhooks_helper import verify_signature
@csrf_exempt
@require_POST
def square_webhook(request):
body = request.body.decode('utf-8') # raw body, never re-serialized JSON
signature = request.headers.get('x-square-hmacsha256-signature', '')
if not verify_signature(
request_body=body,
signature_header=signature,
signature_key=settings.SQUARE_WEBHOOK_SIGNATURE_KEY,
notification_url=settings.SQUARE_WEBHOOK_URL, # exactly as registered
):
return HttpResponseForbidden()
event = json.loads(body)
# cache.add returns False when the key exists, i.e. we have seen this event
if not cache.add('square:event:' + event['event_id'], 1, timeout=7 * 24 * 3600):
return HttpResponse(status=200)
process_square_event.delay(event) # your task queue; return fast
return HttpResponse(status=200)
Accusez réception d’abord et traitez ensuite : vérifiez, dédupliquez, mettez en file d’attente, puis renvoyez 200. En production, remplacez la vérification dans le cache par une contrainte d’unicité sur event_id dans votre base de données afin que la déduplication survive à une purge du cache.
Épingler la version de l’API Square et planifier les mises à niveau
Square versionne son API avec des dates de publication au format YYYY-MM-DD, généralement chaque mois, et une seule version s’applique à toutes les API. Chaque application enregistrée dans la Developer Console possède une version par défaut qui lui est attribuée et affichée sur la page Credentials. Cette version est utilisée pour chaque requête, sauf si vous la remplacez avec l’en-tête Square-Version. La réponse renvoie toujours la version utilisée : enregistrez-la dans vos logs.
| Modification effectuée par Square | Rupture de compatibilité ? |
|---|---|
| Nouvel endpoint | Non |
| Nouveau champ facultatif ou en lecture seule | Non |
| Dépréciation | Non, mais elle est versionnée pour que vous puissiez la repérer |
| Nouveau champ obligatoire | Oui |
| Retrait | Oui |
| Renommage ou changement de structure d’un champ, d’un type ou d’une constante textuelle | Oui |
| Code de statut HTTP différent pour une opération | Oui |
Le retrait d’InventoryTransfer dans la version en est un exemple concret : le code épinglé sur une version plus ancienne continue de fonctionner, tandis que le même code cesse de fonctionner dès que vous passez cette date. Envoyez donc explicitement Square-Version depuis votre propre configuration au lieu de vous fier à la version par défaut de la console, et effectuez les mises à niveau de manière planifiée. Une mise à niveau inclut toutes les modifications intervenues depuis votre version précédente : consultez les notes de version de chaque version intermédiaire et exécutez votre suite de tests dans le Sandbox avec le nouvel en-tête avant de toucher à la production. Notez également que les SDK Java, Ruby, Python et PHP placent la date de l’API à la fin de leur numéro de version, contrairement aux SDK .NET, Node.js et Go. Vérifiez donc quelle version de l’API cible une version donnée du SDK.
Développer une intégration Square sur mesure ou utiliser un connecteur prêt à l’emploi
Un connecteur prêt à l’emploi est le bon choix lorsque votre catalogue est réduit, qu’un système en est clairement responsable et que vous avez seulement besoin de faire circuler les produits, commandes et paiements dans un seul sens. Le développement sur mesure devient intéressant lorsque plusieurs canaux de vente doivent conserver des catalogues cohérents, lorsque l’inventaire obéit à des règles que le modèle Square ne peut pas exprimer (lots, kits ou stock réservé), ou lorsque les données de commandes et de clients doivent alimenter un ERP ou un CRM avec votre propre logique métier.
Si vous connectez Square à une boutique Shopify, WooCommerce, BigCommerce ou personnalisée et que les risques évoqués plus haut — modifications de prix dans les deux sens, écrasement des stocks ou expiration des jetons — vous concernent, il s’agit du travail d’intégration de plateforme et d’API couvert par le service d’intégration de plateformes e-commerce et d’API de Netalith.
Checklist d’intégration de l’API Square avant la mise en ligne
- Conservez les identifiants, URL de base et jetons du Sandbox et de la production dans des configurations distinctes, jamais dans le code.
- Planifiez l’actualisation des jetons de chaque vendeur connecté, stockez les jetons d’actualisation de manière chiffrée et gérez
oauth.authorization.revoked. - Envoyez explicitement
Square-Versionet enregistrez la version renvoyée dans chaque réponse. - Dérivez les clés d’idempotence de vos propres identifiants de commande et de tentative, jamais d’une nouvelle valeur aléatoire à chaque nouvelle tentative.
- Vérifiez la signature du webhook sur le corps brut, dédupliquez avec
event_idet renvoyez 200 avant d’exécuter les traitements lents. - Enregistrez les identifiants externes sur les objets Square et les identifiants Square dans votre système ; écrivez par lots et n’effectuez jamais d’interrogation avec
ListCatalog. - Choisissez délibérément entre ajustements d’inventaire et inventaires physiques, et planifiez une tâche de rapprochement.
- En cas de problème lors d’un appel ou d’une livraison, utilisez les logs d’API et les logs d’événements webhook de la Developer Console.
Si vous préférez que cette intégration soit développée et testée avec votre propre catalogue et vos canaux de vente, décrivez votre projet via le formulaire de demande de devis gratuit de Netalith.
FAQ
Questions fréquentes
Ai-je besoin d’OAuth pour une intégration de l’API Square, ou un jeton d’accès personnel suffit-il ?
Un jeton d’accès personnel suffit si vous intégrez uniquement votre propre compte Square. Si d’autres vendeurs doivent connecter leur compte à votre application, vous avez besoin d’OAuth afin que chaque vendeur accorde des autorisations précises et que votre application reçoive des jetons associés à ce vendeur. Certains endpoints, comme les API Webhook Subscriptions et Events, n’acceptent qu’un jeton personnel, même dans une application OAuth.
Combien de temps les jetons d’accès OAuth Square restent-ils valides ?
Les jetons d’accès OAuth Square expirent après 30 jours. Vous les renouvelez avec le jeton d’actualisation. Dans le code flow, le jeton d’actualisation n’expire pas tant que le vendeur ne révoque pas l’accès ; dans le flux PKCE, il est à usage unique et expire après 90 jours. Actualisez les jetons selon un calendrier avant leur expiration plutôt que d’attendre l’échec d’un appel.
Comment vérifier un webhook Square ?
Calculez une signature HMAC-SHA-256 à partir de la clé de signature de l’abonnement, de l’URL de notification et du corps brut de la requête, puis comparez-la à temps constant avec l’en-tête x-square-hmacsha256-signature. Rejetez toute signature qui ne correspond pas. Les SDK Square incluent un assistant pour cette vérification. Ignorez également les événements répétés en contrôlant la valeur event_id présente dans le corps.
Comment garder l’inventaire Square synchronisé avec ma boutique en ligne ?
Commencez par déterminer quel système détient le stock de référence. Écoutez inventory.count.updated pour recevoir les changements provenant de Square et envoyez des modifications sous forme d’ajustements tant que Square Point of Sale continue d’enregistrer des ventes. Utilisez les inventaires physiques uniquement pour un rapprochement planifié ou lorsque votre système détient réellement le stock de référence, car un inventaire physique écrase la quantité calculée par Square.
L’Orders API de Square entraîne-t-elle des frais supplémentaires ?
Au 29 septembre 2026, la documentation de Square indique qu’il n’y a pas de frais de transaction pour les commandes payées avec Square et qu’un frais de 1 % par transaction s’applique lorsque vous utilisez l’Orders API avec un prestataire de paiement autre que Square. Les conditions peuvent changer : vérifiez les frais actuels auprès de Square avant de concevoir votre intégration en fonction de cette distinction.