TypeScript

Funciona en Node.js 20 o posterior y en navegadores. No tiene dependencias de tiempo de ejecución.

Instalación

npm install @stockshift/sdk

Inicio rápido

Crea un artículo y luego lista las existencias disponibles:

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);
}

Autenticación

Pasa una clave de API o un token de acceso OAuth como token. Crea una clave de API en la app, en Configuración > Acceso > Claves de API. La clave actúa como el miembro que la creó, y cada llamada necesita tanto el permiso del miembro como uno de los alcances de la clave. Para un token OAuth que vence, pasa una función. El cliente la llama antes de cada solicitud:

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

Otras opciones:

Opción	Valor predeterminado	Significado
`baseUrl`	`https://app.stockshift.io/api/v1`	Dónde está la API.
`maxRetries`	`2`	Reintentos para una llamada que se puede reintentar.
`timeout`	`60000`	Milisegundos de espera para cada intento.
`maxRetryAfter`	`60`	El `Retry-After` más largo, en segundos, que vale la pena esperar.
`headers`	ninguno	Encabezados que se envían en cada llamada.
`fetch`	`fetch` global	El `fetch` que se usa.

Hacer llamadas

Hay un método por cada método HTTP: get, post, put, patch y delete. Cada uno recibe una ruta tal como la escribe la referencia de la API. Completa los parámetros de ruta con path, la cadena de consulta con query y el cuerpo JSON con 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" },
});

Una llamada se resuelve con el cuerpo de la respuesta. Una respuesta vacía se resuelve con undefined, una exportación CSV con su texto y un archivo con la Response sin procesar. Cada esquema de la referencia tiene un tipo en Schemas:

import type { Schemas } from "@stockshift/sdk";

type Item = Schemas["ItemResource"];

Paginación

Una lista que puede crecer devuelve una página a la vez. paginate() sigue los cursores y entrega cada registro:

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

Para paginar a mano, envía el next_cursor de cada página como query.after hasta que sea null.

Errores

Una llamada fallida lanza un ApiError que contiene el cuerpo de detalles del problema de RFC 9457. Decide según code, que es estable. detail está escrito para personas y puede cambiar.

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 también tiene status, problem y headers. Una llamada que no recibe respuesta, porque falló la red o el intento agotó el tiempo de espera, lanza un ConnectionError.

Reintentos y claves de idempotencia

El cliente reintenta un 429 después del tiempo que indica Retry-After. Lo hace con todos los métodos, porque la API no ejecutó la llamada. Si Retry-After es mayor que maxRetryAfter, lanza un error en lugar de esperar. Un 5xx o una falla de red se reintenta para GET, PUT y DELETE, con una breve espera entre intentos. Un POST o PATCH solo se reintenta cuando le das una clave de idempotencia, para que un reintento no pueda hacer el cambio dos veces:

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

Usa una clave nueva para cada cambio que quieras hacer. Los endpoints que respetan la clave lo indican en la referencia de la API.

Webhooks

Revisa el encabezado StockShift-Signature antes de confiar en una entrega. verifyWebhook() necesita el cuerpo sin procesar, exactamente como llegó:

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;
  }
}

Rechaza una entrega de más de cinco minutos de antigüedad. Define tolerance, en segundos, para cambiarlo. Los reintentos de un evento conservan su id, así que guárdalo y omite los eventos que ya procesaste. Para probar tu propio receptor, signWebhook() firma un payload igual que StockShift.

Versiones

La versión mayor cambia cuando la API cambia de una forma que puede romper tu código, como un campo eliminado o un parámetro obligatorio nuevo. Los endpoints y campos nuevos llegan en versiones menores. API_VERSION contiene la versión de la referencia de la API con la que se compiló el paquete.

SDK

Frameworks

Instalación

Inicio rápido

Autenticación

Hacer llamadas

Paginación

Errores

Reintentos y claves de idempotencia

Webhooks

Versiones

​Instalación

​Inicio rápido

​Autenticación

​Hacer llamadas

​Paginación

​Errores

​Reintentos y claves de idempotencia

​Webhooks

​Versiones

Instalación

Inicio rápido

Autenticación

Hacer llamadas

Paginación

Errores

Reintentos y claves de idempotencia

Webhooks

Versiones