Checkout

El dominio de Checkout gestiona los carritos de compra y el flujo de conversión a orden. Tiene dos entidades principales: Cart (carrito) y Checkout (proceso de pago).

Carrito (Cart)

Crear carrito

POST /api/v1/checkout/carts

Campo	Tipo	Requerido	Descripción
customer_id	uuid	No	ID del cliente (si está autenticado)
session_id	string	No	ID de sesión anónima
currency	string	No	Moneda del carrito (default: moneda del tenant)

{
  "session_id": "sess_abc123",
  "currency": "PEN"
}

Respuesta 201 Created:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "...",
    "session_id": "sess_abc123",
    "line_items": [],
    "item_count": 0,
    "subtotal": 0,
    "expires_at": "2026-07-23T12:00:00Z",
    "created_at": "2026-07-22T12:00:00Z",
    "updated_at": "2026-07-22T12:00:00Z"
  }
}

Obtener carrito

GET /api/v1/checkout/carts/:id

Respuesta 200 OK: misma estructura que crear.

Agregar item al carrito

POST /api/v1/checkout/carts/:id/items

Campo	Tipo	Requerido	Descripción
variant_id	uuid	Sí	ID de la variante del producto
product_id	uuid	Sí	ID del producto
title	string	Sí	Nombre del producto
variant_title	string	No	Título de la variante
sku	string	No	SKU
quantity	int	Sí	Cantidad (mínimo 1)
unit_price	int64	Sí	Precio unitario en céntimos
requires_shipping	bool	No	Requiere envío
image_url	string	No	URL de imagen del producto
weight_grams	int	No	Peso en gramos
taxable	bool	No	Está sujeto a impuestos

{
  "variant_id": "...",
  "product_id": "...",
  "title": "Camiseta básica",
  "variant_title": "Negro / M",
  "sku": "CAM-NEG-M",
  "quantity": 2,
  "unit_price": 4500,
  "image_url": "https://cdn.example.com/camiseta.jpg"
}

Actualizar cantidad

PUT /api/v1/checkout/carts/:id/items/:variant_id

{
  "quantity": 3
}

Eliminar item

DELETE /api/v1/checkout/carts/:id/items/:variant_id

Aplicar cupón

POST /api/v1/checkout/carts/:id/coupon

{
  "code": "VERANO20"
}

Checkout

Iniciar checkout

Crea un checkout a partir de un carrito existente. El carrito se "congela" y ya no se puede modificar.

POST /api/v1/checkout/checkouts

Campo	Tipo	Requerido	Descripción
cart_id	uuid	Sí	ID del carrito
customer_id	uuid	No	ID del cliente
email	string	Sí	Email de contacto
currency	string	No	Moneda

{
  "cart_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "currency": "PEN"
}

Respuesta 201 Created:

{
  "data": {
    "id": "...",
    "cart_id": "...",
    "email": "[email protected]",
    "status": "pending",
    "line_items": [...],
    "subtotal": 9000,
    "shipping_total": 0,
    "discount_total": 0,
    "tax_total": 0,
    "total": 9000,
    "currency": "PEN"
  }
}

Obtener checkout

GET /api/v1/checkout/checkouts/:id

Actualizar envío

Configura las direcciones de envío y facturación, y la tarifa de envío seleccionada.

PUT /api/v1/checkout/checkouts/:id/shipping

{
  "shipping_address": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "address1": "Av. Larco 123",
    "city": "Lima",
    "province": "Lima",
    "country_code": "PE",
    "zip": "15001",
    "phone": "+51987654321"
  },
  "billing_address": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "address1": "Av. Larco 123",
    "city": "Lima",
    "province": "Lima",
    "country_code": "PE",
    "zip": "15001"
  },
  "shipping_rate": {
    "carrier": "Olva",
    "service": "Estándar",
    "price": 1500
  }
}

Completar checkout

Finaliza el checkout y genera la orden. Requiere que el pago esté confirmado.

POST /api/v1/checkout/checkouts/:id/complete

{
  "order_id": "uuid-de-la-orden-creada"
}

Abandonar checkout

Marca el checkout como abandonado. Se usa para tracking de carritos abandonados.

POST /api/v1/checkout/checkouts/:id/abandon

Estados del Checkout

Estado	Descripción
pending	Checkout creado, esperando datos de envío
shipping_set	Direcciones configuradas
payment_pending	Esperando confirmación de pago
completed	Checkout completado, orden creada
abandoned	Checkout abandonado por el comprador

Errores

Código	HTTP	Descripción
TENANT_REQUIRED	400	Falta el contexto de tenant
INVALID_ID	400	ID de carrito/checkout inválido
INVALID_REQUEST	400	Body de request inválido
CART_NOT_FOUND	404	Carrito no encontrado
CHECKOUT_NOT_FOUND	404	Checkout no encontrado
ITEM_NOT_FOUND	404	Item no existe en el carrito
COUPON_INVALID	422	Cupón no válido o expirado
CART_EXPIRED	410	Carrito expirado