Ordenes

#Listar pedidos

GET /api/v1/orders

Requiere llave válida, permiso read y acceso a la tienda. La respuesta contiene { data, total, limit, offset }.

curl "https://karrito.app/api/v1/orders?kind=real&status=PENDING&limit=20"   -H "Authorization: Bearer $KARRITO_API_KEY"

Si analizas ventas reales, usa kind=real: el listado predeterminado también puede contener pedidos de prueba.

#Consultar un pedido

GET /api/v1/orders/ID_DEL_PEDIDO

Devuelve { data: pedido }. Incluye información de cliente e ítems, totales, moneda, método de pago/envío y notas. El detalle añade campos como dirección, notas internas y datos del checkout. No publiques esa información privada en ejemplos o conversaciones públicas.

orderNumber es un número, no una cadena KRT-.... Los importes decimales pueden llegar serializados como texto; no supongas que todos son números JavaScript. customer puede ser null y cada ítem puede incluir variantTitle.

#Cambiar el estado

PUT /api/v1/orders/ID_DEL_PEDIDO

La escritura requiere orders:write. El servidor valida el cuerpo y la transición de estado; no todas las transiciones son válidas. Consulta el contrato de esa operación y revisa el resultado antes de darla por completada.

Estados de la API: pendiente (PENDING), completado (COMPLETED) y cancelado (CANCELLED). Marcar un pedido completado no prueba un cobro externo ni una entrega física.

#Checkout público y duplicados

El checkout público usa un flujo diferente de la API de administración. No utilices un ejemplo genérico de creación de pedidos como sustituto del checkout de tu tienda: sus campos y validaciones son distintos.

El checkout puede reconocer un pedido reciente repetido y devolver su identificación con deduplicated: true. No se promete que todo pedido repetido produzca 409, ni que un reintento nunca pueda duplicar una operación. Comprueba el resultado antes de repetir el envío.

Consulta Checkout por WhatsApp y Gestionar pedidos.