# Tiendy Storefront API > Vender desde una landing propia usando a Tiendy como backend: catálogo, precios, envío, ofertas, cupones, pedidos y pago. Los pedidos aparecen en Pedidos y cuentan en Finanzas como cualquier otro. Instrucciones y documentación completa para un modelo que va a escribir una integración con la API de storefront de Tiendy: reglas, guía, referencia de cada endpoint y eventos de webhook. ## Base y autenticación - URL base: `https://www.tiendy.com.py/api/storefront/v1` - Autenticación: encabezado `Authorization: Bearer pk_...` (clave publicable, en el navegador) o `Authorization: Bearer sk_...` (clave secreta, en el servidor). - La clave determina la tienda: ningún request lleva `storeId`. - El comercio crea y revoca sus claves, y registra los orígenes autorizados, en el panel de Tiendy, en Configuración → API. - La API se incluye solo en el plan Tiendy AI (`PRO`). Fuera de ese plan los endpoints responden 403 `STOREFRONT_API_PLAN_REQUIRED`. - Contrato OpenAPI: https://www.tiendy.com.py/docs/openapi.json. Si la guía y el contrato difieren, vale el contrato. ## Reglas que no se pueden romper - Tiendy es la única autoridad de precios, envío, ofertas, cupones y totales. La landing muestra lo que el servidor calcula; cualquier total que envíe se ignora. - La clave `pk_` (publicable) va en el navegador y solo funciona desde los orígenes autorizados de la tienda. La clave `sk_` (secreta) va solo de servidor a servidor, nunca en un navegador: con encabezado `Origin` responde 403 `SECRET_KEY_IN_BROWSER`. - `POST /checkout` exige el encabezado `Idempotency-Key`. Cada reintento de la misma compra reusa la misma clave con el mismo cuerpo; si el cuerpo cambia, la clave es nueva. - Para reintentar un pago se vuelve a llamar a `POST /orders/{token}/pay` con el mismo pedido. Nunca se llama de nuevo a `POST /checkout`, porque crearía un segundo pedido. - El monto que vale es el `total` de la respuesta del checkout: hay que mostrar ese, no el cotizado. La cotización no reserva nada ni vence. - Toda landing implementa el flujo ALTCHA: ante un 403 `ALTCHA_REQUIRED` del checkout, pedir `GET /altcha/challenge`, resolverlo en el navegador y reenviar el mismo cuerpo y la misma `Idempotency-Key`, sumando `altchaChallenge` y `altchaSolution`. - El stock se verifica en el checkout, no se reserva: se puede sobrevender. Hablar de «pedido recibido» y no prometer disponibilidad. Ante un 409 `INSUFFICIENT_STOCK`, ajustar las líneas, volver a cotizar y reenviar con una `Idempotency-Key` nueva. - Ramificar solo por `code`, nunca por el texto del error. Algunos rechazos solo traen `message`, que se muestra tal cual. - Los montos son enteros en la moneda de la tienda, sin decimales. No se dividen por 100: `150000` en PYG son 150.000 guaraníes. - `publicToken` es un secreto del comprador: con él se opera el pedido. Guardarlo para poder reintentar el pago. - El pago con tarjeta es con Stripe: checkout con el `request` de la opción `stripe` de `GET /store`, y después `POST /orders/{token}/pay` con un `returnUrl` `https` de un origen autorizado de la tienda. Pagopar está retirado. - La página de retorno de Stripe muestra el estado y nunca lo decide: llegar con `status=success` no prueba nada. Consulta `GET /orders/{token}` con el `order` de la URL y lee `paymentStatus`. - En un webhook, verificar la firma `Tiendy-Signature` sobre el cuerpo crudo, antes de parsear el JSON, comparar en tiempo constante y rechazar un `t` con más de 5 minutos de diferencia. Descartar repeticiones por `Tiendy-Event-Id`. ## Introducción ### Qué permite hacer Vender desde una landing propia usando a Tiendy como backend: catálogo, precios, envío, ofertas, cupones, pedidos y pago. Los pedidos aparecen en Pedidos y cuentan en Finanzas como cualquier otro. Tiendy es la única autoridad de precios, envío, ofertas, cupones y totales. La landing muestra lo que el servidor calcula, y cualquier total que envíe se ignora. ### Antes de empezar - **Plan.** La API se incluye solo en el plan Tiendy AI (`PRO`, el más caro), sin compra aparte. Si la tienda no está en ese plan o lo pierde, los endpoints responden 403 `STOREFRONT_API_PLAN_REQUIRED` en hasta dos minutos. Las consultas de pedidos existentes (`GET /orders/{token}` y `GET /orders/by-payment-hash/{hash}`) siguen abiertas, porque un comprador que ya pagó tiene que poder ver su pedido. Los pedidos siguen en el panel y las confirmaciones de pago (el webhook de Stripe) se siguen procesando. - **Claves.** Cada tienda tiene las suyas, y la clave determina la tienda: ningún request lleva `storeId`. - **URL base:** `https://www.tiendy.com.py/api/storefront/v1`. - **Montos.** Enteros en la moneda de la tienda (`currency` en `GET /store`), sin decimales. No se dividen por 100: `150000` en PYG son 150.000 guaraníes. ## Obtener las claves Las claves, los orígenes y los webhooks se administran en el panel de Tiendy, en **Configuración → API** de la tienda. Si la tienda no está en el plan Tiendy AI, esa pantalla muestra el aviso para cambiar de plan. 1. Entrar al panel de la tienda y abrir Configuración → API. Hace falta el permiso de configuración: ver para leer, editar para crear, revocar o cambiar orígenes. 2. En «Claves de API», crear una clave: un nombre para reconocerla en la lista y el tipo, publicable (`pk_`) para el navegador o secreta (`sk_`) para un servidor. 3. Copiar la clave en el momento. Se muestra una sola vez, porque Tiendy guarda solo su hash; si se pierde, se revoca y se crea otra. 4. En «Orígenes autorizados», agregar cada sitio desde el que se va a usar la clave publicable, por ejemplo `https://landing.example.com`. Las reglas de coincidencia están en Autenticación. 5. Para recibir avisos de pedidos, agregar un webhook en la misma pantalla y guardar su secreto de firma `whsec_…`, que también se muestra una sola vez (ver Webhooks). Una clave revocada deja de funcionar y responde 401 `API_KEY_INVALID`. ## Autenticación ```http Authorization: Bearer pk_... ``` | Clave | Dónde se usa | Restricción | |---|---|---| | `pk_` publicable | Navegador | Solo desde los orígenes autorizados de la tienda. `Origin` ausente o no autorizado: 403 `ORIGIN_NOT_ALLOWED`. | | `sk_` secreta | Servidor a servidor | Nunca en un navegador. Con encabezado `Origin`: 403 `SECRET_KEY_IN_BROWSER`. | Tiendy solo guarda el hash de las dos clases, así que una clave se ve una sola vez, al crearla. El comercio las crea y revoca en el panel, en Configuración → API, y ahí mismo registra los orígenes. Hace falta el permiso de configuración (ver para leer, editar para crear, revocar o cambiar orígenes) y el plan con la API. **Orígenes.** Coincidencia exacta de esquema, host y puerto: `https://landing.example.com` no autoriza `https://www.landing.example.com` ni `https://landing.example.com:8443`. Sin comodines. `https` obligatorio, salvo `localhost`, `127.0.0.1` y `[::1]` para desarrollo. `Origin: null` nunca está autorizado. **Una clave `pk_` más el chequeo de origen no es un límite de seguridad.** La clave es visible en el navegador y un cliente fuera de él puede falsificar `Origin`. Lo que protege a la tienda son las reglas del servidor y los límites de frecuencia, que se aplican siempre. **CORS.** Un preflight `OPTIONS` no lleva `Authorization`, por lo que no puede saber de qué tienda se trata: responde 204 a cualquier origen, lo refleja en `Access-Control-Allow-Origin` con `Vary: Origin` y permite `Authorization`, `Content-Type` e `Idempotency-Key`. Un preflight exitoso no significa que el origen esté autorizado: eso se decide en el request real. Un `ORIGIN_NOT_ALLOWED` no lleva encabezados CORS, así que el navegador no deja leerlo; toda otra respuesta sí se puede leer y expone `Retry-After` e `Idempotency-Replayed`. No se usan cookies. ## Vender desde la landing ### 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, 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í: ```text 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. ```js 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: "ana@example.com", 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). | `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: 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: ```js 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. | 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): ```text https://landing.example.com/pago?order=&status=success pagó https://landing.example.com/pago?order=&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`: | `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. 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": "" }`. 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}`. ## Stock: se puede sobrevender El stock **se verifica en el checkout, no se reserva**, y se descuenta recién al despachar o entregar. Lo que se verifica es el stock online: la suma de las ubicaciones de la tienda que despachan pedidos online, el mismo número que devuelven el catálogo y la cotización. Dos compradores pueden pasar a la vez por la última unidad, y ambos pedidos se crean: esa diferencia la resuelve el comercio. Por eso conviene hablar de «pedido recibido» y no prometer disponibilidad. Un 409 `INSUFFICIENT_STOCK` no crea nada y trae `details`, con un elemento por SKU: ```json { "skuId": "clx0sku", "skuKey": "color:rojo", "label": "Remera Rojo", "requested": 3, "available": 1 } ``` Hay que mostrar el mensaje, ajustar las líneas, volver a cotizar y reenviar con una `Idempotency-Key` nueva, porque cambió el cuerpo. `available` es el stock online de ese SKU. `stockIssues` en la cotización anticipa el problema, pero no garantiza nada. No existe la venta sin stock: un SKU con stock controlado y sin unidades online no se puede comprar. ## Verificación ALTCHA Una ráfaga de intentos arma la tienda durante 30 minutos, y mientras tanto el checkout exige una prueba de trabajo. Hoy alcanza con más de 5 intentos por minuto en la tienda, de modo que una promoción exitosa también la arma. Toda landing tiene que implementar este flujo: 1. `POST /checkout` responde 403 `ALTCHA_REQUIRED`. Nada se escribió. 2. `GET /altcha/challenge` entrega un desafío válido por 10 minutos. 3. El navegador lo resuelve y reenvía el mismo cuerpo y la misma `Idempotency-Key`, sumando `altchaChallenge` y `altchaSolution`. ```js import { solveChallenge } from "altcha-lib"; import { deriveKey } from "altcha-lib/algorithms/web/pbkdf2"; const challenge = await (await fetch(`${BASE}/altcha/challenge`, { headers })).json(); const altchaSolution = await solveChallenge({ challenge, deriveKey }); // reenviar: { ...body, altchaChallenge: challenge, altchaSolution } ``` Cada solución sirve una sola vez. `ALTCHA_INVALID`, `ALTCHA_EXPIRED` y `ALTCHA_REPLAY` se resuelven igual, con un desafío nuevo; conviene reintentar una sola vez. Un 404 del desafío significa que ALTCHA no está configurado en la plataforma y no se exige en ninguna tienda. ## Meta Pixel y métricas El servidor envía Purchase a la API de Conversiones cuando la tienda la tiene configurada. La landing reutiliza el mismo `eventId` en su píxel para que Meta no cuente la venta dos veces. - Se usa el píxel de `store.metaPixel`, respetando sus toggles y `requireCookieConsent`. - `metaPurchase.due` indica cuándo disparar Purchase: en un pago manual, desde la creación; con tarjeta (Stripe), desde la confirmación del pago. Deja de ser `true` a las 24 horas. - `metaEvents` del checkout trae Lead y, si el pedido creó el cliente, CompleteRegistration, con sus ids. - `metaContext` en el checkout aporta `eventSourceUrl`, `fbclid`, `fbp`, `fbc`, `consent` e `initiateCheckoutEventId` (UUID v4). Las cookies de la landing no viajan a Tiendy, así que `fbp` y `fbc` hay que enviarlos a mano. ```js const { eventId, due, params } = order.metaPurchase; if (due) fbq("trackSingle", pixelId, "Purchase", params, { eventID: eventId }); ``` Si la tienda exige consentimiento, el servidor no envía eventos salvo con `metaContext.consent` en `granted`. **Métricas.** Los pedidos cuentan en Pedidos y Finanzas. Las visitas las mide la landing: Métricas de Tiendy no las ve, y el beacon de analítica y el relay de Meta de Tiendy tratan a una tienda API-only como cerrada. ## Tiendas API-only `Store.apiOnly` (`apiOnly` en `GET /store`) significa que la tienda vende solo por esta API. El personal de Tiendy lo activa; no hay opción en el panel. | Sigue funcionando | Deja de estar disponible | |---|---| | Esta API y el panel del comercio | El storefront, que responde 404, y su dominio propio | | Las páginas de pedido del comprador, a las que enlazan sus emails (`trackingUrl`) | Robots y sitemap de la tienda | | La confirmación de los pagos con tarjeta (Stripe) | El marketplace y el widget de Tiendlink | | | `/api/cart` y el checkout del marketplace: 403 `STORE_API_ONLY` | API-only no es lo mismo que cerrada. Una tienda pausada o archivada responde 403 `STORE_INACTIVE` en catálogo, cotización y checkout, también por esta API; los endpoints de un pedido existente siguen disponibles. ## Datos que nunca devuelve Las respuestas públicas nunca incluyen costos (`costPrice`, `unitCostSnapshot`), claves o comisiones de Pagopar, lo que Tiendy descuenta de una venta con tarjeta ni el neto del comercio, los identificadores de Stripe (sesión, pago), la cuenta donde el comercio cobra esas ventas, datos del dueño ni datos personales de un comprador, ni siquiera los del propio pedido: nombre, email, teléfono, documento, dirección o ubicación. La landing ya tiene lo que el comprador tipeó. ## Errores ```json { "error": "Texto corto", "message": "Texto para el comprador", "code": "INSUFFICIENT_STOCK" } ``` Se ramifica solo por `code`, y no por el texto. Los mensajes están en español y son aptos para mostrar; los que vienen del checkout de Tiendy pueden estar en voseo. **No todo rechazo trae `code` todavía:** datos del comprador, ciudad, cupón inválido, tope de cupón y líneas inválidas solo traen `message`, que se muestra tal cual. | Estado | `code` | Qué significa | |---|---|---| | 400 | `INVALID_QUERY` | Un parámetro de una lectura está fuera de rango o mal formado. | | 400 | `INVALID_BODY` | El cuerpo no es JSON o no respeta los tipos y formatos del contrato. | | 400 | `IDEMPOTENCY_KEY_REQUIRED` | Falta el encabezado o está mal formado. | | 400 | `PAYMENT_METHOD_UNAVAILABLE` | La tienda no ofrece ese medio de pago, o la combinación enviada no existe. | | 400 | `STRIPE_NOT_AVAILABLE` | La tienda no tiene el pago con tarjeta (Stripe) disponible. | | 400 | `STRIPE_CURRENCY_NOT_SUPPORTED` | El pago con tarjeta solo existe para tiendas en guaraníes. | | 400 | `STRIPE_AMOUNT_NOT_ALLOWED` | El total supera el máximo por venta de `stripe.maxTotal`. | | 400 | `STRIPE_REJECTED` | Stripe no aceptó iniciar el pago. | | 400 | `RETURN_URL_INVALID` | `returnUrl` falta o no es una URL `https` de un origen autorizado. Ver el paso 4. | | 400 | `FILE_INVALID` | Sin archivo, tipo no permitido o contenido que no coincide. | | 400 | `SHIPPING_METHOD_INACTIVE` | El método se desactivó: se quita la selección. | | 400 | `SHIPPING_METHOD_REQUIRED` | La tienda exige método de envío. | | 400 | `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED` | Pagopar está retirado: el primero es lo que responde hoy todo intento de usarlo (paso 7). | | 401 | `API_KEY_INVALID` | Clave ausente, inválida o revocada. | | 403 | `STOREFRONT_API_PLAN_REQUIRED` | La tienda no está en el plan `PRO`. No aplica a las consultas de pedidos existentes. | | 403 | `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER` | Clave usada desde donde no corresponde. | | 403 | `STORE_INACTIVE` | Tienda pausada o archivada. | | 403 | `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY` | Ver ALTCHA. | | 404 | `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED` | No existe. Lo de otra tienda responde igual. | | 409 | `INSUFFICIENT_STOCK` | Ver Stock. | | 409 | `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS` | Otro cuerpo con la misma clave, o el intento concurrente no terminó a tiempo. | | 409 | `ORDER_NOT_PAYABLE`, `ORDER_CHANGED` | El pedido no admite otro pago, o cambió durante el inicio (reintentar). | | 409 | `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED` | Ver Comprobante. | | 413 | `FILE_TOO_LARGE` | Más de 10 MB, o sin `Content-Length`. | | 422 | `SHIPPING_NOT_AVAILABLE_FOR_CITY` | El método no cubre esa ciudad: ofrecer otro. | | 422 | `BUNDLE_COUPON_CONFLICT` | La oferta aplicada no combina con el cupón. | | 422 | `PROOF_INVALID` | La clave no es de un comprobante de esta tienda. | | 429 | `RATE_LIMITED` | Respetar `Retry-After`. | | 503 | `SERVICE_UNAVAILABLE` | No se pudo verificar la clave o el plan, o Stripe no respondió al iniciar un pago. No significa que la clave sea inválida: reintentar después de `Retry-After`. | ## Límites de frecuencia Todo request pasa por estos límites. Son **provisorios**: se revisan con el tráfico real de la primera landing. Ante una caída del sistema de límites, el request sigue; la única excepción es asociar el comprobante, que en ese caso se rechaza y se puede reintentar. | Límite | Valor provisorio | Por | |---|---|---| | Antes de verificar la clave | 600 por minuto | IP | | Clave publicable, por cliente | 120 por minuto | IP y clave | | Total de la clave | 1.200 por minuto | Clave | Un `sk_` no tiene el límite por cliente, porque todos sus compradores comparten la IP del servidor. Un origen rechazado no consume el total de la clave. Las lecturas de productos (lista y detalle) suman la protección del catálogo de la tienda: 60 por minuto por IP y tienda, y 1.200 por minuto en total por tienda. Con `pk_` aplican los dos; con `sk_`, solo el total de la tienda, porque todos sus compradores comparten una IP. Al superarlos no se rechaza de entrada: se sirve la última respuesta conocida (ver el paso 1). Además, cada operación tiene el suyo: | Operación | Límite provisorio | Por | Con `sk_` | |---|---|---|---| | Cotización | 60 por minuto | IP y clave | No aplica | | Cotización con cupón | 20 por minuto | IP y tienda | No aplica | | Checkout | 10 por minuto | IP y tienda | Aplica | | Checkout, total | 20 por minuto y 100 por hora | Tienda | Aplica | | Inicio de pago (Stripe incluido) | 20 por minuto | IP y clave | No aplica | | Desafío ALTCHA | 30 por minuto | IP | No aplica | | Subida de comprobante | 10 por minuto | IP y tienda | No aplica | | Asociar comprobante | 10 cada 10 minutos | IP | No aplica | | Consultas a Pagopar desde `GET /orders/by-payment-hash/{hash}` (Pagopar está retirado) | 120 por minuto; superado, responde el estado guardado | Tienda | Aplica | Los límites del checkout son propios de esta API: una ráfaga contra el checkout del storefront no los gasta, ni al revés. La señal que arma la tienda para ALTCHA sí es compartida. Un 429 de checkout también arma la tienda para ALTCHA. ## Webhooks Tiendy avisa por `POST` a una URL `https` del comercio cuando cambia un pedido de la tienda. Llegan los pedidos de **todos los canales** (storefront de Tiendy, esta API, marketplace, panel y caja), y cada evento dice de cuál vino en `data.order.source` (`STOREFRONT`, `STOREFRONT_API`, `MARKETPLACE`, `ADMIN`, `POS`, o `null` en pedidos viejos). Solo plan PRO. | Evento | Cuándo | |---|---| | `order.created` | Se creó un pedido. Si nace pagado, también llega `order.paid`. | | `order.paid` | El pedido pasó a `paymentStatus = PAGADO`. | | `order.status_changed` | Cambió `status`. `data.previousStatus` y `data.status` dicen de dónde a dónde. Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. | | `order.proof_uploaded` | El comprador subió el comprobante de pago. | Un endpoint puede suscribirse a algunos eventos; sin lista recibe todos. Un evento se genera solo para los endpoints activos en ese momento, y solo si la tienda está en el plan PRO: lo que pasa con un endpoint pausado o con la tienda fuera del plan no se envía después. ```json { "id": "7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11", "type": "order.status_changed", "createdAt": "2026-11-03T15:04:05.000Z", "storeId": "…", "data": { "order": { "id": 1234, "status": "PREPARANDO", "paymentStatus": "PAGADO", "total": 115000, "source": "STOREFRONT_API", "…": "…" }, "previousStatus": "PENDIENTE", "status": "PREPARANDO" } } ``` `data.order` es el mismo `OrderView` de `GET /orders/{token}`, sin `metaPurchase` y con `source`: sin datos del comprador, sin costos, sin `publicToken`. Un pago con tarjeta confirmado genera `order.paid` y, si el pedido estaba `PENDIENTE`, `order.status_changed` a `PREPARANDO`. Es una foto del pedido en el momento del evento; para el estado actual, consultar la API. ### Registrar un endpoint El comercio da de alta sus endpoints en el panel de Tiendy, en **Configuración → API → Webhooks** (hace falta permiso de edición de Configuración; con permiso de solo lectura se ven la lista y el historial de envíos): 1. «Agregar webhook»: la URL (`https`, pública), una descripción opcional y los eventos. «Todos los eventos» (el default) también recibe los que se agreguen más adelante. Hasta 10 endpoints por tienda. 2. Al guardar, el panel muestra **una sola vez** el secreto de firma `whsec_…`. Copiarlo y guardarlo en el receptor: Tiendy no lo vuelve a mostrar, y en la lista solo aparecen sus últimos 4 caracteres. 3. Desde la lista se puede editar, pausar o activar (al pausar, los envíos que ya estaban pendientes quedan en espera y salen al reactivarlo, dentro de los 3 días; los eventos que ocurren mientras está pausado no se generan), rotar el secreto (el anterior deja de funcionar enseguida y el nuevo se muestra una vez) y eliminar (se borra también su historial). 4. «Ver envíos» muestra cada entrega con su evento, `Tiendy-Event-Id`, estado (pendiente, entregado, reintentando, fallido), intentos y la última respuesta. «Reenviar» vuelve a mandar una entrega con el **mismo** `Tiendy-Event-Id` y el mismo cuerpo, así que un receptor que descarta repetidos la trata igual; no se puede reenviar un evento de más de 3 días, uno de un endpoint pausado ni uno que ya está en cola. El historial conserva los envíos entregados y los fallidos durante 30 días. ### Verificar la firma Cada request trae `Tiendy-Event-Id`, `Tiendy-Event-Type` y `Tiendy-Signature: t=,v1=`, donde `v1` es el HMAC-SHA256 con el secreto del endpoint (`whsec_…`, se muestra una sola vez al crearlo) sobre `.`. Verificar sobre el cuerpo **tal como llegó**, antes de parsear el JSON, comparar en tiempo constante y rechazar un `t` con más de 5 minutos de diferencia: ```ts import { createHmac, timingSafeEqual } from "node:crypto"; function verify(rawBody: string, header: string, secret: string): boolean { const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2))); const t = Number(parts.t); if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false; const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest(); const given = Buffer.from(parts.v1 ?? "", "hex"); return given.length === expected.length && timingSafeEqual(given, expected); } ``` ### Entrega y reintentos - Responder `2xx` rápido y procesar después. Cualquier otra respuesta, una redirección (no se siguen) o 10 segundos sin respuesta es un intento fallido. - Hasta 8 intentos, con esperas de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Un evento sin entregar a los 3 días se descarta. - Si la tienda deja el plan PRO, los eventos pendientes no se envían: quedan en espera y salen si vuelve al plan antes de los 3 días. Los pedidos que cambian mientras está fuera del plan no generan eventos. ### Contrato del receptor - **Al menos una vez.** El mismo evento puede llegar más de una vez, incluso después de un `2xx`. Descartar repeticiones por `Tiendy-Event-Id` (es el mismo `id` del cuerpo). - **Sin orden garantizado.** Un `order.paid` puede llegar antes que su `order.created`, y un reintento puede llegar después de un evento más nuevo. `createdAt` es la hora del evento, no la de la entrega. - **El evento es un aviso, no el estado.** El `order` del cuerpo es una foto del momento del evento. Para el estado actual, consultar `GET /orders/{token}` con el `publicToken` del pedido y actuar sobre esa respuesta. - La URL tiene que resolver a una dirección pública; una URL interna o privada nunca recibe nada. ## No disponible todavía ### No disponible todavía - Filtros de catálogo por atributo o por precio. - Cuentas de comprador, inicio de sesión y «Ya soy cliente». - Carrito en el servidor y reserva de stock. - Retiro en sucursal: elegir la sucursal de un método de tipo `RETIRO`. - Texto alternativo de las imágenes (`images[].alt` es siempre `null`). - Venta sin stock (pedidos de un SKU sin unidades). - Devoluciones de un pago con tarjeta por la API: se hacen desde el panel. - Una sesión de pago nueva para un pedido cuya sesión de Stripe venció (24 horas): hace falta un pedido nuevo. - Pagopar: retirado (paso 7). - Webhooks de catálogo (`product.updated`, `stock.updated`). ### Pendiente de definir - Límites definitivos por clave y por operación. - Tiempo de retención de `Idempotency-Key`. Hoy una clave dura lo que dure su pedido: no hay barrido. - Códigos estables para los rechazos que solo traen `message`. - Comportamiento con monedas distintas de PYG, ya que las ofertas están escritas en guaraníes y el pago con tarjeta (Stripe) solo existe en guaraníes. ## Referencia de endpoints URL base: `https://www.tiendy.com.py/api/storefront/v1`. Todos los pedidos llevan `Authorization: Bearer `. ### GET /store Configuración pública de la tienda Todo lo que la landing necesita para armar un checkout: moneda, campos del comprador, métodos de envío activos, opciones de pago y píxel. Con la tienda pausada o archivada responde 403 `STORE_INACTIVE`, igual que todo el catálogo. Una tienda API-only no está cerrada: responde con normalidad. Respuestas: - 200: Tienda. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/store \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "id": "clx0store", "name": "Tienda Demo", "description": "Ropa y accesorios.", "logoUrl": "https://img.example.com/logo.png", "contactEmail": "hola@example.com", "whatsapp": "+595981123456", "currency": "PYG", "apiOnly": false, "checkout": { "fields": { "email": "optional", "name": "required", "lastName": "required", "address": "required", "city": "required", "document": "optional" }, "askDirection2": true, "askDeliveryLocation": false, "offersNoShipping": true, "requiresShippingMethod": false }, "shippingMethods": [ { "id": "1f2e3d4c", "name": "Envío a domicilio", "description": "Entrega en 24 a 48 horas.", "type": "DOMICILIO", "costType": "FIJO", "price": 15000, "freeThreshold": null, "deliveryMin": 24, "deliveryMax": 48, "deliveryUnit": "HORAS", "recommended": true, "cityIds": [ "1101" ] } ], "paymentOptions": [ { "id": "__stripe__", "kind": "stripe", "label": "Tarjeta de crédito/débito (Stripe)", "requireProof": false, "fields": { "email": "optional", "name": "required", "lastName": "required", "address": "required", "city": "required", "document": "optional" }, "request": { "paymentMethod": "TARJETA", "viaPagopar": false, "viaStripe": true }, "stripe": { "maxTotal": 5000000 } }, { "id": "7a8b9c0d", "kind": "manual", "label": "Transferencia bancaria", "requireProof": true, "fields": { "email": "optional", "name": "required", "lastName": "required", "address": "required", "city": "required", "document": "optional" }, "request": { "paymentMethod": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "viaPagopar": false }, "manual": { "name": "Transferencia bancaria", "type": "TRANSFER", "instructions": "Transferí el total y subí el comprobante.", "logoUrl": null, "accounts": [ { "label": "Cuenta principal", "bank": "Banco Ejemplo", "holder": "Tienda Demo", "accountNumber": "1234567890", "ruc": "1234567-9", "alias": "tienda.demo" } ] } } ], "metaPixel": { "pixelId": "123456789012345", "requireCookieConsent": false, "trackPageView": true, "trackViewContent": true, "trackAddToCart": true, "trackInitiateCheckout": true, "trackPurchase": true, "trackCompleteRegistration": true, "trackLead": true, "trackSearch": true } } ``` ### GET /products Lista paginada de productos Devuelve productos `EN_VENTA` y `AGOTADO`, del más nuevo al más viejo. Los borradores y archivados nunca aparecen. Los filtros por atributo y por precio no están disponibles todavía. Cada producto trae solo su primera imagen; `GET /products/{id}` las trae todas. Bajo una ráfaga, esta lectura y la del detalle 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. Con `pk_` aplican los límites por visitante de la tienda; con `sk_`, solo el total de la tienda. Parámetros: - `q` (consulta, texto): Búsqueda sin distinguir acentos. Cada palabra tiene que aparecer en el nombre, la descripción, la categoría o las etiquetas. Máximo 100 caracteres. - `categoryId` (consulta, texto): Filtra por categoría; una categoría raíz incluye sus subcategorías visibles. Una categoría oculta, inexistente o de otra tienda devuelve una página vacía. De 1 a 64 caracteres. - `page` (consulta, entero): De 1 a 100000, por defecto 1. - `limit` (consulta, entero): De 1 a 100, por defecto 24. Respuestas: - 200: Página de productos. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/products \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "items": [ { "id": "clx0prod", "name": "Remera", "slug": "remera", "shortDescription": "Remera de algodón.", "brand": "Marca Demo", "status": "EN_VENTA", "purchasable": true, "isFeatured": false, "createdAt": "2026-10-01T12:00:00.000Z", "categoryId": "clx0cat", "price": 75000, "salePrice": null, "images": [ { "url": "https://img.example.com/remera-rojo.jpg", "alt": null } ], "variants": [ { "id": "clx0var", "name": "Color", "options": [ { "id": "clx0opt", "name": "Rojo", "status": "DISPONIBLE", "imageUrl": null } ] } ], "skus": [ { "id": "clx0sku", "key": "color:rojo", "price": 75000, "salePrice": null, "unitPrice": 75000, "stock": 12, "status": "DISPONIBLE", "options": [ { "variantName": "Color", "optionId": "clx0opt", "optionName": "Rojo" } ] } ] } ], "page": 1, "limit": 24, "total": 1, "hasMore": false } ``` ### GET /products/{id} Detalle de un producto Incluye todas las imágenes, variantes, SKU comprables, stock online y ofertas. Parámetros: - `id` (ruta, texto, requerido) Respuestas: - 200: Producto. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/products/clx0prod \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "id": "clx0prod", "name": "Remera", "slug": "remera", "shortDescription": "Remera de algodón.", "brand": "Marca Demo", "status": "EN_VENTA", "purchasable": true, "isFeatured": false, "createdAt": "2026-10-01T12:00:00.000Z", "categoryId": "clx0cat", "price": 75000, "salePrice": null, "images": [ { "url": "https://img.example.com/remera-rojo.jpg", "alt": null } ], "variants": [ { "id": "clx0var", "name": "Color", "options": [ { "id": "clx0opt", "name": "Rojo", "status": "DISPONIBLE", "imageUrl": null } ] } ], "skus": [ { "id": "clx0sku", "key": "color:rojo", "price": 75000, "salePrice": null, "unitPrice": 75000, "stock": 12, "status": "DISPONIBLE", "options": [ { "variantName": "Color", "optionId": "clx0opt", "optionName": "Rojo" } ] } ], "description": "

