Service d’intégration de l’API Etsy : accès et recrutement

Ce que couvre un service d’intégration de l’API Etsy

Un service d’intégration de l’API Etsy relie les données d’une boutique Etsy (fiches produits, inventaire, commandes et suivi) aux systèmes que vous utilisez déjà, via Etsy Open API v3, et maintient la synchronisation entre les deux. Il s’agit généralement d’une boutique en ligne, d’un ERP ou d’une instance Odoo, d’un outil d’expédition ou d’une plateforme multicanale.

Définissez le périmètre par flux de travail, plutôt que de parler simplement de « connecter Etsy ». Chaque ligne ci-dessous correspond à un chantier distinct, avec ses propres scénarios d’erreur, et à un scope d’autorisation précis dans le modèle OAuth d’Etsy.

Deux éléments ne font partie d’aucune intégration légitime. Le scraping des pages Etsy pour récupérer des données que l’API ne fournit pas est interdit par les critères d’accès commercial d’Etsy. Par ailleurs, Open API v3 ne propose aucun endpoint pour acheter des étiquettes d’expédition : le vendeur doit donc toujours les acheter et les imprimer lui-même.

Quel niveau d’accès à l’API Etsy choisir : Seller App, Personal App ou Commercial Access ?

Etsy contrôle l’accès à son API selon le type d’application. Ce choix détermine qui peut se connecter, la rapidité de l’approbation et la possibilité, ou non, de servir plusieurs boutiques. Au 29 septembre 2026, la documentation destinée aux développeurs définit trois niveaux.

La règle que nous appliquons en pratique est la suivante : si l’intégration concerne une seule boutique, son propriétaire doit enregistrer une Seller App avec son propre compte Etsy, puis le développeur construit la solution à partir de cette clé. Etsy n’approuve une Seller App que pour un vendeur qui ne possède aucune autre application active, et l’application ne peut s’authentifier qu’auprès de la boutique qui l’a enregistrée. Une agence ne peut donc pas réutiliser une clé appartenant à l’agence pour plusieurs boutiques clientes, et ne devrait pas essayer. L’avantage est aussi une propriété clairement définie : les identifiants et l’intégration restent au client si le contrat prend fin.

Si vous développez un produit auquel d’autres vendeurs se connecteront, vous commencez par une Personal App, puis vous demandez le Commercial Access. Les critères d’examen documentés comprennent le respect des conditions d’utilisation de l’API et de la politique de mise en cache, l’absence de screen-scraping, l’utilisation d’OAuth pour toute opération touchant aux données privées des membres, ainsi que des noms et visuels conformes à la politique de marque d’Etsy. L’application doit aussi afficher clairement qu’Etsy ne l’approuve ni ne la certifie. Les applications commerciales qui utilisent transactions_r doivent également demander séparément le champ buyer_email. Etsy ne publie aucun délai d’examen et indique seulement qu’il varie selon le cas d’usage : considérez donc l’approbation comme une dépendance sur le chemin critique de votre projet. Les critères complets figurent dans l’introduction à Etsy Open API v3.

Développer en interne, utiliser une application ou recruter un service d’intégration Etsy

Trois options sont réellement envisageables. Le bon choix dépend de l’écart entre votre flux Etsy et le fonctionnement standard des fiches produits et des commandes.

Etsy est rarement votre seul canal. Le service d’intégration de marketplaces de Netalith pour Etsy, Amazon SP-API, eBay, Walmart et Temu couvre Etsy ainsi que ces autres canaux. La logique de stock et de commande peut ainsi être conçue une seule fois pour l’ensemble, plutôt qu’une fois par marketplace.

Pour déterminer rapidement si un développement personnalisé est rentable, notez les situations dans lesquelles une application standard vous obligerait à corriger les données manuellement, par exemple un surbooking après la modification d’une variante ou l’envoi tardif d’un numéro de suivi. Si la liste est courte, achetez une application. Si elle est longue, l’intégration est au cœur du produit et mérite un périmètre écrit.

