Checkout
Usa el checkout generado por el framework y conoce sus requisitos reales.
El framework ya genera estas rutas:
/checkout/redirige a/cart./checkout/:checkoutIdmuestra el flujo de compra./thank-youmuestra la confirmación.
No crees pages/checkout.* ni pages/thank-you.tsx: son rutas reservadas.
Requisitos
El checkout llama siempre a useAuth y useCart, incluso cuando la tienda
permite checkout de invitado. Tu layout debe montar ambos providers:
import { AuthProvider, CartProvider, defineLayout } from "@ecomiq/storefront";
import { authClient } from "./lib/auth-client";
export default defineLayout(({ children, settings }) => (
<AuthProvider client={authClient}>
<CartProvider
storeId={settings.store.id}
currencyCode={settings.store.currency}
>
{children}
</CartProvider>
</AuthProvider>
));También necesitas:
lib/auth-client.tsconcreateStorefrontAuthClient.- El proxy
pages/api/$.ts. - El handler
pages/api/auth.$.ts.
La guía de cuentas contiene esos archivos.
Enviar al comprador al checkout
import { Link, useCart } from "@ecomiq/storefront";
export function CheckoutButton() {
const { cart } = useCart();
if (!cart) return null;
return (
<Link to="/checkout/$checkoutId" params={{ checkoutId: cart.id }}>
Continuar al checkout
</Link>
);
}El checkout lee settings.store.checkoutSettings.general.allowGuestCheckout.
Si el checkout de invitado está desactivado y no existe sesión, redirige a
/login?redirect=/checkout/{id}. Tú debes crear las páginas /login y
/register.
API de bajo nivel
Para un flujo alternativo, serverApi expone las operaciones reales. Todas
reciben un solo objeto que incluye cartId:
await serverApi.patchCartBuyer({
cartId,
email: "andrea@ejemplo.pe",
firstName: "Andrea",
lastName: "Ramos",
phone: "+51 999 888 777",
});
const shipping = await serverApi.getShippingOptions({
cartId,
postalCode: "15001",
});
const rate = shipping.groups[0]?.rates[0];
if (rate) {
await serverApi.putCartShippingMethod({
cartId,
rateId: rate.rateId,
shippingMethodId: rate.shippingMethodId,
});
}
const result = await serverApi.checkoutCart({
cartId,
paymentMethodCode: "bank_transfer",
externalRef: crypto.randomUUID(),
});También están disponibles getCartCheckout, patchCartAddresses,
uploadPaymentReceipt, addCartPromotionCode y removeCartPromotionCode.
Stripe y Mercado Pago
La UI incluida abre una URL de redirección cuando el API la devuelve y soporta
comprobantes manuales. Todavía no monta una interfaz embebida de Stripe o
Mercado Pago cuando el proveedor devuelve solo un clientSecret. Prueba el
método de pago elegido de extremo a extremo antes de publicar.