Remera de algodón peinado.

", "metaTitle": null, "metaDescription": null, "offers": { "quantityOffer": { "id": "clx0offer", "name": "Llevá 2 y ahorrá", "combinesWithCoupons": true, "tiers": [ { "minQuantity": 2, "discountType": "PERCENT", "value": 20, "label": "2 unidades", "badge": null, "preselected": false } ] }, "combo": null } } ``` ### GET /products/by-slug/{slug} Detalle de un producto por su slug Responde lo mismo que `GET /products/{id}`. La coincidencia es exacta y no admite un id. Un slug mal formado, uno de otra tienda o uno que ya no existe responden el mismo 404 `PRODUCT_NOT_FOUND`. Parámetros: - `slug` (ruta, texto, requerido): Patrón ^[a-z0-9-]{1,64}$. Respuestas: - 200: Producto. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/products/by-slug/remera \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "id": "clx0prod", "name": "Remera", "slug": "remera", "shortDescription": "Remera de algodón.", "brand": "Marca Demo", "status": "EN_VENTA", "purchasable": true, "isFeatured": false, "createdAt": "2026-10-01T12:00:00.000Z", "categoryId": "clx0cat", "price": 75000, "salePrice": null, "images": [ { "url": "https://img.example.com/remera-rojo.jpg", "alt": null } ], "variants": [ { "id": "clx0var", "name": "Color", "options": [ { "id": "clx0opt", "name": "Rojo", "status": "DISPONIBLE", "imageUrl": null } ] } ], "skus": [ { "id": "clx0sku", "key": "color:rojo", "price": 75000, "salePrice": null, "unitPrice": 75000, "stock": 12, "status": "DISPONIBLE", "options": [ { "variantName": "Color", "optionId": "clx0opt", "optionName": "Rojo" } ] } ], "description": "