Comment fonctionne l’authentification de l’API Etsy et quelles sont ses failles courantes

Etsy Open API v3 utilise deux identifiants conjointement : une clé API dans chaque requête et un token OAuth 2.0 pour toute donnée privée ou toute opération d’écriture. Voici les éléments essentiels pour un développeur.

Trois erreurs expliquent la plupart des tickets du type « l’intégration vient de s’arrêter ». Premièrement, la réponse de renouvellement n’est pas enregistrée : le renouvellement suivant utilise alors un token obsolète et le vendeur doit se reconnecter. Enregistrez toujours les dernières valeurs renvoyées et déclenchez une alerte bien avant 90 jours pour toute boutique qui n’a pas effectué de renouvellement. Deuxièmement, le scope accordé peut être un sous-ensemble du scope demandé. Vérifiez donc le champ scope dans la réponse du token au lieu de supposer que les droits d’écriture sont disponibles. Troisièmement, l’absence d’un scope pour un flux donné se manifeste généralement uniquement par l’échec de certains appels, ce qui ressemble à un bug aléatoire jusqu’à ce que quelqu’un compare les scopes.

Un piège de la documentation mérite d’être signalé : certains exemples de tutoriels n’envoient que le keystring dans x-api-key, tandis que la page consacrée à l’authentification précise que le keystring et le shared secret doivent être réunis par deux-points. Suivez la page d’authentification.

Que pouvez-vous synchroniser avec l’API Etsy : endpoints et scopes

Chaque chemin ci-dessous se trouve sous https://api.etsy.com/v3/application. Vérifiez le scope exact de chaque endpoint dans la référence API d’Etsy avant de demander des autorisations à un vendeur : demander plus de scopes que nécessaire réduit les chances d’approbation.

Le corps minimal d’une fiche produit physique au format brouillon comprend quantity, title, description, price, who_made, when_made et taxonomy_id, ainsi que shipping_profile_id et readiness_state_id. image_ids est obligatoire avant l’activation de la fiche. Cette chaîne de dépendances (profil d’expédition, profil de préparation, taxonomie et images) explique pourquoi l’automatisation d’une première fiche prend plus de temps que ne le laisse penser le corps de la requête.

Webhooks ou polling pour les commandes Etsy

Etsy propose désormais des webhooks : une intégration n’a donc plus besoin d’interroger l’API pour chaque nouvelle commande. La documentation des webhooks Etsy répertorie quatre événements, tous liés aux commandes.

La charge utile est un pointeur, pas la commande elle-même : elle contient event_type, resource_url et shop_id, puis votre code appelle resource_url pour récupérer le reçu. La documentation indique que les webhooks sont disponibles pour les applications commerciales et personnelles. Elle ne mentionne pas les Seller Apps : vérifiez donc leur disponibilité dans votre portail développeur avant de concevoir une intégration Seller App qui en dépend.

Chaque livraison est signée. Le contenu signé est constitué de webhook-id, webhook-timestamp et du corps brut, reliés par des points ; la clé est votre secret de signature, sans le préfixe whsec_ et décodé en base64 ; la signature est un HMAC-SHA256 encodé en base64. Voici un vérificateur fonctionnel en Python :

import base64, hashlib, hmac, time

def verify_etsy_webhook(secret, headers, raw_body, tolerance=300):
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False  # stale or replayed
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    expected = base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()
    # header may hold several signatures; drop a version prefix if present
    return any(
        hmac.compare_digest(expected, part.split(",", 1)[-1])
        for part in headers["webhook-signature"].split()
    )

Effectuez la vérification sur les octets bruts avant toute analyse JSON et utilisez webhook-id comme clé d’idempotence, car Etsy conserve le même identifiant lors des nouvelles tentatives. Si votre endpoint échoue, Etsy réessaie immédiatement, puis après 5 secondes, 5 minutes, 30 minutes, 2 heures, 5 heures et 10 heures, deux fois, soit environ 27,5 heures entre la première et la dernière tentative.

