Installation
Démarrage rapide
Créez un article, puis listez le stock en main :AsyncStockShift a les mêmes méthodes pour asyncio et Trio. Attendez chaque appel avec await et parcourez les pages avec async for :
Authentification
Passez une clé d’API ou un jeton d’accès OAuth danstoken. Créez une clé d’API dans l’application sous Paramètres > Accès > Clés d’API. La clé agit au nom du membre qui l’a créée, et un appel exige à la fois l’autorisation du membre et l’une des portées de la clé.
Pour un jeton OAuth qui expire, passez une fonction. Le client l’appelle avant chaque requête. AsyncStockShift accepte aussi une fonction coroutine :
with_options() renvoie une copie avec d’autres paramètres qui partage les connexions :
Faire des appels
Chaque domaine de l’API est un attribut, commecatalog ou inventory, et chaque opération est une méthode de cet attribut. Les paramètres de chemin viennent en premier. Tout le reste est un argument nommé :
GET /catalog/items/{item}, et reprend la référence de l’API.
Un appel renvoie un modèle Pydantic de stockshift.models, ou une liste de modèles. Une réponse vide renvoie None, un export CSV son texte et un fichier la httpx.Response. Un champ que l’API ajoute après cette version est conservé dans le modèle, et vous pouvez le lire dans model_extra.
Un champ facultatif du corps que vous omettez n’est pas envoyé. Passez None pour envoyer null, ce qui efface le champ.
Pour appeler un chemin qui n’a pas de méthode dans cette version, utilisez request(). Elle renvoie la httpx.Response :
Pagination
Une liste qui peut grossir renvoie une page à la fois. Chaque liste paginée a une deuxième méthode qui commence pariter_. Elle suit les curseurs et produit chaque enregistrement :
next_cursor de chaque page dans after jusqu’à ce qu’il soit None.
Erreurs
Un appel qui échoue lève uneAPIError qui contient le corps des détails du problème RFC 9457. Basez votre logique sur code, qui est stable. detail est rédigé pour des humains et peut changer.
APIError a aussi status, problem, headers et response. Un appel qui n’obtient aucune réponse, parce que le réseau a fait défaut ou que la tentative a expiré, lève une APIConnectionError. Les deux héritent de StockShiftError, qui est aussi levée pour une réponse que cette version ne sait pas lire.
Nouvelles tentatives et clés d’idempotence
Le client réessaie un429 après le délai indiqué dans Retry-After. Il le fait pour toutes les méthodes, parce que l’API n’a pas exécuté l’appel. Si Retry-After dépasse max_retry_after, il lève plutôt une erreur.
Un 5xx ou une défaillance réseau est réessayé pour GET, PUT et DELETE, avec un court délai progressif. Un POST ou un PATCH n’est réessayé que si vous lui donnez une clé d’idempotence, pour qu’une nouvelle tentative ne puisse pas appliquer la modification deux fois :
Webhooks
Vérifiez l’en-têteStockShift-Signature avant de faire confiance à une livraison. verify_webhook() a besoin du corps brut, exactement tel qu’il est arrivé :
UnknownWebhookEvent pour un type ajouté après cette version. Elle refuse une livraison de plus de cinq minutes. Passez tolerance, en secondes, pour changer ce délai. Les nouvelles tentatives d’un événement gardent son id : conservez-le et ignorez les événements que vous avez déjà traités.
Pour tester votre propre récepteur, sign_webhook() signe une charge utile de la même façon que StockShift.
Versions
La version majeure change quand l’API évolue d’une façon qui peut briser votre code, comme un champ retiré ou un nouveau paramètre obligatoire. Les nouveaux points de terminaison et champs arrivent dans des versions mineures.stockshift.API_VERSION contient la version de la référence de l’API à partir de laquelle le paquet a été construit.