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.

  • 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, con q, categoryId, page y limit.
  • GET /products/{id}: variantes, SKU comprables, stock y ofertas.
  • GET /products/by-slug/{slug}: lo mismo, por slug exacto. Un slug puede ser nulo y puede cambiar sin redirigir desde el valor anterior, que responde 404.
  • GET /geo/cities: departamentos y ciudades; el code de la ciudad es el cityId.

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:

JSON
{
  "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í:

Texto
listSubtotal - bundleSavings = subtotal
subtotal - couponDiscount + shippingPrice = total

subtotal 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.

JavaScript
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.

  • tel siempre es obligatorio. Se acepta 0981..., 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, optional o required. Un campo hidden se descarta aunque se envíe.
  • Sin configurar, name, lastName, address y city son obligatorios, y email y document opcionales.
  • Si store.checkout.askDirection2 es false, direction2 se guarda vacía.
  • Conviene enviar cityId. Un city de 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 ruc junto con taxIdCountry y taxIdType: 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. Un email vací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).

kindQué hacer después
stripePOST /orders/{token}/pay con returnUrl (paso 4). Pago con tarjeta. No pide ningún dato extra del comprador.
manualMostrar manual.instructions y manual.accounts. Si proof.requested es true, pedir el comprobante (paso 6).
standardConfirmar 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:

EstadocodeQué significa
400STRIPE_NOT_AVAILABLELa tienda no tiene el pago con tarjeta disponible.
400STRIPE_CURRENCY_NOT_SUPPORTEDLa tienda no vende en guaraníes.
400STRIPE_AMOUNT_NOT_ALLOWEDEl total supera stripe.maxTotal: ofrecer otro medio.
400PAYMENT_METHOD_UNAVAILABLEviaStripe 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:

  1. GET /store: la opción con kind: "stripe" está en paymentOptions si la tienda puede cobrar con tarjeta.
  2. POST /checkout con el request de esa opción: crea el pedido, PENDIENTE.
  3. POST /orders/{token}/pay con returnUrl: devuelve la URL de pago de Stripe.
  4. El comprador paga en Stripe y vuelve a returnUrl (paso 5).
  5. La landing lee GET /orders/{token}: paymentStatus dice si está pagado.
  6. El comercio recibe order.paid por 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:

JavaScript
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 clave sk_: el origen de la landing tiene que estar registrado.
  • http solo vale para localhost, 127.0.0.1 y [::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.

EstadocodeQué significa
400RETURN_URL_INVALIDFalta returnUrl o no cumple las reglas.
400STRIPE_NOT_AVAILABLE, STRIPE_CURRENCY_NOT_SUPPORTED, STRIPE_AMOUNT_NOT_ALLOWEDLa tienda dejó de ofrecer el pago con tarjeta para este pedido.
400STRIPE_REJECTEDStripe no aceptó iniciar el pago.
404ORDER_NOT_FOUNDEl token no es de un pedido de esta tienda.
409ORDER_NOT_PAYABLEPagado, cancelado o con la sesión vencida.
409ORDER_CHANGEDDos inicios simultáneos del mismo pedido: reintentar.
503SERVICE_UNAVAILABLEStripe 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):

Texto
https://landing.example.com/pago?order=<publicToken>&status=success     pagó
https://landing.example.com/pago?order=<publicToken>&status=cancelled   volvió sin pagar

Si 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:

paymentStatusQué mostrar
PAGADOPago confirmado. Vaciar el carrito. status pasa a PREPARANDO.
PENDIENTECon 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.

  1. POST /orders/{token}/proof/upload, en multipart/form-data con el campo file. Hasta 10 MB; JPEG, PNG, WebP, GIF o PDF. Devuelve { "key": "..." }.
  2. POST /orders/{token}/proof con { "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 pagopar no aparece en store.paymentOptions de ninguna tienda.
  • POST /checkout con viaPagopar: true responde 400 PAGOPAR_NOT_ACTIVE.
  • POST /orders/{token}/pay sobre un pedido que no se creó con la opción stripe responde 400 PAGOPAR_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 con GET /orders/{token}.
  • PAGOPAR_REJECTED queda 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}.