> ## 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 cliente de TypeScript para la API de StockShift. Sus tipos se generan a partir del documento OpenAPI de la API, así que las rutas, los parámetros, los cuerpos y las respuestas se comprueban al compilar.

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

## Instalación

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

## Inicio rápido

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

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

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

```ts theme={null}
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`:

```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" },
});
```

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

```ts theme={null}
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:

```ts theme={null}
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.

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

```ts theme={null}
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ó:

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

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.


## Related topics

- [StockShift para desarrolladores](https://docs.stockshift.io/es/index.md)
- [SDK](https://docs.stockshift.io/es/sdks/index.md)
- [Guarda el borrador de una automatización](https://docs.stockshift.io/es/api-reference/automatizaciones/guarda-el-borrador-de-una-automatización.md)


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