TypeScript

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

npm install @stockshift/sdk

Démarrage rapide

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

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 :

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 :

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 :

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 :

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.

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 :

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

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.

SDK

Cadriciels

Installation

Démarrage rapide

Authentification

Faire des appels

Erreurs

Nouvelles tentatives et clés d’idempotence

Webhooks

Versions

​Installation

​Démarrage rapide

​Authentification

​Faire des appels

​Pagination

​Erreurs

​Nouvelles tentatives et clés d’idempotence

​Webhooks

​Versions

Installation

Démarrage rapide

Authentification

Faire des appels

Pagination

Erreurs

Nouvelles tentatives et clés d’idempotence

Webhooks

Versions