Ordenes

#Listar ordenes

GET /api/v1/orders

Devuelve una lista paginada de las ordenes de tu tienda, ordenadas por fecha de creación (más recientes primero).

#Parametros de query

#Valores de status

#Ejemplo con curl

# Todos los pedidos
curl "https://karrito.shop/api/v1/orders?limit=20" \
  -H "Authorization: Bearer krt_live_a1b2c3d4e5f6g7h8i9j0"

# Solo pedidos pendientes
curl "https://karrito.shop/api/v1/orders?status=pending" \
  -H "Authorization: Bearer krt_live_a1b2c3d4e5f6g7h8i9j0"

#Ejemplo con JavaScript

const response = await fetch("https://karrito.shop/api/v1/orders?status=pending", {
  headers: {
    "Authorization": "Bearer krt_live_a1b2c3d4e5f6g7h8i9j0"
  }
});

const { data, total } = await response.json();
console.log(`${total} pedidos pendientes`);

#Respuesta

{
  "data": [
    {
      "id": "clxo1a2b3c4d5e6f7g8h9",
      "orderNumber": "KRT-001042",
      "status": "pending",
      "customerName": "Maria Rodriguez",
      "customerPhone": "+18095551234",
      "items": [
        {
          "productName": "Camisa azul clasica",
          "variantName": "Talla M",
          "quantity": 2,
          "unitPrice": 25.00,
          "subtotal": 50.00
        },
        {
          "productName": "Pantalon negro slim",
          "variantName": null,
          "quantity": 1,
          "unitPrice": 40.00,
          "subtotal": 40.00
        }
      ],
      "total": 90.00,
      "notes": "Entregar despues de las 5pm",
      "createdAt": "2026-03-17T16:45:00.000Z"
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0
}

#Obtener una orden

GET /api/v1/orders/:id

Devuelve una orden individual con todos sus detalles, incluyendo datos del cliente e items.

#Ejemplo con curl

curl "https://karrito.shop/api/v1/orders/clxo1a2b3c4d5e6f7g8h9" \
  -H "Authorization: Bearer krt_live_a1b2c3d4e5f6g7h8i9j0"

#Respuesta

{
  "data": {
    "id": "clxo1a2b3c4d5e6f7g8h9",
    "orderNumber": "KRT-001042",
    "status": "pending",
    "customerName": "Maria Rodriguez",
    "customerPhone": "+18095551234",
    "customerAddress": "Calle Principal #45, Santo Domingo",
    "items": [
      {
        "productId": "clx1a2b3c4d5e6f7g8h9i0",
        "productName": "Camisa azul clasica",
        "variantId": "clxv4d5e6f7g8h9i0j1k2",
        "variantName": "Talla M",
        "quantity": 2,
        "unitPrice": 25.00,
        "subtotal": 50.00
      },
      {
        "productId": "clx2b3c4d5e6f7g8h9i0j1",
        "productName": "Pantalon negro slim",
        "variantId": null,
        "variantName": null,
        "quantity": 1,
        "unitPrice": 40.00,
        "subtotal": 40.00
      }
    ],
    "total": 90.00,
    "notes": "Entregar despues de las 5pm",
    "shippingOption": {
      "name": "Envio a domicilio",
      "price": 150.00
    },
    "createdAt": "2026-03-17T16:45:00.000Z",
    "updatedAt": "2026-03-17T16:45:00.000Z"
  }
}

#Crear una orden

POST /api/orders

Este es un endpoint publico que no requiere autenticación. Es el mismo que usa el catálogo de Karrito cuando un cliente hace un pedido. Puedes usarlo para crear ordenes desde tu propia app o sitio web.

Nota: Este endpoint vive en /api/orders (sin el prefijo /v1) porque es publico.

#Body (JSON)

#Ejemplo con curl

curl -X POST "https://karrito.shop/api/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "clxs1a2b3c4d5e6f7g8h9",
    "name": "Carlos Mejia",
    "phone": "+18095559876",
    "address": "Av. Winston Churchill #42, Piantini",
    "items": [
      { "variantId": "clxv4d5e6f7g8h9i0j1k2", "quantity": 2 },
      { "variantId": "clxv5e6f7g8h9i0j1k2l3", "quantity": 1 }
    ],
    "notes": "Llamar antes de entregar"
  }'

#Ejemplo con JavaScript

const order = await fetch("https://karrito.shop/api/orders", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    storeId: "clxs1a2b3c4d5e6f7g8h9",
    name: "Carlos Mejia",
    phone: "+18095559876",
    items: [
      { variantId: "clxv4d5e6f7g8h9i0j1k2", quantity: 2 },
      { variantId: "clxv5e6f7g8h9i0j1k2l3", quantity: 1 }
    ]
  })
});

const { id, orderNumber } = await order.json();
console.log(`Orden creada: ${orderNumber}`);

#Respuesta exitosa (201 Created)

{
  "id": "clxo2b3c4d5e6f7g8h9i0",
  "orderNumber": "KRT-001043"
}

#Deduplicación

El endpoint rechaza ordenes duplicadas dentro de una ventana de 5 minutos. Si el mismo cliente (mismo teléfono) envía los mismos items en ese periodo, recibes un 409 Conflict:

{
  "error": "Orden duplicada detectada. Intenta de nuevo en unos minutos.",
  "code": "DUPLICATE_ORDER"
}

#Schema de orden

#Scopes requeridos

• orders:read para GET (listar y obtener)
• orders:write para actualizar estado
• POST /api/orders no requiere autenticación

#Siguiente paso

Configura webhooks para recibir notificaciones en tiempo real cuando llegan nuevos pedidos.