Guías · Empezar
Vender desde la landing
El recorrido completo de una venta: del catálogo al pago. Tu landing guarda las líneas del carrito y el servidor calcula todo lo demás.
1. Cargar la tienda y el catálogo
GET /store: moneda, campos que pide el checkout, métodos de envío, opciones de pago y píxel.GET /categories: categorías visibles, con un nivel de subcategorías.GET /products: lista paginada, conq,categoryId,pageylimit.GET /products/{id}: variantes, SKU comprables, stock y ofertas.GET /products/by-slug/{slug}: lo mismo, porslugexacto. Unslugpuede ser nulo y puede cambiar sin redirigir desde el valor anterior, que responde 404.GET /geo/cities: departamentos y ciudades; elcodede la ciudad es elcityId.
Solo los productos con purchasable: true se pueden comprar: están EN_VENTA y les queda alguna combinación disponible. AGOTADO se lista pero el checkout lo rechaza. En un SKU, stock: null significa que la tienda no controla el stock de ese SKU y stock: 0 significa agotado.
El stock es el que la tienda vende online: la suma de las ubicaciones (depósitos o sucursales) que despachan pedidos online, que es lo mismo que verifica el checkout. En una tienda con una sola ubicación es su stock total. Las unidades de una ubicación que no despacha online no cuentan, así que un SKU puede figurar AGOTADO aunque la tienda tenga unidades en otro lado.
La lista trae la primera imagen de cada producto; el detalle, todas. Cada imagen trae url y alt; hoy alt es siempre null, porque el panel todavía no permite cargar el texto alternativo. Un parámetro fuera de rango responde 400 INVALID_QUERY: limit admite hasta 100.
Toda respuesta lleva Cache-Control: private, no-store. Conviene no guardar el stock del lado de la landing.
Bajo una ráfaga, las lecturas de productos pueden servir la última respuesta conocida, de hasta 10 minutos, o responder 429 si no hay ninguna. Nunca responden un catálogo vacío por eso.
2. Cotizar
No hay carrito en el servidor. La landing guarda las líneas y las cotiza con POST /cart/quote:
{
"items": [{ "productId": "clx0prod", "skuId": "clx0sku", "quantity": 2 }],
"shippingMethodId": "1f2e3d4c",
"cityId": "1101",
"couponCode": "VERANO"
}En un producto con variantes, skuId es obligatorio; en uno simple se omite. La respuesta cierra así:
listSubtotal - bundleSavings = subtotal
subtotal - couponDiscount + shippingPrice = totalsubtotal es la base del envío por umbral y del cupón, por lo que un cupón no quita un envío gratis ya alcanzado. availableShippingMethodIds trae los métodos que cubren la ciudad. Hay que volver a cotizar al cambiar líneas, ciudad, envío o cupón.
stockIssues compara lo pedido contra ese mismo stock online. La cotización no reserva nada ni vence. El checkout vuelve a calcular todo: hay que mostrar el total de su respuesta, que es el que vale. Los topes de canje de un cupón solo se verifican en el checkout.
Si una oferta aplicada no combina con cupones, la respuesta es 422 BUNDLE_COUPON_CONFLICT: el comprador decide quitar el cupón. La oferta nunca se cambia en silencio.
3. Crear el pedido
Conviene llamar a POST /checkout desde el navegador, con pk_. Con sk_ también funciona y paga los mismos límites: todos los compradores de ese servidor comparten una IP y agotan el límite por IP y tienda (10 por minuto hoy), y un 429 arma la tienda para ALTCHA, que el servidor tendría que resolver. Meta también recibe la IP y el navegador del servidor en vez de los del comprador.
const res = await fetch(`${BASE}/checkout`, {
method: "POST",
headers: {
Authorization: `Bearer ${PUBLISHABLE_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": attemptId, // el mismo id en cada reintento de esta compra
},
body: JSON.stringify({
items,
tel: "0981123456",
name: "Ana",
lastName: "Gómez",
email: "[email protected]",
cityId: "1101",
direction1: "Av. Mariscal López 1234",
shippingMethodId: "1f2e3d4c",
...option.request, // la opción elegida de store.paymentOptions
}),
});Datos del comprador. Solo compra como invitado.
telsiempre es obligatorio. Se acepta0981...,981...,595981...o+595...; sin código de país se interpreta como Paraguay. Uno ilegible responde 400.- El resto depende de
store.checkout.fields, con tres valores por campo:hidden,optionalorequired. Un campohiddense descarta aunque se envíe. - Sin configurar,
name,lastName,addressycityson obligatorios, yemailydocumentopcionales. - Si
store.checkout.askDirection2esfalse,direction2se guarda vacía. - Conviene enviar
cityId. Uncityde texto libre que no coincide con el catálogo no frena la venta, pero el pedido queda sin control de cobertura y el comercio recibe un aviso. - Para el documento, conviene enviar
rucjunto contaxIdCountryytaxIdType: solo así el servidor lo valida, incluido el dígito verificador del RUC. - Un comprador se reconoce por email o teléfono dentro de la tienda, y su ficha se actualiza con los últimos datos. Las respuestas nunca devuelven datos guardados.
- Un cuerpo que no respeta los tipos y formatos del contrato responde 400
INVALID_BODY. Unemailvacío equivale a ausente; mal formado se rechaza también si la tienda oculta el campo.
Pago. Cada elemento de store.paymentOptions trae en request los campos exactos a enviar y en fields lo que el checkout pide con esa opción. Un medio que la tienda no ofrece responde 400 PAYMENT_METHOD_UNAVAILABLE. viaPagopar sigue siendo obligatorio en el cuerpo y hoy va siempre en false: Pagopar está retirado (paso 7).
kind | Qué hacer después |
|---|---|
stripe | POST /orders/{token}/pay con returnUrl (paso 4). Pago con tarjeta. No pide ningún dato extra del comprador. |
manual | Mostrar manual.instructions y manual.accounts. Si proof.requested es true, pedir el comprobante (paso 6). |
standard | Confirmar el pedido. Solo aparece si la tienda no configuró ningún otro medio, Stripe incluido. |
Tarjeta (Stripe). La opción stripe aparece solo si el pago con tarjeta está disponible para esa tienda en ese momento: lo tiene activado, vende en guaraníes y Tiendy lo tiene habilitado. Su request es { "paymentMethod": "TARJETA", "viaPagopar": false, "viaStripe": true }, y stripe.maxTotal es el total máximo de un pedido que se puede pagar así: Gs. 5.000.000, o el tope menor que haya fijado la tienda. Conviene ocultar la opción cuando el total de la cotización lo supera.
viaStripe es opcional y ausente equivale a false. Rechazos del checkout con viaStripe: true, todos sin crear nada:
| Estado | code | Qué significa |
|---|---|---|
| 400 | STRIPE_NOT_AVAILABLE | La tienda no tiene el pago con tarjeta disponible. |
| 400 | STRIPE_CURRENCY_NOT_SUPPORTED | La tienda no vende en guaraníes. |
| 400 | STRIPE_AMOUNT_NOT_ALLOWED | El total supera stripe.maxTotal: ofrecer otro medio. |
| 400 | PAYMENT_METHOD_UNAVAILABLE | viaStripe junto con un medio manual o con un paymentMethod que no es TARJETA. |
El pedido se crea PENDIENTE. El comercio recibe la notificación y el email del pedido recién cuando el pago se confirma; el webhook order.created sí sale al crearlo.
Envío. shippingMethodId es un id de store.shippingMethods, o NINGUNO o ausente para «Retiro en local / Sin envío». Con store.checkout.requiresShippingMethod en true, esa opción se rechaza con 400 SHIPPING_METHOD_REQUIRED.
Límite conocido: no hay retiro en sucursal. El checkout no tiene un campo para elegir la sucursal, así que un pedido con un método de tipo RETIRO se crea sin sucursal elegida y su stock se verifica contra el stock online, como cualquier otro.
Reintentos. Idempotency-Key es obligatorio. Reenviar la misma clave con el mismo cuerpo devuelve 200 con el pedido ya creado y Idempotency-Replayed: true, sin repetir emails, eventos ni canjes de cupón, así que un timeout o un 500 se reintenta sin riesgo de duplicar. Dos envíos simultáneos con la misma clave crean un solo pedido. La misma clave con otro cuerpo responde 409 IDEMPOTENCY_KEY_REUSED; si el primer intento no termina a tiempo, 409 IDEMPOTENCY_IN_PROGRESS, que se reintenta. Al comparar cuerpos no cuentan el orden de los campos, los campos desconocidos, altchaChallenge, altchaSolution ni metaContext. Un intento rechazado no registra la clave.
La respuesta 201 trae publicToken, con el que se opera después. Hay que tratarlo como un secreto del comprador y guardarlo para poder reintentar el pago.
4. Pagar con tarjeta (Stripe)
El recorrido completo:
GET /store: la opción conkind: "stripe"está enpaymentOptionssi la tienda puede cobrar con tarjeta.POST /checkoutcon elrequestde esa opción: crea el pedido,PENDIENTE.POST /orders/{token}/payconreturnUrl: devuelve la URL de pago de Stripe.- El comprador paga en Stripe y vuelve a
returnUrl(paso 5). - La landing lee
GET /orders/{token}:paymentStatusdice si está pagado. - El comercio recibe
order.paidpor webhook cuando Stripe confirma el pago.
Para un pedido creado con la opción stripe, POST /orders/{token}/pay devuelve { "url": "https://checkout.stripe.com/..." }; se redirige al comprador ahí. El cuerpo lleva la página de la landing a la que vuelve:
const res = await fetch(`${BASE}/orders/${order.publicToken}/pay`, {
method: "POST",
headers: { Authorization: `Bearer ${PUBLISHABLE_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ returnUrl: "https://landing.example.com/pago" }),
});
const { url } = await res.json();
window.location.assign(url);returnUrl es obligatorio y tiene reglas estrictas, porque es la única URL que la API recibe de quien llama:
- URL completa
https, de hasta 2.000 caracteres, sin usuario ni contraseña, y sin llaves ({}), espacios ni barras invertidas. - Su origen (esquema, host y puerto) tiene que ser uno de los orígenes autorizados de la tienda (Configuración → API), con la misma coincidencia exacta que usa la clave
pk_. También con una clavesk_: el origen de la landing tiene que estar registrado. httpsolo vale paralocalhost,127.0.0.1y[::1], y solo si ese origen está registrado.- Cualquier otra cosa responde 400
RETURN_URL_INVALID, sin llamar a Stripe.
Si falla o el comprador vuelve sin pagar, se llama de nuevo con el mismo pedido. Nunca se llama de nuevo a /checkout, porque crearía un segundo pedido. Reintentar es seguro: mientras la sesión de pago siga abierta, la respuesta es la misma url, y nunca se crea un segundo cobro. La sesión queda fijada en el primer intento: un reintento con otro returnUrl devuelve la sesión ya creada, con la página de retorno original.
El comprador tiene 24 horas para pagar. Pasado ese plazo, o con el pedido ya pagado o cancelado, la respuesta es 409 ORDER_NOT_PAYABLE: una compra nueva necesita un pedido nuevo.
| Estado | code | Qué significa |
|---|---|---|
| 400 | RETURN_URL_INVALID | Falta returnUrl o no cumple las reglas. |
| 400 | STRIPE_NOT_AVAILABLE, STRIPE_CURRENCY_NOT_SUPPORTED, STRIPE_AMOUNT_NOT_ALLOWED | La tienda dejó de ofrecer el pago con tarjeta para este pedido. |
| 400 | STRIPE_REJECTED | Stripe no aceptó iniciar el pago. |
| 404 | ORDER_NOT_FOUND | El token no es de un pedido de esta tienda. |
| 409 | ORDER_NOT_PAYABLE | Pagado, cancelado o con la sesión vencida. |
| 409 | ORDER_CHANGED | Dos inicios simultáneos del mismo pedido: reintentar. |
| 503 | SERVICE_UNAVAILABLE | Stripe no respondió: reintentar después de Retry-After. |
5. Página de retorno de Stripe
Stripe devuelve al comprador a returnUrl con dos parámetros que agrega el servidor, conservando los que la URL ya tenía (y su fragmento):
https://landing.example.com/pago?order=<publicToken>&status=success pagó
https://landing.example.com/pago?order=<publicToken>&status=cancelled volvió sin pagarSi returnUrl ya traía order o status, se reemplazan.
La página de retorno muestra el estado y nunca lo decide. Llegar con status=success no prueba nada: cualquiera puede escribir esa URL. El pago lo confirma solo el webhook firmado que Stripe le envía a Tiendy. La página toma order, llama a GET /orders/{token} y lee paymentStatus:
paymentStatus | Qué mostrar |
|---|---|
PAGADO | Pago confirmado. Vaciar el carrito. status pasa a PREPARANDO. |
PENDIENTE | Con status=success: pago en proceso; consultar de nuevo cada pocos segundos, con un máximo razonable. Con status=cancelled: ofrecer reintentar con POST /orders/{token}/pay. |
payment.gateway vale "stripe" en un pedido creado con esta opción y null en los demás: así la landing sabe que ese pedido se paga con POST /orders/{token}/pay. Solo los pedidos creados por la API se pagan así: uno hecho en la tienda propia con Stripe también muestra "stripe", pero se paga en la tienda. Un pedido ya pagado o cancelado responde 409 ORDER_NOT_PAYABLE, mande lo que mande el cuerpo. La confirmación también llega por los webhooks del comercio: order.paid y order.status_changed (ver Webhooks).
No disponible todavía: devoluciones por la API (se hacen desde el panel) y generar una sesión nueva para un pedido cuya sesión venció.
6. Comprobante de pago manual
Nunca bloquea el pedido: se envía después, y solo una vez.
POST /orders/{token}/proof/upload, enmultipart/form-datacon el campofile. Hasta 10 MB; JPEG, PNG, WebP, GIF o PDF. Devuelve{ "key": "..." }.POST /orders/{token}/proofcon{ "proofUrl": "<key>" }. A pesar del nombre, es la clave del paso anterior, nunca una URL.
Rechazos del paso 1: 413 FILE_TOO_LARGE y 400 FILE_INVALID. Del paso 2: 422 PROOF_INVALID y 409 PROOF_NOT_ALLOWED (el pago no es manual), PROOF_ORDER_CANCELLED o PROOF_ALREADY_UPLOADED.
7. Pagopar (no disponible)
Pagopar está retirado en toda la plataforma y no se puede activar. Esta sección queda como referencia de lo que la API sigue respondiendo:
- La opción
pagoparno aparece enstore.paymentOptionsde ninguna tienda. POST /checkoutconviaPagopar: trueresponde 400PAGOPAR_NOT_ACTIVE.POST /orders/{token}/paysobre un pedido que no se creó con la opciónstriperesponde 400PAGOPAR_NOT_ACTIVE. Su cuerpo se ignora.GET /orders/by-payment-hash/{hash}sigue respondiendo por los pedidos que tienen un hash de Pagopar. Los pedidos de Stripe no tienen hash: se consultan conGET /orders/{token}.PAGOPAR_REJECTEDqueda en el contrato, pero hoy ningún request lo recibe.
Mientras existió, el flujo era: checkout con viaPagopar: true (con email, ruc y rucName obligatorios), POST /orders/{token}/pay para obtener la URL de Pagopar, y una página de retorno única por comercio que consultaba GET /orders/by-payment-hash/{hash}.