> ## 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.

# TypeScript

> Un client TypeScript pour l'API StockShift. Ses types sont générés à partir du document OpenAPI de l'API, donc les chemins, les paramètres, les corps et les réponses sont vérifiés à la compilation.

Il fonctionne avec Node.js 20 ou une version ultérieure et dans les navigateurs. Il n'a aucune dépendance d'exécution.

## Installation

```bash theme={null}
npm install @stockshift/sdk
```

## Démarrage rapide

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

```ts theme={null}
import { StockShift } from "@stockshift/sdk";

const stockshift = new StockShift({ token: process.env.STOCKSHIFT_TOKEN! });

await stockshift.post("/catalog/items", {
  body: { sku: "BOLT-M4", name: "M4 hex bolt", type: "stocked", make_or_buy: "buy" },
});

for await (const row of stockshift.paginate("/inventory/stock")) {
  console.log(row.sku, row.location_code, row.available_to_promise);
}
```

## 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 :

```ts theme={null}
const stockshift = new StockShift({ token: () => tokens.current() });
```

Autres options :

| Option | Valeur par défaut | Signification |
| - | - | - |
| `baseUrl` | `https://app.stockshift.io/api/v1` | L'adresse de l'API. |
| `maxRetries` | `2` | Nombre de nouvelles tentatives pour un appel qui peut être répété. |
| `timeout` | `60000` | Millisecondes d'attente pour chaque tentative. |
| `maxRetryAfter` | `60` | Le plus long `Retry-After`, en secondes, qui vaut la peine d'attendre. |
| `headers` | aucune | En-têtes envoyés avec chaque appel. |
| `fetch` | `fetch` global | Le `fetch` à utiliser. |

## Faire des appels

Il y a une méthode par méthode HTTP : `get`, `post`, `put`, `patch` et `delete`. Chacune prend un chemin tel que la référence de l'API l'écrit. Remplissez les paramètres de chemin avec `path`, la chaîne de requête avec `query` et le corps JSON avec `body` :

```ts theme={null}
const { data: item } = await stockshift.get("/catalog/items/{item}", {
  path: { item: "01J8QZ4M..." },
});

const { data: page } = await stockshift.get("/catalog/items", {
  query: { search: "bolt", status: "active" },
});
```

Un appel se résout en corps de la réponse. Une réponse vide se résout en `undefined`, une exportation CSV en son texte et un fichier en `Response` brute.

Chaque schéma de la référence a un type sous `Schemas` :

```ts theme={null}
import type { Schemas } from "@stockshift/sdk";

type Item = Schemas["ItemResource"];
```

## Pagination

Une liste qui peut grandir renvoie une page à la fois. `paginate()` suit les curseurs et produit chaque enregistrement :

```ts theme={null}
for await (const item of stockshift.paginate("/catalog/items", { query: { search: "bolt" } })) {
  console.log(item.sku);
}
```

Pour paginer à la main, renvoyez le `next_cursor` de chaque page dans `query.after` jusqu'à ce qu'il soit `null`.

## 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 personnes et peut changer.

```ts theme={null}
import { ApiError } from "@stockshift/sdk";

try {
  await stockshift.post("/catalog/items", { body });
} catch (error) {
  if (error instanceof ApiError && error.code === "validation_failed") {
    console.log(error.errors); // { sku: ["Another item already has the SKU BOLT-M4."] }
  }
}
```

`ApiError` a aussi `status`, `problem` et `headers`. Un appel qui ne reçoit aucune réponse, parce que le réseau a échoué ou que la tentative a expiré, lève une `ConnectionError`.

## 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 `maxRetryAfter`, 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 d'attente 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 :

```ts theme={null}
await stockshift.post("/integrations/connections/{connection}/channel/stock/push", {
  path: { connection: connectionId },
  idempotencyKey: crypto.randomUUID(),
});
```

Utilisez une nouvelle clé pour chaque modification que vous voulez faire. Les points de terminaison qui respectent 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. `verifyWebhook()` a besoin du corps brut, exactement tel qu'il est arrivé :

```ts theme={null}
import { verifyWebhook, WebhookVerificationError } from "@stockshift/sdk";

export async function POST(request: Request): Promise<Response> {
  try {
    const event = await verifyWebhook({
      payload: await request.text(),
      header: request.headers.get("StockShift-Signature"),
      secret: process.env.STOCKSHIFT_WEBHOOK_SECRET!,
    });
    if (event.type === "inventory.stock.adjusted") {
      console.log(event.data.item_id, event.data.quantity);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(null, { status: 400 });
    }
    throw error;
  }
}
```

Elle refuse une livraison de plus de cinq minutes. Définissez `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 déjà traités.

Pour tester votre propre récepteur, `signWebhook()` signe une charge utile de la même façon que StockShift.

## Versions

La version majeure change quand l'API change 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. `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)
- [Authentification](https://docs.stockshift.io/fr-ca/guides/authentication.md)


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