Ordenes

#Listar ordenes

GET /api/v1/orders

Devuelve una lista paginada de las ordenes de tu tienda, ordenadas por fecha de creacion (mas recientes primero).

#Parametros de query

Parametro	Tipo	Default	Descripcion
limit	number	50	Resultados por pagina (max 100)
offset	number	0	Resultados a saltar
status	string	-	Filtrar por estado (opcional)

#Valores de status

Status	Descripcion
pending	Pedido recibido, sin confirmar
confirmed	Pedido confirmado por el vendedor
shipped	Pedido enviado
delivered	Pedido entregado
cancelled	Pedido cancelado

#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 autenticacion. Es el mismo que usa el catalogo 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)

Campo	Tipo	Requerido	Descripcion
storeId	string	Si	ID de la tienda
name	string	Si	Nombre del cliente
phone	string	Si	Telefono del cliente (formato E.164)
address	string	No	Direccion de entrega
items	array	Si	Productos del pedido
items[].variantId	string	Si	ID de la variante del producto
items[].quantity	number	Si	Cantidad (min 1)
notes	string	No	Notas adicionales del cliente
shippingOptionId	string	No	ID de la opcion de envio seleccionada

#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"
}

#Deduplicacion

El endpoint rechaza ordenes duplicadas dentro de una ventana de 5 minutos. Si el mismo cliente (mismo telefono) envia 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

Campo	Tipo	Descripcion
id	string	Identificador unico (CUID)
orderNumber	string	Numero de orden legible (KRT-XXXXXX)
status	string	Estado actual del pedido
customerName	string	Nombre del cliente
customerPhone	string	Telefono del cliente
customerAddress	string | null	Direccion de entrega
items	OrderItem[]	Lista de productos del pedido
total	number	Total del pedido en la moneda de la tienda
notes	string | null	Notas adicionales del cliente
shippingOption	object | null	Opcion de envio seleccionada
createdAt	string	Fecha de creacion (ISO 8601)
updatedAt	string	Fecha de ultima modificacion (ISO 8601)

#Scopes requeridos

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

#Siguiente paso

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