Gestión de Pedidos

Descripción General

Los pedidos representan compras realizadas en una tienda Whatalo. La API de Orders te permite obtener detalles de pedidos, actualizar el estado del pedido, actualizar el estado de pago, añadir notas internas e integrar con sistemas de fulfillment.

Los pedidos son creados por los clientes a través del storefront. La API te permite leer y actualizar pedidos, no crearlos directamente.

Listar Pedidos

curl -X GET https://api.whatalo.com/v1/orders \
  -H "X-API-Key: wk_live_your_key_here"

Scope requerido: read:orders

Obtener un Pedido

curl -X GET https://api.whatalo.com/v1/orders/ord_abc123 \
  -H "X-API-Key: wk_live_your_key_here"

Obtener Artículos del Pedido

Obtén los line items de un pedido específico:

curl -X GET https://api.whatalo.com/v1/orders/ord_abc123/items \
  -H "X-API-Key: wk_live_your_key_here"

Actualizar Pedidos

PATCH /v1/orders/{id} permite actualizar tres campos mutables:

status
payment_status
internal_notes

Puedes enviar uno o varios de estos campos en la misma solicitud. Fuera de estos campos, el pedido es de solo lectura.

Actualizar Estado del Pedido

Actualiza el estado del ciclo de vida del pedido con una solicitud PATCH:

curl -X PATCH https://api.whatalo.com/v1/orders/ord_abc123 \
  -H "X-API-Key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

Scope requerido: write:orders

Valores soportados para status:

pending | confirmed | in_progress | completed | cancelled | returned

Solo se aceptan transiciones válidas. Por ejemplo, un pedido puede pasar de pending a confirmed, pero no de completed a pending.

Actualizar Estado de Pago

Actualiza el estado de pago sin cambiar el ciclo de vida del pedido:

curl -X PATCH https://api.whatalo.com/v1/orders/ord_abc123 \
  -H "X-API-Key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_status": "paid"
  }'

Valores soportados para payment_status:

pending | paid | refunded | failed

Actualizar Notas Internas

Guarda una nota interna del comerciante en el pedido:

curl -X PATCH https://api.whatalo.com/v1/orders/ord_abc123 \
  -H "X-API-Key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_notes": "Entregado al transportista"
  }'

Ciclo de Vida del Pedido

Los pedidos en Whatalo siguen este ciclo de vida:

pending → confirmed → in_progress → completed
                                   → returned
         → cancelled

Valores de payment_status: pending | paid | refunded | failed

Patrones Comunes

Integración de Fulfillment

Marca pedidos como en progreso cuando tu sistema de fulfillment los recoge:

async function markInProgress(orderId) {
  const response = await fetch(
    `https://api.whatalo.com/v1/orders/${orderId}`,
    {
      method: 'PATCH',
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        status: 'in_progress',
        internal_notes: 'Picked up by fulfillment system'
      })
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to update order: ${response.status}`);
  }

  return response.json();
}

Conteo de Pedidos para Dashboard

curl -X GET "https://api.whatalo.com/v1/orders/count?status=pending" \
  -H "X-API-Key: wk_live_your_key_here"

On this page