Pedidos

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

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

Permisos Requeridos

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

Mapeo HTTP

Método	Verbo HTTP	Ruta
`list(params?)`	GET	`/orders`
`get(id)`	GET	`/orders/:id`
`updateStatus(id, data)`	PATCH	`/orders/:id`
`updatePaymentStatus(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.data.status);
console.log(order.data.payment_status);
console.log(order.data.total);
console.log(order.data.currency);

updateStatus

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

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

// Move an order into fulfilment
await client.orders.updateStatus("order_123", {
  status: "in_progress",
});

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

Valores de estado: pending, confirmed, in_progress, completed, cancelled, returned.

updatePaymentStatus

Actualiza el estado de pago de un pedido.

// Mark an order as paid
await client.orders.updatePaymentStatus("order_123", {
  payment_status: "paid",
});

// Mark an order as refunded
await client.orders.updatePaymentStatus("order_123", {
  payment_status: "refunded",
});

Valores de payment_status: pending, paid, refunded, failed.

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 { data: order } = await client.orders.get(orderId);

  if (order.status !== "confirmed") {
    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: "in_progress" });
}

Manejo de Errores

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

try {
  await client.orders.updateStatus("order_999", { status: "completed" });
} 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