> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockshift.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> Un client Python pour l'API StockShift. Il est généré à partir du document OpenAPI de l'API. Il a une méthode pour chaque opération et un modèle typé pour chaque réponse.

Il nécessite Python 3.10 ou plus récent. Il repose sur httpx et Pydantic v2, et il est livré avec des annotations de type complètes qui passent mypy et pyright en mode strict.

## Installation

```bash theme={null}
pip install stockshift
```

## Démarrage rapide

Créez un article, puis listez le stock en main :

```python theme={null}
import os

from stockshift import StockShift

with StockShift(token=os.environ["STOCKSHIFT_TOKEN"]) as stockshift:
    stockshift.catalog.create_item(
        sku="BOLT-M4", name="M4 hex bolt", type="stocked", make_or_buy="buy"
    )

    for row in stockshift.inventory.iter_stock_on_hand():
        print(row.sku, row.location_code, row.available_to_promise)
```

`AsyncStockShift` a les mêmes méthodes pour asyncio et Trio. Attendez chaque appel avec `await` et parcourez les pages avec `async for` :

```python theme={null}
from stockshift import AsyncStockShift

async with AsyncStockShift(token=os.environ["STOCKSHIFT_TOKEN"]) as stockshift:
    async for item in stockshift.catalog.iter_items(search="bolt"):
        print(item.sku)
```

## Authentification

Passez une clé d'API ou un jeton d'accès OAuth dans `token`. 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 :

```python theme={null}
stockshift = StockShift(token=lambda: tokens.current())
```

Autres arguments :

| Argument | Valeur par défaut | Signification |
| - | - | - |
| `base_url` | `https://app.stockshift.io/api/v1` | L'adresse de l'API. |
| `max_retries` | `2` | Nombre de nouvelles tentatives pour un appel qui peut être répété. |
| `timeout` | `60` | Secondes d'attente pour chaque tentative. |
| `max_retry_after` | `60` | Le plus long `Retry-After`, en secondes, qui vaut la peine d'attendre. |
| `headers` | aucun | En-têtes envoyés avec chaque appel. |
| `http_client` | un nouveau | Un `httpx.Client` ou `httpx.AsyncClient` pour l'envoi. |

`with_options()` renvoie une copie avec d'autres paramètres qui partage les connexions :

```python theme={null}
stockshift.with_options(timeout=120, max_retries=5).catalog.list_units_of_measure()
```

## Faire des appels

Chaque domaine de l'API est un attribut, comme `catalog` 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é :

```python theme={null}
item = stockshift.catalog.get_item("01J8QZ4M...")
print(item.sku)

page = stockshift.catalog.list_items(search="bolt", status="active")
```

La docstring de chaque méthode nomme son chemin, comme `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` :

```python theme={null}
response = stockshift.request("GET", "/catalog/items/{item}", path_params={"item": item.id})
```

## Pagination

Une liste qui peut grossir renvoie une page à la fois. Chaque liste paginée a une deuxième méthode qui commence par `iter_`. Elle suit les curseurs et produit chaque enregistrement :

```python theme={null}
for item in stockshift.catalog.iter_items(search="bolt"):
    print(item.sku)
```

Elle récupère la page suivante seulement quand les enregistrements de la précédente sont épuisés. Pour paginer vous-même, renvoyez le `next_cursor` de chaque page dans `after` jusqu'à ce qu'il soit `None`.

## Erreurs

Un appel qui échoue lève une `APIError` 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.

```python theme={null}
from stockshift import APIError

try:
    stockshift.catalog.create_item(
        sku="BOLT-M4", name="M4 hex bolt", type="stocked", make_or_buy="buy"
    )
except APIError as error:
    if error.code == "validation_failed":
        print(error.errors)  # {'sku': ['Another item already has the SKU BOLT-M4.']}
```

`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 un `429` 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 :

```python theme={null}
import uuid

stockshift.integrations.push_stock_now(connection_id, idempotency_key=str(uuid.uuid4()))
```

Utilisez une nouvelle clé pour chaque modification que vous voulez faire. Les points de terminaison qui tiennent compte de la clé l'indiquent dans la référence de l'API.

## Webhooks

Vérifiez l'en-tête `StockShift-Signature` avant de faire confiance à une livraison. `verify_webhook()` a besoin du corps brut, exactement tel qu'il est arrivé :

```python theme={null}
from stockshift import WebhookVerificationError, verify_webhook
from stockshift.models import InventoryStockAdjustedEvent


def receive(body: bytes, signature: str | None) -> int:
    try:
        event = verify_webhook(body, signature, os.environ["STOCKSHIFT_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return 400

    if isinstance(event, InventoryStockAdjustedEvent):
        print(event.data.item_id, event.data.quantity)
    return 204
```

Elle renvoie un modèle pour chaque type d'événement, ou un `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.


## Related topics

- [StockShift pour les développeurs](https://docs.stockshift.io/fr-ca/index.md)
- [SDK](https://docs.stockshift.io/fr-ca/sdks/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.