Inventario

Lee y ajusta los niveles de inventario de productos con client.inventory — obtener stock actual y aplicar ajustes de cantidad.

client.inventory permite que tu plugin lea y ajuste los niveles de inventario para productos individuales. Esto es útil para plugins que sincronizan stock con un almacén externo, sistema POS o proveedor de cumplimiento.

Permisos Requeridos

Operación	Permiso requerido
`get`	`read:inventory`
`adjust`	`write:inventory`

Mapeo HTTP

Método	Verbo HTTP	Ruta
`get(productId)`	GET	`/products/:id/inventory`
`adjust(productId, data)`	PATCH	`/products/:id/inventory`

Métodos

get

Obtiene los niveles de inventario actuales de un producto, incluyendo inventario por variante cuando existen.

const { data } = await client.inventory.get("758517075954");

console.log(data.product_id);      // "758517075954"
console.log(data.stock_quantity);   // Cantidad actual en stock
console.log(data.sku);             // Identificador SKU
console.log(data.track_inventory); // Si el rastreo de inventario está activo
console.log(data.variants);        // Array de inventario por variante

La respuesta incluye un array variants con niveles de inventario por variante:

const { data } = await client.inventory.get("758517075954");

for (const variant of data.variants) {
  console.log(`${variant.variant_type}: ${variant.variant_value}`);
  console.log(`  Stock: ${variant.stock_quantity}`);
  console.log(`  Rastreado: ${variant.track_inventory}`);
}

adjust

Aplica un delta de cantidad al inventario de un producto. Los valores positivos aumentan el stock; los negativos lo reducen. El campo reason es texto libre que se almacena en el registro de auditoría.

// Reducir stock en 5 (ej. después de un pedido al por mayor)
await client.inventory.adjust("758517075954", {
  quantity: -5,
  reason: "Bulk order fulfilment",
});

// Aumentar stock en 100 (ej. después de reabastecimiento)
await client.inventory.adjust("758517075954", {
  quantity: 100,
  reason: "Warehouse restock — shipment #WH-20241015",
});

// Razón personalizada — usa cualquier string
await client.inventory.adjust("758517075954", {
  quantity: -2,
  reason: "Promotional giveaway — Instagram campaign",
});

El campo reason acepta cualquier string no vacío. Valores comunes incluyen restock, correction, damaged, received, returned, pero puedes usar cualquier razón que se ajuste a tu flujo de trabajo.

Patrón de Sincronización

Un patrón común para plugins de sincronización de inventario:

import { WhataloClient } from "@whatalo/plugin-sdk";

const client = new WhataloClient({ apiKey: process.env.WHATALO_API_KEY! });

async function syncInventoryFromWarehouse(
  productId: string,
  warehouseQuantity: number
): Promise<void> {
  // 1. Leer stock actual en la tienda
  const { data } = await client.inventory.get(productId);

  // 2. Calcular el delta
  const delta = warehouseQuantity - data.stock_quantity;

  if (delta === 0) {
    return; // Ya sincronizado, nada que hacer
  }

  // 3. Aplicar el ajuste
  await client.inventory.adjust(productId, {
    quantity: delta,
    reason: `Warehouse sync — warehouse qty: ${warehouseQuantity}`,
  });

  console.log(
    `Adjusted ${productId} by ${delta > 0 ? "+" : ""}${delta} units`
  );
}

Manejo de Errores

import { NotFoundError, ValidationError } from "@whatalo/plugin-sdk";

try {
  await client.inventory.adjust("999999999999", {
    quantity: -10,
    reason: "test",
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    // El producto no existe
    console.log(`Product not found: ${error.resourceId}`);
  } else if (error instanceof ValidationError) {
    // ej. inventario no está rastreado, o el ajuste llevaría la cantidad
    // por debajo de cero y la tienda no permite stock negativo
    error.fieldErrors.forEach((e) => console.log(`${e.field}: ${e.message}`));
  } else {
    throw error;
  }
}

Consulta Errores y Límites de Tasa para la referencia completa de clases de error.