Remera de algodón peinado.

", "metaTitle": null, "metaDescription": null, "offers": { "quantityOffer": { "id": "clx0offer", "name": "Llevá 2 y ahorrá", "combinesWithCoupons": true, "tiers": [ { "minQuantity": 2, "discountType": "PERCENT", "value": 20, "label": "2 unidades", "badge": null, "preselected": false } ] }, "combo": null } } ``` ### GET /categories Categorías visibles de la tienda Las mismas que muestra la grilla de categorías de la tienda. Una categoría raíz sin productos visibles, propios o de sus subcategorías visibles, no aparece. Respuestas: - 200: Categorías, con un nivel de subcategorías. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/categories \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "items": [ { "id": "clx0cat", "name": "Remeras", "slug": "remeras", "description": null, "imageUrl": null, "children": [ { "id": "clx0sub", "name": "Manga corta", "slug": "manga-corta", "description": null, "imageUrl": null } ] } ] } ``` ### GET /geo/cities Catálogo de departamentos y ciudades Catálogo INE de Paraguay. El `code` de una ciudad es el valor de `cityId` en `POST /cart/quote` y `POST /checkout`, y el que aparece en `Store.shippingMethods[].cityIds`. Parámetros: - `departmentCode` (consulta, texto): Filtra las ciudades de un departamento. Patrón ^[0-9]{2}$. Respuestas: - 200: Catálogo. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/geo/cities \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "departments": [ { "code": "11", "name": "CENTRAL" } ], "cities": [ { "code": "1101", "departmentCode": "11", "name": "AREGUÁ" } ] } ``` ### POST /cart/quote Cotiza las líneas del carrito No hay carrito en el servidor: la landing guarda las líneas y esta operación las cotiza. No escribe nada, no reserva stock y no tiene vencimiento: el checkout vuelve a calcular todo con los datos de ese momento. Sin datos del comprador, `perCustomerLimit` y `maxRedemptions` de un cupón solo se verifican en el checkout. Cuerpo (`application/json`, requerido): - `items` (lista de objetos, requerido): De 1 a 100 elementos. - `productId` (texto, requerido) - `skuId` (texto): Obligatorio en productos con variantes. En un producto simple se omite y el servidor usa su SKU por defecto. - `quantity` (entero, requerido): De 1 a 100000. - `shippingMethodId` (texto): Id de un método, o `NINGUNO` para «Retiro en local / Sin envío». - `cityId` (texto): Código de `GET /geo/cities`. Decide la cobertura de envío. - `couponCode` (texto): De 1 a 64 caracteres. Respuestas: - 200: Cotización. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 422 (`SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`): `SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/cart/quote \ -H "Authorization: Bearer pk_..." \ -H "Content-Type: application/json" \ -d '{ "items": [ { "productId": "clx0prod", "skuId": "clx0sku", "quantity": 2 } ], "shippingMethodId": "1f2e3d4c", "cityId": "1101", "couponCode": "VERANO" }' ``` Ejemplo de respuesta (200): ```json { "currency": "PYG", "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "unitPrice": 75000, "listTotal": 150000, "bundleDiscount": 30000, "bundleName": "Llevá 2 y ahorrá", "total": 120000 } ], "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponDiscount": 20000, "shippingPrice": 15000, "total": 115000, "availableShippingMethodIds": [ "1f2e3d4c" ], "stockIssues": [] } ``` ### POST /checkout Crea un pedido como invitado Crea el pedido y devuelve su `publicToken`, con el que se opera después. Los rechazos no escriben nada: ni pedido, ni cliente, ni canje de cupón. El stock se verifica acá, no se reserva: se descuenta recién al despachar o entregar. Dos compradores pueden pasar a la vez por la última unidad. Se verifica el stock online (la suma de las ubicaciones que despachan pedidos online). No hay retiro en sucursal: un pedido con un método de tipo `RETIRO` se crea sin sucursal elegida y se verifica contra el mismo stock online. Una tienda armada por una ráfaga exige ALTCHA: 403 `ALTCHA_REQUIRED`. Está pensado para llamarse desde el navegador con `pk_`. Con `sk_` se aceptan los mismos datos y se aplican los mismos límites, incluido el de IP y tienda: todos los compradores de un servidor son una sola IP, y Meta recibe la IP y el navegador de ese servidor. Una tienda armada le exige ALTCHA igual. Parámetros: - `Idempotency-Key` (encabezado, texto, requerido): Identificador único por intento de compra (se recomienda un UUID v4), con caracteres ASCII imprimibles y sin espacios. Reenviar la misma clave con el mismo cuerpo devuelve el pedido ya creado, sin repetir ningún efecto. Para comparar cuerpos cuentan los campos del contrato, sin importar su orden, y no cuentan `altchaChallenge`, `altchaSolution` ni `metaContext`. Solo se registra cuando se crea un pedido: un intento rechazado se puede repetir con la misma clave. De 8 a 128 caracteres. Cuerpo (`application/json`, requerido): Se ignora cualquier total, y también `storeId`, `isExistingCustomer` y campos desconocidos. Qué campos del comprador son obligatorios lo define `Store.checkout.fields`, salvo `tel`, siempre obligatorio. - `items` (lista de objetos, requerido): De 1 a 100 elementos. - `productId` (texto, requerido) - `skuId` (texto): Obligatorio en productos con variantes. En un producto simple se omite y el servidor usa su SKU por defecto. - `quantity` (entero, requerido): De 1 a 100000. - `tel` (texto, requerido): Teléfono en cualquier forma legible (`0981...`, `981...`, `595981...`, `+595...`). Sin código de país se interpreta como Paraguay y se guarda en E.164. - `email` (texto (email)): Opcional salvo que la tienda lo exija. Identifica al comprador junto con `tel`. Vacío equivale a ausente. Mal formado responde 400 `INVALID_BODY`, también si la tienda oculta el campo. - `name` (texto) - `lastName` (texto) - `ruc` (texto): Número de documento. - `taxIdCountry` (texto): País del documento. Hoy: `PY`. Va junto con `taxIdType`. Valores: `PY`. - `taxIdType` (texto): Tipo de documento. Con el par presente, el servidor valida `ruc`, incluido el dígito verificador. Valores: `RUC`, `CI`, `PASSPORT`, `FOREIGN_ID`, `RESIDENCE_CARD`, `DIPLOMATIC_CARD`, `OTHER`, `UNNAMED`. - `rucName` (texto): Razón social. - `cityId` (texto): Código de `GET /geo/cities`. Desconocido o retirado responde 400. Gana sobre `city`. - `city` (texto): Texto libre, solo cuando no hay `cityId`. Si no coincide exactamente con una ciudad, el pedido sale igual, sin control de cobertura. - `direction1` (texto) - `direction2` (texto): Referencia o apartado. - `shippingMethodId` (texto): Id de un método activo de la tienda, o `NINGUNO`/ausente para «Retiro en local / Sin envío». Con un método de tipo `RETIRO` no se puede elegir la sucursal: el pedido se crea sin ella. - `paymentMethod` (texto, requerido): Valores: `TARJETA`, `EFECTIVO`, `TRANSFERENCIA`. - `customPaymentMethodId` (texto): Solo en opciones `manual`. Tiene que ser un método activo de la tienda. - `viaPagopar` (booleano, requerido): Obligatorio, y hoy siempre `false`: Pagopar está retirado y `true` responde 400 `PAGOPAR_NOT_ACTIVE`. - `viaStripe` (booleano): `true` si este pedido se paga con tarjeta (Stripe): la opción `stripe` de `store.paymentOptions`. Opcional; ausente equivale a `false`. Exige `TARJETA`, sin `customPaymentMethodId` y con `viaPagopar: false` (si no, 400 `PAYMENT_METHOD_UNAVAILABLE`). Si la tienda no lo tiene disponible, 400 `STRIPE_NOT_AVAILABLE` o `STRIPE_CURRENCY_NOT_SUPPORTED`; si el total supera `stripe.maxTotal`, 400 `STRIPE_AMOUNT_NOT_ALLOWED`. El pedido se paga después con `POST /orders/{token}/pay`. - `couponCode` (texto): Solo el código; el descuento lo calcula el servidor. De 1 a 64 caracteres. - `deliveryLocation` (objeto): Punto de entrega opcional. Un valor inválido se descarta, nunca frena la venta. - `lat` (número, requerido): De -90 a 90. - `lng` (número, requerido): De -180 a 180. - `source` (texto, requerido): Valores: `GPS`, `LINK`, `MANUAL`. - `accuracyM` (número o nulo): Mínimo 0. - `metaContext` (objeto): Contexto opcional para la API de Conversiones de Meta. Nunca decide si se crea el pedido. - `eventSourceUrl` (texto): Máximo 2048 caracteres. - `fbclid` (texto): Máximo 500 caracteres. - `fbp` (texto): Valor de la cookie `_fbp` de la landing. Si es inválido, se descarta. - `fbc` (texto): Valor de la cookie `_fbc` de la landing. Si es inválido, se descarta. - `consent` (texto): Valores: `granted`, `denied`, `unknown`. - `initiateCheckoutEventId` (texto (uuid)): UUID v4 con el que el navegador disparó InitiateCheckout. Si es inválido, el servidor no envía ese evento. - `altchaChallenge` (objeto): El desafío de `GET /altcha/challenge`, tal como se recibió. - `altchaSolution` (objeto): La solución devuelta por `altcha-lib`. Respuestas: - 200: Repetición de un pedido ya creado con esta clave. - 201: Pedido creado. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 409 (`INSUFFICIENT_STOCK`, `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS`, `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`, `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`): `INSUFFICIENT_STOCK` (con `details`), `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS` (el intento concurrente con esa clave no terminó a tiempo; reintentar), `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`, `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`. El tope de canjes de un cupón responde 409 solo con `message`. - 422 (`SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`): `SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/checkout \ -H "Authorization: Bearer pk_..." \ -H "Idempotency-Key: 0b5c1a9e-7d2f-4c68-9a3e-5f1d2b7c8e90" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "productId": "clx0prod", "skuId": "clx0sku", "quantity": 2 } ], "tel": "0981123456", "email": "ana@example.com", "name": "Ana", "lastName": "Gómez", "ruc": "1234567-9", "taxIdCountry": "PY", "taxIdType": "RUC", "rucName": "Ana Gómez", "cityId": "1101", "city": "Areguá", "direction1": "Av. Mariscal López 1234", "direction2": "Casa con portón negro", "shippingMethodId": "1f2e3d4c", "paymentMethod": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "viaPagopar": false, "viaStripe": false, "couponCode": "VERANO", "deliveryLocation": { "lat": -25.3083, "lng": -57.3842, "source": "GPS", "accuracyM": 12 }, "metaContext": { "eventSourceUrl": "https://landing.example.com/checkout", "fbclid": "IwAR0ejemplo", "fbp": "fb.1.1793718245000.1234567890", "fbc": "fb.1.1793718245000.IwAR0ejemplo", "consent": "granted", "initiateCheckoutEventId": "5d3f9a1c-2b47-4e80-8c6d-1a2b3c4d5e6f" } }' ``` Ejemplo de respuesta (201): ```json { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "metaPurchase": { "eventId": "purchase-1234", "due": true, "params": { "value": 115000, "currency": "PYG", "order_id": "1234" } }, "trackingUrl": "https://www.tiendy.com.py/tienda-demo/order/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13", "publicToken": "3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13", "metaEvents": [ { "name": "Lead", "eventId": "lead-1234", "params": { "value": 115000 } } ] } ``` ### GET /altcha/challenge Emite un desafío ALTCHA Desafío firmado de prueba de trabajo (`PBKDF2/SHA-256`), válido por 10 minutos y de un solo uso. Responde 404 cuando ALTCHA no está configurado en la plataforma: en ese caso ninguna tienda lo exige. Respuestas: - 200: Desafío, para resolver con `altcha-lib`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/altcha/challenge \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json {} ``` ### GET /orders/{token} Estado de un pedido Sigue disponible con la tienda pausada o archivada. No incluye datos personales del comprador. Parámetros: - `token` (ruta, texto (uuid), requerido): `publicToken` del pedido. Un token de otra tienda responde 404. Respuestas: - 200: Pedido. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/orders/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13 \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "metaPurchase": { "eventId": "purchase-1234", "due": true, "params": { "value": 115000, "currency": "PYG", "order_id": "1234" } }, "trackingUrl": "https://www.tiendy.com.py/tienda-demo/order/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13", "publicToken": "3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13" } ``` ### GET /orders/by-payment-hash/{hash} Estado de un pedido por hash de Pagopar **Pagopar está retirado**: este endpoint sigue respondiendo por los pedidos que tienen un hash de Pagopar. Un pedido pagado con tarjeta (Stripe) no tiene hash y se consulta con `GET /orders/{token}`. Para la página de retorno de Pagopar, que solo recibe el hash. Si el pedido no figura pagado, Tiendy le consulta a Pagopar y aplica la misma confirmación que el webhook, de modo que un webhook perdido no deja impago un pedido pagado. La landing nunca decide el estado. No se le consulta a Pagopar por un pedido ya pagado o cancelado, y si la consulta falla o se supera el tope de consultas de la tienda se responde el estado guardado. El hash de un intento reemplazado por un nuevo `POST /orders/{token}/pay` deja de encontrarse. Sigue disponible si la tienda pierde el plan `PRO`. Parámetros: - `hash` (ruta, texto, requerido) Respuestas: - 200: Pedido, sin `publicToken`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/orders/by-payment-hash/0a1b2c3d4e5f60718293a4b5c6d7e8f9 \ -H "Authorization: Bearer pk_..." ``` Ejemplo de respuesta (200): ```json { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "metaPurchase": { "eventId": "purchase-1234", "due": true, "params": { "value": 115000, "currency": "PYG", "order_id": "1234" } }, "trackingUrl": null } ``` ### POST /orders/{token}/pay Inicia el pago con tarjeta (Stripe) Para un pedido creado con la opción `stripe` (`viaStripe: true`): devuelve la URL de pago de Stripe a la que se redirige al comprador. El plazo para pagar es de 24 horas. Para reintentar, se vuelve a llamar con el mismo pedido: nunca se crea otro, y mientras la sesión siga abierta la respuesta es la misma `url`. 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. `returnUrl` es obligatorio. Stripe devuelve al comprador a esa URL con `order=` y `status=success` o `status=cancelled` agregados por el servidor, conservando los parámetros y el fragmento que ya tenía. Llegar a esa URL no prueba nada: la landing lee `GET /orders/{token}`. El pago lo confirma solo el webhook firmado de Stripe a Tiendy. Rechazos propios: 400 `RETURN_URL_INVALID`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`; 409 `ORDER_NOT_PAYABLE` (pagado, cancelado o con la sesión vencida) y `ORDER_CHANGED` (dos inicios simultáneos: reintentar); 503 `SERVICE_UNAVAILABLE` (Stripe no respondió: reintentar). Un pedido que no se creó con la opción `stripe` responde 400 `PAGOPAR_NOT_ACTIVE`, porque Pagopar está retirado; su cuerpo se ignora. Parámetros: - `token` (ruta, texto (uuid), requerido): `publicToken` del pedido. Un token de otra tienda responde 404. Cuerpo (`application/json`, requerido): - `returnUrl` (texto (uri), requerido): La página de la landing a la que Stripe devuelve al comprador. URL completa `https`, sin usuario ni contraseña, cuyo origen (esquema, host y puerto) es uno de los orígenes autorizados de la tienda, también con una clave `sk_`. `http` solo para `localhost`, `127.0.0.1` y `[::1]`, si ese origen está registrado. Si no, 400 `RETURN_URL_INVALID`. Máximo 2000 caracteres. Respuestas: - 200: Sesión de pago creada, o la que ya estaba abierta. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 409 (`INSUFFICIENT_STOCK`, `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS`, `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`, `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`): `INSUFFICIENT_STOCK` (con `details`), `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS` (el intento concurrente con esa clave no terminó a tiempo; reintentar), `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`, `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`. El tope de canjes de un cupón responde 409 solo con `message`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/orders/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13/pay \ -H "Authorization: Bearer pk_..." \ -H "Content-Type: application/json" \ -d '{ "returnUrl": "https://landing.example.com/pago" }' ``` Ejemplo de respuesta (200): ```json { "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8i9J0" } ``` ### POST /orders/{token}/proof/upload Sube el archivo del comprobante (paso 1) Sube el archivo y devuelve su clave. Todavía no queda asociado al pedido: eso lo hace `POST /orders/{token}/proof`. Máximo 10 MB y encabezado `Content-Length` obligatorio. Tipos: JPEG, PNG, WebP, GIF y PDF; el contenido se verifica contra el tipo declarado. Parámetros: - `token` (ruta, texto (uuid), requerido): `publicToken` del pedido. Un token de otra tienda responde 404. Cuerpo (`multipart/form-data`, requerido): - `file` (texto (binary), requerido) Respuestas: - 200: Archivo guardado. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 413 (`FILE_TOO_LARGE`): `FILE_TOO_LARGE`: más de 10 MB, o `Content-Length` ausente o inválido. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/orders/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13/proof/upload \ -H "Authorization: Bearer pk_..." \ -F "file=@" ``` Ejemplo de respuesta (200): ```json { "key": "uploads/checkout-proof/clx0store/7f3c2a10-8f0b-4a3e-9a51-0d2b6c1e4f77.jpg" } ``` ### POST /orders/{token}/proof Asocia el comprobante al pedido (paso 2) Se acepta una sola vez, solo en pedidos con método de pago manual y no cancelados. `proofUrl` tiene que ser una clave emitida por el paso 1 para esta tienda, nunca una URL. Sigue disponible con la tienda pausada o archivada. Parámetros: - `token` (ruta, texto (uuid), requerido): `publicToken` del pedido. Un token de otra tienda responde 404. Cuerpo (`application/json`, requerido): - `proofUrl` (texto, requerido): De 1 a 300 caracteres. Respuestas: - 200: Comprobante guardado. - 400 (`INVALID_QUERY`, `INVALID_BODY`, `IDEMPOTENCY_KEY_REQUIRED`, `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`, `STRIPE_NOT_AVAILABLE`, `STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`, `RETURN_URL_INVALID`, `PAGOPAR_NOT_ACTIVE`, `PAGOPAR_REJECTED`, `FILE_INVALID`): Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está fuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los tipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada), `SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE` (un método manual inactivo, un método estándar en una tienda con otro medio configurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de `TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago con tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en guaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta), `STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID` (`returnUrl` ausente o que no es una URL `https` de un origen autorizado), `PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de usarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no permitido o contenido que no coincide). Muchos rechazos del checkout (datos del comprador, ciudad, cupón, líneas) solo traen `message`. - 401 (`API_KEY_INVALID`): Clave ausente, inválida o revocada: `API_KEY_INVALID`. - 403 (`STOREFRONT_API_PLAN_REQUIRED`, `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE`, `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`): `STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a `GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`), `ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o archivada; solo catálogo, cotización y checkout), o en el checkout `ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`. - 404 (`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`): No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos: `ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`. - 409 (`INSUFFICIENT_STOCK`, `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS`, `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`, `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`): `INSUFFICIENT_STOCK` (con `details`), `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS` (el intento concurrente con esa clave no terminó a tiempo; reintentar), `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`, `PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`. El tope de canjes de un cupón responde 409 solo con `message`. - 422 (`SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`): `SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`. - 429 (`RATE_LIMITED`): `RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada. - 500: Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`. - 503 (`SERVICE_UNAVAILABLE`): `SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o Stripe no respondió al iniciar un pago. No dice nada de la clave ni del plan: reintentar después de `Retry-After`. Ejemplo de pedido: ```bash curl https://www.tiendy.com.py/api/storefront/v1/orders/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13/proof \ -H "Authorization: Bearer pk_..." \ -H "Content-Type: application/json" \ -d '{ "proofUrl": "uploads/checkout-proof/clx0store/7f3c2a10-8f0b-4a3e-9a51-0d2b6c1e4f77.jpg" }' ``` Ejemplo de respuesta (200): ```json { "ok": true } ``` ## Eventos de webhook Eventos que Tiendy envía al endpoint del comercio. ### order.created Se creó un pedido Un pedido nuevo de la tienda, de cualquier canal (`data.order.source`). Si nace pagado (una venta de caja cobrada), también llega `order.paid`. Encabezados: - `Tiendy-Signature` (encabezado, texto, requerido): `t=,v1=`: HMAC-SHA256 con el secreto del endpoint sobre `.`. - `Tiendy-Event-Id` (encabezado, texto (uuid), requerido): Igual a `id` del cuerpo. Sirve para descartar repeticiones. - `Tiendy-Event-Type` (encabezado, texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. Cuerpo (`application/json`, requerido): - `id` (texto (uuid), requerido): Id del evento. Es el mismo en todos los endpoints de la tienda y en cada reintento. - `type` (texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. - `createdAt` (texto (date-time), requerido): Cuándo ocurrió el evento. Los eventos pueden llegar desordenados. - `storeId` (texto, requerido) - `data` (objeto, requerido) - `order` (objeto, requerido): El mismo `OrderView` que devuelve la API, sin `metaPurchase` (es solo para el navegador) y con el canal del pedido. Sin datos del comprador ni `publicToken`; `trackingUrl` siempre es `null`. - `id` (entero, requerido): Número de pedido, para mostrar. Es correlativo y no sirve para operar. - `status` (texto, requerido): Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. - `paymentStatus` (texto, requerido): Valores: `PENDIENTE`, `PARCIAL`, `PAGADO`, `CANCELADO`. - `createdAt` (texto (date-time), requerido) - `currency` (texto, requerido) - `listSubtotal` (entero) - `bundleSavings` (entero) - `subtotal` (entero) - `couponCode` (texto o nulo) - `couponDiscount` (entero) - `shippingName` (texto o nulo) - `shippingPrice` (entero o nulo): Nulo si el pedido no tiene método de envío. - `total` (entero, requerido): Es el monto que vale. Hay que mostrar este, no el cotizado. - `lines` (lista de objetos, requerido) - `productId` (texto o nulo, requerido) - `skuId` (texto o nulo) - `productName` (texto o nulo, requerido) - `variantLabel` (texto o nulo) - `quantity` (entero, requerido) - `bundleName` (texto o nulo) - `bundleDiscount` (entero, requerido) - `total` (entero, requerido): Lo cobrado, neto de la oferta. - `payment` (objeto, requerido) - `method` (texto o nulo, requerido): Valores: `TARJETA`, `EFECTIVO`, `TRANSFERENCIA`. - `customPaymentMethodId` (texto o nulo) - `customPaymentMethodName` (texto o nulo) - `gateway` (texto o nulo): `stripe` en un pedido creado con la opción `stripe`: se paga con `POST /orders/{token}/pay`. `null` en todos los demás. Valores: `stripe`, `null`. - `proof` (objeto, requerido) - `requested` (booleano, requerido): Mostrar la invitación a subir el comprobante. - `uploaded` (booleano, requerido) - `trackingUrl` (texto (uri) o nulo): Página de seguimiento en Tiendy, la misma que reciben los emails del comprador. Siempre `null` en `GET /orders/by-payment-hash/{hash}`: la URL incluye el `publicToken`. - `source` (texto o nulo, requerido): Canal del pedido. `null` en pedidos anteriores a la columna. Valores: `STOREFRONT`, `STOREFRONT_API`, `MARKETPLACE`, `ADMIN`, `POS`, `null`. Respuestas: - 2XX: Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido. Ejemplo del cuerpo: ```json { "id": "7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11", "type": "order.created", "createdAt": "2026-11-03T15:04:05.000Z", "storeId": "clx0store", "data": { "order": { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "trackingUrl": null, "source": "STOREFRONT_API" } } } ``` ### order.paid Un pedido pasó a pagado El pedido entró en `paymentStatus = PAGADO` (pago con tarjeta confirmado por Stripe, pagos cargados en el panel o cobros de Envíos). Encabezados: - `Tiendy-Signature` (encabezado, texto, requerido): `t=,v1=`: HMAC-SHA256 con el secreto del endpoint sobre `.`. - `Tiendy-Event-Id` (encabezado, texto (uuid), requerido): Igual a `id` del cuerpo. Sirve para descartar repeticiones. - `Tiendy-Event-Type` (encabezado, texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. Cuerpo (`application/json`, requerido): - `id` (texto (uuid), requerido): Id del evento. Es el mismo en todos los endpoints de la tienda y en cada reintento. - `type` (texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. - `createdAt` (texto (date-time), requerido): Cuándo ocurrió el evento. Los eventos pueden llegar desordenados. - `storeId` (texto, requerido) - `data` (objeto, requerido) - `order` (objeto, requerido): El mismo `OrderView` que devuelve la API, sin `metaPurchase` (es solo para el navegador) y con el canal del pedido. Sin datos del comprador ni `publicToken`; `trackingUrl` siempre es `null`. - `id` (entero, requerido): Número de pedido, para mostrar. Es correlativo y no sirve para operar. - `status` (texto, requerido): Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. - `paymentStatus` (texto, requerido): Valores: `PENDIENTE`, `PARCIAL`, `PAGADO`, `CANCELADO`. - `createdAt` (texto (date-time), requerido) - `currency` (texto, requerido) - `listSubtotal` (entero) - `bundleSavings` (entero) - `subtotal` (entero) - `couponCode` (texto o nulo) - `couponDiscount` (entero) - `shippingName` (texto o nulo) - `shippingPrice` (entero o nulo): Nulo si el pedido no tiene método de envío. - `total` (entero, requerido): Es el monto que vale. Hay que mostrar este, no el cotizado. - `lines` (lista de objetos, requerido) - `productId` (texto o nulo, requerido) - `skuId` (texto o nulo) - `productName` (texto o nulo, requerido) - `variantLabel` (texto o nulo) - `quantity` (entero, requerido) - `bundleName` (texto o nulo) - `bundleDiscount` (entero, requerido) - `total` (entero, requerido): Lo cobrado, neto de la oferta. - `payment` (objeto, requerido) - `method` (texto o nulo, requerido): Valores: `TARJETA`, `EFECTIVO`, `TRANSFERENCIA`. - `customPaymentMethodId` (texto o nulo) - `customPaymentMethodName` (texto o nulo) - `gateway` (texto o nulo): `stripe` en un pedido creado con la opción `stripe`: se paga con `POST /orders/{token}/pay`. `null` en todos los demás. Valores: `stripe`, `null`. - `proof` (objeto, requerido) - `requested` (booleano, requerido): Mostrar la invitación a subir el comprobante. - `uploaded` (booleano, requerido) - `trackingUrl` (texto (uri) o nulo): Página de seguimiento en Tiendy, la misma que reciben los emails del comprador. Siempre `null` en `GET /orders/by-payment-hash/{hash}`: la URL incluye el `publicToken`. - `source` (texto o nulo, requerido): Canal del pedido. `null` en pedidos anteriores a la columna. Valores: `STOREFRONT`, `STOREFRONT_API`, `MARKETPLACE`, `ADMIN`, `POS`, `null`. Respuestas: - 2XX: Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido. Ejemplo del cuerpo: ```json { "id": "7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11", "type": "order.paid", "createdAt": "2026-11-03T15:04:05.000Z", "storeId": "clx0store", "data": { "order": { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "trackingUrl": null, "source": "STOREFRONT_API" } } } ``` ### order.status_changed Cambió el estado de un pedido `data.previousStatus` es el estado anterior y `data.status` el nuevo. Encabezados: - `Tiendy-Signature` (encabezado, texto, requerido): `t=,v1=`: HMAC-SHA256 con el secreto del endpoint sobre `.`. - `Tiendy-Event-Id` (encabezado, texto (uuid), requerido): Igual a `id` del cuerpo. Sirve para descartar repeticiones. - `Tiendy-Event-Type` (encabezado, texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. Cuerpo (`application/json`, requerido): - `id` (texto (uuid), requerido): Id del evento. Es el mismo en todos los endpoints de la tienda y en cada reintento. - `type` (texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. - `createdAt` (texto (date-time), requerido): Cuándo ocurrió el evento. Los eventos pueden llegar desordenados. - `storeId` (texto, requerido) - `data` (objeto, requerido) - `order` (objeto, requerido): El mismo `OrderView` que devuelve la API, sin `metaPurchase` (es solo para el navegador) y con el canal del pedido. Sin datos del comprador ni `publicToken`; `trackingUrl` siempre es `null`. - `id` (entero, requerido): Número de pedido, para mostrar. Es correlativo y no sirve para operar. - `status` (texto, requerido): Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. - `paymentStatus` (texto, requerido): Valores: `PENDIENTE`, `PARCIAL`, `PAGADO`, `CANCELADO`. - `createdAt` (texto (date-time), requerido) - `currency` (texto, requerido) - `listSubtotal` (entero) - `bundleSavings` (entero) - `subtotal` (entero) - `couponCode` (texto o nulo) - `couponDiscount` (entero) - `shippingName` (texto o nulo) - `shippingPrice` (entero o nulo): Nulo si el pedido no tiene método de envío. - `total` (entero, requerido): Es el monto que vale. Hay que mostrar este, no el cotizado. - `lines` (lista de objetos, requerido) - `productId` (texto o nulo, requerido) - `skuId` (texto o nulo) - `productName` (texto o nulo, requerido) - `variantLabel` (texto o nulo) - `quantity` (entero, requerido) - `bundleName` (texto o nulo) - `bundleDiscount` (entero, requerido) - `total` (entero, requerido): Lo cobrado, neto de la oferta. - `payment` (objeto, requerido) - `method` (texto o nulo, requerido): Valores: `TARJETA`, `EFECTIVO`, `TRANSFERENCIA`. - `customPaymentMethodId` (texto o nulo) - `customPaymentMethodName` (texto o nulo) - `gateway` (texto o nulo): `stripe` en un pedido creado con la opción `stripe`: se paga con `POST /orders/{token}/pay`. `null` en todos los demás. Valores: `stripe`, `null`. - `proof` (objeto, requerido) - `requested` (booleano, requerido): Mostrar la invitación a subir el comprobante. - `uploaded` (booleano, requerido) - `trackingUrl` (texto (uri) o nulo): Página de seguimiento en Tiendy, la misma que reciben los emails del comprador. Siempre `null` en `GET /orders/by-payment-hash/{hash}`: la URL incluye el `publicToken`. - `source` (texto o nulo, requerido): Canal del pedido. `null` en pedidos anteriores a la columna. Valores: `STOREFRONT`, `STOREFRONT_API`, `MARKETPLACE`, `ADMIN`, `POS`, `null`. - `previousStatus` (texto, requerido): Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. - `status` (texto, requerido): Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. Respuestas: - 2XX: Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido. Ejemplo del cuerpo: ```json { "id": "7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11", "type": "order.status_changed", "createdAt": "2026-11-03T15:04:05.000Z", "storeId": "clx0store", "data": { "order": { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "trackingUrl": null, "source": "STOREFRONT_API" }, "previousStatus": "PENDIENTE", "status": "PREPARANDO" } } ``` ### order.proof_uploaded El comprador subió el comprobante de pago Encabezados: - `Tiendy-Signature` (encabezado, texto, requerido): `t=,v1=`: HMAC-SHA256 con el secreto del endpoint sobre `.`. - `Tiendy-Event-Id` (encabezado, texto (uuid), requerido): Igual a `id` del cuerpo. Sirve para descartar repeticiones. - `Tiendy-Event-Type` (encabezado, texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. Cuerpo (`application/json`, requerido): - `id` (texto (uuid), requerido): Id del evento. Es el mismo en todos los endpoints de la tienda y en cada reintento. - `type` (texto, requerido): Valores: `order.created`, `order.paid`, `order.status_changed`, `order.proof_uploaded`. - `createdAt` (texto (date-time), requerido): Cuándo ocurrió el evento. Los eventos pueden llegar desordenados. - `storeId` (texto, requerido) - `data` (objeto, requerido) - `order` (objeto, requerido): El mismo `OrderView` que devuelve la API, sin `metaPurchase` (es solo para el navegador) y con el canal del pedido. Sin datos del comprador ni `publicToken`; `trackingUrl` siempre es `null`. - `id` (entero, requerido): Número de pedido, para mostrar. Es correlativo y no sirve para operar. - `status` (texto, requerido): Valores: `PENDIENTE`, `CONFIRMADO`, `PREPARANDO`, `EN_CAMINO`, `ENTREGADO`, `CANCELADO`. - `paymentStatus` (texto, requerido): Valores: `PENDIENTE`, `PARCIAL`, `PAGADO`, `CANCELADO`. - `createdAt` (texto (date-time), requerido) - `currency` (texto, requerido) - `listSubtotal` (entero) - `bundleSavings` (entero) - `subtotal` (entero) - `couponCode` (texto o nulo) - `couponDiscount` (entero) - `shippingName` (texto o nulo) - `shippingPrice` (entero o nulo): Nulo si el pedido no tiene método de envío. - `total` (entero, requerido): Es el monto que vale. Hay que mostrar este, no el cotizado. - `lines` (lista de objetos, requerido) - `productId` (texto o nulo, requerido) - `skuId` (texto o nulo) - `productName` (texto o nulo, requerido) - `variantLabel` (texto o nulo) - `quantity` (entero, requerido) - `bundleName` (texto o nulo) - `bundleDiscount` (entero, requerido) - `total` (entero, requerido): Lo cobrado, neto de la oferta. - `payment` (objeto, requerido) - `method` (texto o nulo, requerido): Valores: `TARJETA`, `EFECTIVO`, `TRANSFERENCIA`. - `customPaymentMethodId` (texto o nulo) - `customPaymentMethodName` (texto o nulo) - `gateway` (texto o nulo): `stripe` en un pedido creado con la opción `stripe`: se paga con `POST /orders/{token}/pay`. `null` en todos los demás. Valores: `stripe`, `null`. - `proof` (objeto, requerido) - `requested` (booleano, requerido): Mostrar la invitación a subir el comprobante. - `uploaded` (booleano, requerido) - `trackingUrl` (texto (uri) o nulo): Página de seguimiento en Tiendy, la misma que reciben los emails del comprador. Siempre `null` en `GET /orders/by-payment-hash/{hash}`: la URL incluye el `publicToken`. - `source` (texto o nulo, requerido): Canal del pedido. `null` en pedidos anteriores a la columna. Valores: `STOREFRONT`, `STOREFRONT_API`, `MARKETPLACE`, `ADMIN`, `POS`, `null`. Respuestas: - 2XX: Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido. Ejemplo del cuerpo: ```json { "id": "7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11", "type": "order.proof_uploaded", "createdAt": "2026-11-03T15:04:05.000Z", "storeId": "clx0store", "data": { "order": { "id": 1234, "status": "PENDIENTE", "paymentStatus": "PENDIENTE", "createdAt": "2026-11-03T15:04:05.000Z", "currency": "PYG", "listSubtotal": 150000, "bundleSavings": 30000, "subtotal": 120000, "couponCode": "VERANO", "couponDiscount": 20000, "shippingName": "Envío a domicilio", "shippingPrice": 15000, "total": 115000, "lines": [ { "productId": "clx0prod", "skuId": "clx0sku", "productName": "Remera", "variantLabel": "Color: Rojo", "quantity": 2, "bundleName": "Llevá 2 y ahorrá", "bundleDiscount": 30000, "total": 120000 } ], "payment": { "method": "TRANSFERENCIA", "customPaymentMethodId": "7a8b9c0d", "customPaymentMethodName": "Transferencia bancaria", "gateway": null }, "proof": { "requested": true, "uploaded": false }, "trackingUrl": null, "source": "STOREFRONT_API" } } } ```