Ne supprimez pas complètement le polling. Les événements documentés concernent uniquement les commandes : les changements de fiches et d’inventaire nécessitent donc toujours des lectures planifiées. Un rapprochement comparant votre liste de commandes à celle d’Etsy permet également de détecter les événements manqués par un endpoint défaillant.

Limites de débit de l’API Etsy : comment les respecter

Etsy applique des limites par application, c’est-à-dire par clé API, sous forme de requêtes par seconde (QPS) et de requêtes par jour (QPD). La limite quotidienne fonctionne sur une fenêtre glissante de 24 heures et non sur une remise à zéro à minuit : le quota se libère donc progressivement à mesure que les anciennes requêtes sortent de la fenêtre. Les valeurs réelles de votre application sont affichées dans l’Etsy Developer Portal.

La conséquence la plus importante pour la conception est la suivante : le budget appartient à la clé, pas à la boutique. Toutes les boutiques connectées à une même application puisent dans le même quota. Un vendeur qui relance massivement ses fiches peut donc priver les autres de ressources. Une intégration multiboutique a besoin d’une file de requêtes partagée avec une planification équitable ; les appels de commande et de suivi doivent passer avant les actualisations du catalogue.

• Chaque réponse réussie indique x-limit-per-day et x-remaining-today (ainsi que leurs équivalents par seconde). Enregistrez ces valeurs et déclenchez une alerte avant d’atteindre zéro.
• Etsy vérifie d’abord le QPS, puis le QPD. Le dépassement de l’un ou l’autre renvoie 429 avec un en-tête retry-after.
• Considérez retry-after comme une estimation et ajoutez un backoff exponentiel avec jitter, afin que plusieurs workers ne réessaient pas simultanément.
• Mettez en cache les données qui changent rarement, comme les nœuds de taxonomie et les profils d’expédition.
• Besoin d’un quota supérieur ? Écrivez à [email protected] en décrivant l’application et en fournissant une estimation QPD/QPS. Etsy demande ces deux éléments.

Pièges de l’API Etsy qui perturbent la synchronisation des fiches et des commandes

Ces points proviennent des tutoriels d’Etsy et correspondent aux endroits où les intégrations échouent après un premier test réussi. L’un d’eux dépend de la date : la gestion des vidéos évolue le 21 octobre 2026.

Questions à poser avant de recruter un prestataire d’intégration Etsy

Ces questions permettent de distinguer un prestataire qui a géré des intégrations Etsy en production d’un prestataire qui s’est contenté de lire la documentation.

1. Quel compte développeur Etsy détiendra l’application et la clé ? Pour une seule boutique, cela devrait être le vôtre, via une Seller App.
2. Quel niveau d’accès prévoyez-vous d’utiliser et que se passe-t-il si Etsy refuse le Commercial Access ?
3. Où les refresh tokens sont-ils stockés et quelles alertes vous préviennent avant qu’une boutique doive se reconnecter ?
4. Comment répartissez-vous le quota de débit par clé et que se passe-t-il en cas de 429 ?
5. Utilisez-vous des webhooks, un rapprochement planifié ou les deux ?
6. Comment mappez-vous les variations, les SKU et les quantités entre Etsy et mon système ?
7. Que se passe-t-il lorsqu’une synchronisation échoue : nouvelle tentative, file d’attente des messages non traitables, alerte humaine ?
8. Que recevrai-je lors de la remise du projet : code source, notes d’environnement, runbook ?

Si vous savez déjà quels systèmes doivent être connectés à Etsy, décrivez-les dans le formulaire de devis gratuit de Netalith. Les projets Etsy sont chiffrés selon leur périmètre : plus votre demande est précise, plus le devis sera fiable.