Pedidos

Lee datos de pedidos y actualiza su estado con client.orders — listar, obtener, updateStatus y contar.

client.orders permite que tu plugin lea datos de pedidos y actualice su estado. Los pedidos son de solo lectura excepto para las transiciones de estado, que requieren el permiso write:orders.

Permisos Requeridos

Operación	Permiso requerido
`list`, `get`, `count`	`read:orders`
`updateStatus`	`write:orders`

Mapeo HTTP

Método	Verbo HTTP	Ruta
`list(params?)`	GET	`/orders`
`get(id)`	GET	`/orders/:id`
`updateStatus(id, data)`	PATCH	`/orders/:id`
`count(status?)`	GET	`/orders/count`

Métodos

list

Obtiene una lista paginada de pedidos, con filtro opcional por estado.

const { data, pagination } = await client.orders.list({
  page: 1,
  per_page: 25,
  status: "pending", // Filter by order status
});

data.forEach((order) => {
  console.log(`Order ${order.id}: ${order.status}`);
});

get

Obtiene un único pedido por su ID, incluyendo líneas de pedido, cliente y datos de envío.

const order = await client.orders.get("order_123");

console.log(order.status);
console.log(order.total);
console.log(order.customer?.name);
console.log(order.items.length);

updateStatus

Transiciona un pedido a un nuevo estado. Solo se aceptan transiciones de estado válidas.

// Mark an order as shipped
await client.orders.updateStatus("order_123", {
  status: "shipped",
});

// Cancel an order
await client.orders.updateStatus("order_123", {
  status: "cancelled",
});

Valores de estado comunes: pending, processing, shipped, delivered, cancelled.

count

Obtiene el número total de pedidos, con filtro opcional por estado.

// Count all orders
const total = await client.orders.count();

// Count pending orders only
const pending = await client.orders.count("pending");

console.log(`${pending} pedidos esperando procesamiento`);

Patrón Típico de Plugin

La mayoría de los plugins de cumplimiento o logística siguen este patrón:

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

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

async function fulfillOrder(orderId: string): Promise<void> {
  // 1. Fetch order details
  const order = await client.orders.get(orderId);

  if (order.status !== "processing") {
    throw new Error(`Cannot fulfil order with status: ${order.status}`);
  }

  // 2. Send to fulfilment provider
  await myFulfilmentProvider.ship(order);

  // 3. Update order status in the store
  await client.orders.updateStatus(orderId, { status: "shipped" });
}

Manejo de Errores

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

try {
  await client.orders.updateStatus("order_999", { status: "shipped" });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Order not found: ${error.resourceId}`);
  } else if (error instanceof ValidationError) {
    // Invalid status transition
    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.

On this page