{"openapi":"3.1.0","info":{"title":"Tiendy Storefront API","version":"1.0.0","license":{"name":"Propietaria","url":"https://www.tiendy.com.py"},"description":"**Primera versión (v1).** Los límites de frecuencia son provisorios: se revisan\ncon el tráfico real de la primera landing.\n\nPermite que la landing externa de un comercio venda a través de Tiendy.\nTiendy es la única autoridad de precios, envío, ofertas, cupones y totales:\nlos totales enviados por el cliente se ignoran. Guía de uso:\n`docs/STOREFRONT_API.md`.\n\n**Acceso.** Incluida solo en el plan Tiendy AI (`PRO`, el más caro). No se\ncompra por separado.\n\n**Claves.** Cada tienda tiene sus claves y cada clave determina la tienda, por\nlo que ningún request lleva `storeId`. Tiendy guarda solo el hash de las dos\nclases, así que una clave se ve una sola vez, al crearla.\n- `pk_`: publicable, para navegadores, limitada a los orígenes autorizados de\n  la tienda. Una clave `pk_` más el chequeo de origen **no es un límite de\n  seguridad**: la clave es visible y un cliente fuera del navegador puede\n  falsificar `Origin`. Por eso las reglas del servidor y los límites de\n  frecuencia se aplican siempre.\n- `sk_`: secreta, de servidor a servidor. Un request con\n  `sk_` y encabezado `Origin` se rechaza con 403 `SECRET_KEY_IN_BROWSER`.\n\n**CORS.** Un preflight `OPTIONS` no lleva `Authorization`, así que no puede\nresolver la tienda: responde 204 a cualquier origen, reflejándolo en\n`Access-Control-Allow-Origin` con `Vary: Origin`, sin credenciales,\ncon `Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key`.\nLa decisión real se toma en el request: con `pk_`, un `Origin` ausente o no\nautorizado recibe 403 `ORIGIN_NOT_ALLOWED`, sin encabezados CORS que permitan\nleer la respuesta. Toda otra respuesta refleja el `Origin` del request, para que\nun navegador pueda leer el error, y expone\n`Access-Control-Expose-Headers: Retry-After, Idempotency-Replayed`. Las cookies\nno se usan.\n\n**Orígenes.** Coincidencia exacta de esquema, host y puerto, sin comodines ni\nsubdominios implícitos. `https` obligatorio, salvo `localhost`, `127.0.0.1` y\n`[::1]` para desarrollo. `Origin: null` nunca está autorizado.\n\n**Montos.** Enteros en la moneda de la tienda (`GET /store`, `currency`), sin\ndecimales ni centavos. No se dividen por 100.\n\n**Caché.** Toda respuesta, también un error, lleva `Cache-Control: private, no-store`:\ndepende de la clave y del origen, y una lectura puede traer stock.\n\n**Stock.** El stock que devuelven el catálogo y la cotización es el que la tienda\nvende online: la suma de las ubicaciones que despachan pedidos online, lo mismo\nque verifica el checkout. En una tienda con una sola ubicación es su stock total.\nNo hay venta sin stock ni reserva.\n"},"servers":[{"url":"https://www.tiendy.com.py/api/storefront/v1","description":"Producción."}],"security":[{"publishableKey":[]},{"secretKey":[]}],"tags":[{"name":"Tienda","description":"Configuración pública de la tienda."},{"name":"Catálogo","description":"Productos, categorías y ciudades."},{"name":"Compra","description":"Cotización, creación del pedido y verificación antibots."},{"name":"Pedidos","description":"Pago, estado y comprobante de un pedido existente."},{"name":"Webhooks","description":"Eventos que Tiendy envía al endpoint del comercio."}],"paths":{"/store":{"get":{"tags":["Tienda"],"operationId":"getStore","summary":"Configuración pública de la tienda","description":"Todo lo que la landing necesita para armar un checkout: moneda, campos del\ncomprador, métodos de envío activos, opciones de pago y píxel. Con la tienda\npausada o archivada responde 403 `STORE_INACTIVE`, igual que todo el catálogo. Una\ntienda API-only no está cerrada: responde con normalidad.\n","responses":{"200":{"description":"Tienda.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/products":{"get":{"tags":["Catálogo"],"operationId":"listProducts","summary":"Lista paginada de productos","description":"Devuelve productos `EN_VENTA` y `AGOTADO`, del más nuevo al más viejo. Los\nborradores y archivados nunca aparecen. Los filtros por atributo y por\nprecio no están disponibles todavía.\n\nCada producto trae solo su primera imagen; `GET /products/{id}` las trae todas.\n\nBajo una ráfaga, esta lectura y la del detalle pueden servir la última respuesta\nconocida, de hasta 10 minutos, o responder 429 si no hay ninguna. Nunca responden\nun catálogo vacío por eso. Con `pk_` aplican los límites por visitante de la tienda;\ncon `sk_`, solo el total de la tienda.\n","parameters":[{"name":"q","example":"remera","in":"query","description":"Búsqueda sin distinguir acentos. Cada palabra tiene que aparecer en el\nnombre, la descripción, la categoría o las etiquetas.\n","schema":{"type":"string","maxLength":100}},{"name":"categoryId","example":"clx0cat","in":"query","description":"Filtra por categoría; una categoría raíz incluye sus subcategorías visibles. Una\ncategoría oculta, inexistente o de otra tienda devuelve una página vacía.\n","schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100000,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}}],"responses":{"200":{"description":"Página de productos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/products/{id}":{"get":{"tags":["Catálogo"],"operationId":"getProduct","summary":"Detalle de un producto","description":"Incluye todas las imágenes, variantes, SKU comprables, stock online y ofertas.","parameters":[{"name":"id","example":"clx0prod","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/products/by-slug/{slug}":{"get":{"tags":["Catálogo"],"operationId":"getProductBySlug","summary":"Detalle de un producto por su slug","description":"Responde lo mismo que `GET /products/{id}`. La coincidencia es exacta y no admite\nun id. Un slug mal formado, uno de otra tienda o uno que ya no existe responden\nel mismo 404 `PRODUCT_NOT_FOUND`.\n","parameters":[{"name":"slug","example":"remera","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,64}$"}}],"responses":{"200":{"description":"Producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/categories":{"get":{"tags":["Catálogo"],"operationId":"listCategories","summary":"Categorías visibles de la tienda","description":"Las mismas que muestra la grilla de categorías de la tienda. Una categoría raíz sin\nproductos visibles, propios o de sus subcategorías visibles, no aparece.\n","responses":{"200":{"description":"Categorías, con un nivel de subcategorías.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/geo/cities":{"get":{"tags":["Catálogo"],"operationId":"listCities","summary":"Catálogo de departamentos y ciudades","description":"Catálogo INE de Paraguay. El `code` de una ciudad es el valor de `cityId` en\n`POST /cart/quote` y `POST /checkout`, y el que aparece en\n`Store.shippingMethods[].cityIds`.\n","parameters":[{"name":"departmentCode","example":"11","in":"query","description":"Filtra las ciudades de un departamento.","schema":{"type":"string","pattern":"^[0-9]{2}$"}}],"responses":{"200":{"description":"Catálogo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoCatalog"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/cart/quote":{"post":{"tags":["Compra"],"operationId":"quoteCart","summary":"Cotiza las líneas del carrito","description":"No hay carrito en el servidor: la landing guarda las líneas y esta operación\nlas cotiza. No escribe nada, no reserva stock y no tiene vencimiento: el\ncheckout vuelve a calcular todo con los datos de ese momento.\n\nSin datos del comprador, `perCustomerLimit` y `maxRedemptions` de un cupón\nsolo se verifican en el checkout.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Cotización.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/checkout":{"post":{"tags":["Compra"],"operationId":"createCheckout","summary":"Crea un pedido como invitado","description":"Crea el pedido y devuelve su `publicToken`, con el que se opera después. Los\nrechazos no escriben nada: ni pedido, ni cliente, ni canje de cupón.\n\nEl stock se verifica acá, no se reserva: se descuenta recién al despachar o\nentregar. Dos compradores pueden pasar a la vez por la última unidad. Se verifica\nel stock online (la suma de las ubicaciones que despachan pedidos online).\n\nNo hay retiro en sucursal: un pedido con un método de tipo `RETIRO` se crea sin\nsucursal elegida y se verifica contra el mismo stock online.\n\nUna tienda armada por una ráfaga exige ALTCHA: 403 `ALTCHA_REQUIRED`.\n\nEstá pensado para llamarse desde el navegador con `pk_`. Con `sk_` se aceptan los\nmismos datos y se aplican los mismos límites, incluido el de IP y tienda: todos los\ncompradores de un servidor son una sola IP, y Meta recibe la IP y el navegador de ese\nservidor. Una tienda armada le exige ALTCHA igual.\n","parameters":[{"name":"Idempotency-Key","example":"0b5c1a9e-7d2f-4c68-9a3e-5f1d2b7c8e90","in":"header","required":true,"description":"Identificador único por intento de compra (se recomienda un UUID v4), con\ncaracteres ASCII imprimibles y sin espacios. Reenviar la misma clave con el mismo\ncuerpo devuelve el pedido ya creado, sin repetir ningún efecto. Para comparar\ncuerpos cuentan los campos del contrato, sin importar su orden, y no cuentan\n`altchaChallenge`, `altchaSolution` ni `metaContext`. Solo se registra cuando se\ncrea un pedido: un intento rechazado se puede repetir con la misma clave.\n","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Repetición de un pedido ya creado con esta clave.","headers":{"Idempotency-Replayed":{"description":"Siempre `true` en una repetición.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"201":{"description":"Pedido creado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/altcha/challenge":{"get":{"tags":["Compra"],"operationId":"getAltchaChallenge","summary":"Emite un desafío ALTCHA","description":"Desafío firmado de prueba de trabajo (`PBKDF2/SHA-256`), válido por 10\nminutos y de un solo uso. Responde 404 cuando ALTCHA no está configurado en\nla plataforma: en ese caso ninguna tienda lo exige.\n","responses":{"200":{"description":"Desafío, para resolver con `altcha-lib`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AltchaChallenge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/orders/{token}":{"get":{"tags":["Pedidos"],"operationId":"getOrder","summary":"Estado de un pedido","description":"Sigue disponible con la tienda pausada o archivada. No incluye datos personales\ndel comprador.\n","parameters":[{"$ref":"#/components/parameters/OrderToken"}],"responses":{"200":{"description":"Pedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/orders/by-payment-hash/{hash}":{"get":{"tags":["Pedidos"],"operationId":"getOrderByPaymentHash","summary":"Estado de un pedido por hash de Pagopar","description":"**Pagopar está retirado**: este endpoint sigue respondiendo por los pedidos que\ntienen un hash de Pagopar. Un pedido pagado con tarjeta (Stripe) no tiene hash y se\nconsulta con `GET /orders/{token}`.\n\nPara la página de retorno de Pagopar, que solo recibe el hash. Si el pedido no\nfigura pagado, Tiendy le consulta a Pagopar y aplica la misma confirmación que el\nwebhook, de modo que un webhook perdido no deja impago un pedido pagado. La\nlanding nunca decide el estado. No se le consulta a Pagopar por un pedido ya pagado o\ncancelado, y si la consulta falla o se supera el tope de consultas de la tienda se\nresponde el estado guardado. El hash de un intento reemplazado por un nuevo\n`POST /orders/{token}/pay` deja de encontrarse. Sigue disponible si la tienda\npierde el plan `PRO`.\n","parameters":[{"name":"hash","example":"0a1b2c3d4e5f60718293a4b5c6d7e8f9","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pedido, sin `publicToken`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderView"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/orders/{token}/pay":{"post":{"tags":["Pedidos"],"operationId":"payOrder","summary":"Inicia el pago con tarjeta (Stripe)","description":"Para un pedido creado con la opción `stripe` (`viaStripe: true`): devuelve la URL de\npago de Stripe a la que se redirige al comprador. El plazo para pagar es de 24 horas.\nPara reintentar, se vuelve a llamar con el mismo pedido: nunca se crea otro, y\nmientras la sesión siga abierta la respuesta es la misma `url`. La sesión queda\nfijada en el primer intento: un reintento con otro `returnUrl` devuelve la sesión\nya creada, con la página de retorno original.\n\n`returnUrl` es obligatorio. Stripe devuelve al comprador a esa URL con\n`order=<publicToken>` y `status=success` o `status=cancelled` agregados por el\nservidor, conservando los parámetros y el fragmento que ya tenía. Llegar a esa URL\nno prueba nada: la landing lee `GET /orders/{token}`. El pago lo confirma solo el\nwebhook firmado de Stripe a Tiendy.\n\nRechazos propios: 400 `RETURN_URL_INVALID`, `STRIPE_NOT_AVAILABLE`,\n`STRIPE_CURRENCY_NOT_SUPPORTED`, `STRIPE_AMOUNT_NOT_ALLOWED`, `STRIPE_REJECTED`;\n409 `ORDER_NOT_PAYABLE` (pagado, cancelado o con la sesión vencida) y\n`ORDER_CHANGED` (dos inicios simultáneos: reintentar); 503 `SERVICE_UNAVAILABLE`\n(Stripe no respondió: reintentar).\n\nUn pedido que no se creó con la opción `stripe` responde 400 `PAGOPAR_NOT_ACTIVE`,\nporque Pagopar está retirado; su cuerpo se ignora.\n","parameters":[{"$ref":"#/components/parameters/OrderToken"}],"requestBody":{"required":true,"description":"Obligatorio para un pedido creado con la opción de Stripe. Un pedido que no es de\nStripe, o uno ya pagado o cancelado, se responde sin leer el cuerpo.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayRequest"}}}},"responses":{"200":{"description":"Sesión de pago creada, o la que ya estaba abierta.","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"example":"https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8i9J0","type":"string","format":"uri","description":"Siempre una URL de `checkout.stripe.com`."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/orders/{token}/proof/upload":{"post":{"tags":["Pedidos"],"operationId":"uploadOrderProof","summary":"Sube el archivo del comprobante (paso 1)","description":"Sube el archivo y devuelve su clave. Todavía no queda asociado al pedido: eso lo\nhace `POST /orders/{token}/proof`. Máximo 10 MB y encabezado `Content-Length`\nobligatorio. Tipos: JPEG, PNG, WebP, GIF y PDF; el contenido se verifica contra\nel tipo declarado.\n","parameters":[{"$ref":"#/components/parameters/OrderToken"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Archivo guardado.","content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Clave para `proofUrl` en `POST /orders/{token}/proof`.","examples":["uploads/checkout-proof/clx0store/7f3c2a10-8f0b-4a3e-9a51-0d2b6c1e4f77.jpg"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/orders/{token}/proof":{"post":{"tags":["Pedidos"],"operationId":"attachOrderProof","summary":"Asocia el comprobante al pedido (paso 2)","description":"Se acepta una sola vez, solo en pedidos con método de pago manual y no cancelados.\n`proofUrl` tiene que ser una clave emitida por el paso 1 para esta tienda, nunca una\nURL. Sigue disponible con la tienda pausada o archivada.\n","parameters":[{"$ref":"#/components/parameters/OrderToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["proofUrl"],"properties":{"proofUrl":{"example":"uploads/checkout-proof/clx0store/7f3c2a10-8f0b-4a3e-9a51-0d2b6c1e4f77.jpg","type":"string","minLength":1,"maxLength":300}}}}}},"responses":{"200":{"description":"Comprobante guardado.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"webhooks":{"order.created":{"post":{"summary":"Se creó un pedido","description":"Un pedido nuevo de la tienda, de cualquier canal (`data.order.source`). Si nace pagado\n(una venta de caja cobrada), también llega `order.paid`.\n","operationId":"webhookOrderCreated","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/TiendySignature"},{"$ref":"#/components/parameters/TiendyEventId"},{"$ref":"#/components/parameters/TiendyEventType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderWebhookEvent"}}}},"responses":{"2XX":{"description":"Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido."}}}},"order.paid":{"post":{"summary":"Un pedido pasó a pagado","description":"El pedido entró en `paymentStatus = PAGADO` (pago con tarjeta confirmado por Stripe, pagos cargados en el panel o cobros de Envíos).","operationId":"webhookOrderPaid","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/TiendySignature"},{"$ref":"#/components/parameters/TiendyEventId"},{"$ref":"#/components/parameters/TiendyEventType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderWebhookEvent"}}}},"responses":{"2XX":{"description":"Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido."}}}},"order.status_changed":{"post":{"summary":"Cambió el estado de un pedido","description":"`data.previousStatus` es el estado anterior y `data.status` el nuevo.","operationId":"webhookOrderStatusChanged","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/TiendySignature"},{"$ref":"#/components/parameters/TiendyEventId"},{"$ref":"#/components/parameters/TiendyEventType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatusChangedWebhookEvent"}}}},"responses":{"2XX":{"description":"Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido."}}}},"order.proof_uploaded":{"post":{"summary":"El comprador subió el comprobante de pago","operationId":"webhookOrderProofUploaded","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/TiendySignature"},{"$ref":"#/components/parameters/TiendyEventId"},{"$ref":"#/components/parameters/TiendyEventType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderWebhookEvent"}}}},"responses":{"2XX":{"description":"Recibido. Cualquier otra respuesta, una redirección o 10 s sin respuesta es un intento fallido."}}}}},"components":{"securitySchemes":{"publishableKey":{"type":"http","scheme":"bearer","bearerFormat":"pk_","description":"`Authorization: Bearer pk_...`. Para navegadores, limitada a los orígenes autorizados."},"secretKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_","description":"`Authorization: Bearer sk_...`. Solo de servidor a servidor, nunca en un navegador."}},"parameters":{"TiendySignature":{"example":"t=1793718245,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","name":"Tiendy-Signature","in":"header","required":true,"description":"`t=<unix>,v1=<hex>`: HMAC-SHA256 con el secreto del endpoint sobre `<t>.<cuerpo crudo>`.","schema":{"type":"string"}},"TiendyEventId":{"example":"7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11","name":"Tiendy-Event-Id","in":"header","required":true,"description":"Igual a `id` del cuerpo. Sirve para descartar repeticiones.","schema":{"type":"string","format":"uuid"}},"TiendyEventType":{"example":"order.created","name":"Tiendy-Event-Type","in":"header","required":true,"schema":{"$ref":"#/components/schemas/WebhookEventType"}},"OrderToken":{"example":"3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13","name":"token","in":"path","required":true,"description":"`publicToken` del pedido. Un token de otra tienda responde 404.","schema":{"type":"string","format":"uuid"}}},"headers":{"RetryAfter":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Solicitud rechazada. Con `code`: `INVALID_QUERY` (un parámetro de una lectura está\nfuera de rango o mal formado), `INVALID_BODY` (el cuerpo no es JSON o no respeta los\ntipos y formatos del contrato), `IDEMPOTENCY_KEY_REQUIRED` (ausente o mal formada),\n`SHIPPING_METHOD_INACTIVE`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_UNAVAILABLE`\n(un método manual inactivo, un método estándar en una tienda con otro medio\nconfigurado, Stripe incluido, o `viaStripe`/`viaPagopar` con algo distinto de\n`TARJETA` sin método manual), `STRIPE_NOT_AVAILABLE` (la tienda no tiene el pago\ncon tarjeta disponible), `STRIPE_CURRENCY_NOT_SUPPORTED` (la tienda no vende en\nguaraníes), `STRIPE_AMOUNT_NOT_ALLOWED` (el total supera el máximo por venta),\n`STRIPE_REJECTED` (Stripe no aceptó iniciar el pago), `RETURN_URL_INVALID`\n(`returnUrl` ausente o que no es una URL `https` de un origen autorizado),\n`PAGOPAR_NOT_ACTIVE` (Pagopar está retirado: es lo que responde todo intento de\nusarlo), `PAGOPAR_REJECTED` (sin uso hoy), `FILE_INVALID` (sin archivo, tipo no\npermitido o contenido que no coincide). Muchos rechazos del checkout (datos del\ncomprador, ciudad, cupón, líneas) solo traen `message`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Clave ausente, inválida o revocada: `API_KEY_INVALID`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"`STOREFRONT_API_PLAN_REQUIRED` (la tienda no está en el plan `PRO`; no aplica a\n`GET /orders/{token}` ni a `GET /orders/by-payment-hash/{hash}`),\n`ORIGIN_NOT_ALLOWED`, `SECRET_KEY_IN_BROWSER`, `STORE_INACTIVE` (tienda pausada o\narchivada; solo catálogo, cotización y checkout), o en el checkout\n`ALTCHA_REQUIRED`, `ALTCHA_INVALID`, `ALTCHA_EXPIRED`, `ALTCHA_REPLAY`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No existe o es de otra tienda: la respuesta es la misma en ambos casos. Códigos:\n`ORDER_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ALTCHA_NOT_CONFIGURED`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"`INSUFFICIENT_STOCK` (con `details`), `IDEMPOTENCY_KEY_REUSED`,\n`IDEMPOTENCY_IN_PROGRESS` (el intento concurrente con esa clave no terminó a tiempo;\nreintentar), `ORDER_NOT_PAYABLE`, `ORDER_CHANGED`,\n`PROOF_NOT_ALLOWED`, `PROOF_ORDER_CANCELLED`, `PROOF_ALREADY_UPLOADED`. El tope de\ncanjes de un cupón responde 409 solo con `message`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"`SHIPPING_NOT_AVAILABLE_FOR_CITY`, `BUNDLE_COUPON_CONFLICT`, `PROOF_INVALID`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"`FILE_TOO_LARGE`: más de 10 MB, o `Content-Length` ausente o inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"`RATE_LIMITED`. Respetar `Retry-After`. Sin datos para servir, también en una lectura de catálogo degradada.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Error del servidor. En el checkout se puede reintentar con la misma `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"`SERVICE_UNAVAILABLE`: no se pudo verificar la clave o el plan de la tienda, o\nStripe no respondió al iniciar un pago. No dice nada de la clave ni del plan:\nreintentar después de `Retry-After`.\n","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"example":"Stock insuficiente","type":"string","description":"Texto corto en español."},"message":{"example":"No hay stock suficiente de Remera Rojo.","type":"string","description":"Texto en español, apto para mostrarle al comprador."},"code":{"example":"INSUFFICIENT_STOCK","type":"string","description":"Código estable. Es lo único con lo que el cliente debe ramificar."},"details":{"type":"array","description":"Con `INSUFFICIENT_STOCK`, un elemento por SKU sin stock suficiente.","items":{"$ref":"#/components/schemas/StockIssue"}}}},"StockIssue":{"type":"object","required":["skuId","skuKey","label","requested","available"],"properties":{"skuId":{"example":"clx0sku","type":"string"},"skuKey":{"example":"color:rojo","type":"string"},"label":{"example":"Remera Rojo","type":"string","description":"Producto y variante, para mostrar."},"requested":{"example":3,"type":"integer","description":"Total pedido de este SKU, sumando todas las líneas."},"available":{"example":1,"type":"integer","description":"Stock online del SKU, la suma de las ubicaciones que despachan pedidos online."}}},"Store":{"type":"object","required":["id","name","currency","apiOnly","checkout","shippingMethods","paymentOptions"],"properties":{"id":{"example":"clx0store","type":"string"},"name":{"example":"Tienda Demo","type":"string"},"description":{"example":"Ropa y accesorios.","type":["string","null"]},"logoUrl":{"example":"https://img.example.com/logo.png","type":["string","null"],"format":"uri","description":"Nulo si la tienda no tiene logo o eligió no mostrarlo."},"contactEmail":{"example":"hola@example.com","type":["string","null"],"format":"email"},"whatsapp":{"example":"+595981123456","type":["string","null"]},"currency":{"example":"PYG","type":"string","enum":["PYG","USD","ARS","BRL","CLP","UYU","COP"]},"apiOnly":{"example":false,"type":"boolean","description":"La tienda vende solo por esta API y no tiene storefront de Tiendy."},"checkout":{"$ref":"#/components/schemas/CheckoutSettings"},"shippingMethods":{"type":"array","description":"Solo métodos activos.","items":{"$ref":"#/components/schemas/ShippingMethod"}},"paymentOptions":{"type":"array","description":"Las opciones que la tienda ofrece hoy. La de `kind: stripe` aparece solo si el\npago con tarjeta está disponible para la tienda en ese momento.\n","example":[{"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"}]}}],"items":{"$ref":"#/components/schemas/PaymentOption"}},"metaPixel":{"oneOf":[{"$ref":"#/components/schemas/MetaPixelSettings"},{"type":"null"}]}}},"CheckoutSettings":{"type":"object","required":["fields","askDirection2","askDeliveryLocation","offersNoShipping","requiresShippingMethod"],"properties":{"fields":{"$ref":"#/components/schemas/CheckoutFields"},"askDirection2":{"example":true,"type":"boolean","description":"Si es `false`, `direction2` se guarda vacía aunque se envíe."},"askDeliveryLocation":{"example":false,"type":"boolean","description":"La tienda ofrece pedir la ubicación exacta; siempre es opcional para el comprador."},"offersNoShipping":{"example":true,"type":"boolean","description":"La tienda ofrece «Retiro en local / Sin envío»."},"requiresShippingMethod":{"example":false,"type":"boolean","description":"`true` si la tienda apagó «Retiro en local / Sin envío» y tiene algún método\nactivo. Entonces un pedido sin método recibe 400 `SHIPPING_METHOD_REQUIRED`.\n"}}},"CheckoutFields":{"type":"object","description":"Qué pide la tienda a un comprador. Un campo `hidden` se descarta aunque se envíe.\nEl teléfono no está porque siempre es obligatorio. El pago con tarjeta (Stripe) no\ncambia ninguno.\n","required":["email","name","lastName","address","city","document"],"properties":{"email":{"example":"optional","$ref":"#/components/schemas/CheckoutFieldMode"},"name":{"example":"required","$ref":"#/components/schemas/CheckoutFieldMode"},"lastName":{"example":"required","$ref":"#/components/schemas/CheckoutFieldMode"},"address":{"example":"required","description":"`direction1` y `direction2`.","$ref":"#/components/schemas/CheckoutFieldMode"},"city":{"example":"required","description":"`cityId` y `city`.","$ref":"#/components/schemas/CheckoutFieldMode"},"document":{"example":"optional","description":"`ruc`, `taxIdCountry`, `taxIdType` y `rucName`.","$ref":"#/components/schemas/CheckoutFieldMode"}}},"CheckoutFieldMode":{"type":"string","enum":["hidden","optional","required"]},"ShippingMethod":{"type":"object","required":["id","name","type","costType","price","cityIds","recommended"],"properties":{"id":{"example":"1f2e3d4c","type":"string"},"name":{"example":"Envío a domicilio","type":"string"},"description":{"example":"Entrega en 24 a 48 horas.","type":["string","null"]},"type":{"example":"DOMICILIO","type":"string","enum":["DOMICILIO","RETIRO","ENCOMIENDA","UMBRAL"],"description":"`RETIRO` no depende de la ciudad."},"costType":{"example":"FIJO","type":"string","enum":["FIJO","GRATIS","UMBRAL"]},"price":{"example":15000,"type":"integer","description":"Precio de lista. Lo cobrado sale de `POST /cart/quote`."},"freeThreshold":{"example":null,"type":["integer","null"],"description":"Con `UMBRAL`, gratis si el subtotal (neto de ofertas, antes del cupón) lo alcanza."},"deliveryMin":{"example":24,"type":["integer","null"]},"deliveryMax":{"example":48,"type":["integer","null"]},"deliveryUnit":{"example":"HORAS","type":["string","null"],"enum":["HORAS","DIAS_HABILES","DIAS",null]},"recommended":{"example":true,"type":"boolean"},"cityIds":{"example":["1101"],"type":"array","description":"Ciudades que cubre. Vacío significa todas. Una ciudad desconocida o sin resolver\nno restringe ningún método.\n","items":{"type":"string"}}}},"PaymentOption":{"type":"object","required":["id","kind","label","requireProof","fields","request"],"properties":{"id":{"example":"7a8b9c0d","type":"string"},"kind":{"example":"manual","type":"string","enum":["stripe","manual","standard","pagopar"],"description":"`stripe`: pago con tarjeta; después del checkout se llama a\n`POST /orders/{token}/pay`. `pagopar` está retirado y ninguna tienda lo lista.\n"},"label":{"example":"Transferencia bancaria","type":"string"},"requireProof":{"example":true,"type":"boolean","description":"Se le pide un comprobante al comprador. Nunca bloquea el pedido; se envía después."},"fields":{"description":"`Store.checkout.fields` con esta opción aplicada. Con `stripe`, `manual` y `standard` son los de la tienda, sin cambios.","$ref":"#/components/schemas/CheckoutFields"},"manual":{"$ref":"#/components/schemas/ManualPaymentDetails"},"request":{"type":"object","description":"Los campos exactos que `POST /checkout` tiene que enviar para esta opción.","required":["paymentMethod","viaPagopar"],"properties":{"paymentMethod":{"example":"TRANSFERENCIA","$ref":"#/components/schemas/PaymentMethod"},"customPaymentMethodId":{"example":"7a8b9c0d","type":"string"},"viaPagopar":{"example":false,"type":"boolean"},"viaStripe":{"example":true,"type":"boolean","description":"Solo en la opción `stripe`, siempre `true`."}}},"stripe":{"type":"object","description":"Solo en la opción `stripe`.","required":["maxTotal"],"properties":{"maxTotal":{"example":5000000,"type":"integer","description":"El total máximo de un pedido que se puede pagar con tarjeta: Gs. 5.000.000, o\nel tope menor que fijó la tienda. Un checkout por encima responde 400\n`STRIPE_AMOUNT_NOT_ALLOWED`.\n"}}}}},"PayRequest":{"type":"object","required":["returnUrl"],"properties":{"returnUrl":{"example":"https://landing.example.com/pago","type":"string","format":"uri","maxLength":2000,"description":"La página de la landing a la que Stripe devuelve al comprador. URL completa\n`https`, sin usuario ni contraseña, cuyo origen (esquema, host y puerto) es uno de\nlos orígenes autorizados de la tienda, también con una clave `sk_`. `http` solo\npara `localhost`, `127.0.0.1` y `[::1]`, si ese origen está registrado. Si no,\n400 `RETURN_URL_INVALID`.\n"}}},"ManualPaymentDetails":{"type":"object","description":"Datos para que el comprador pague. Solo en opciones `manual`.","required":["name"],"properties":{"name":{"example":"Transferencia bancaria","type":"string"},"type":{"example":"TRANSFER","type":["string","null"],"enum":["TRANSFER","WALLET","CASH","OTHER",null]},"instructions":{"example":"Transferí el total y subí el comprobante.","type":["string","null"]},"logoUrl":{"example":null,"type":["string","null"],"format":"uri"},"accounts":{"type":"array","items":{"type":"object","properties":{"label":{"example":"Cuenta principal","type":"string"},"bank":{"example":"Banco Ejemplo","type":"string"},"holder":{"example":"Tienda Demo","type":"string"},"accountNumber":{"example":"1234567890","type":"string"},"ruc":{"example":"1234567-9","type":"string"},"alias":{"example":"tienda.demo","type":"string"}}}}}},"PaymentMethod":{"type":"string","enum":["TARJETA","EFECTIVO","TRANSFERENCIA"]},"MetaPixelSettings":{"type":"object","required":["pixelId","requireCookieConsent","trackPageView","trackViewContent","trackAddToCart","trackInitiateCheckout","trackPurchase","trackCompleteRegistration","trackLead","trackSearch"],"properties":{"pixelId":{"example":"123456789012345","type":"string"},"requireCookieConsent":{"example":false,"type":"boolean","description":"Si es `true`, el píxel espera el consentimiento y el servidor no envía eventos sin\n`metaContext.consent` igual a `granted`.\n"},"trackPageView":{"type":"boolean"},"trackViewContent":{"type":"boolean"},"trackAddToCart":{"type":"boolean"},"trackInitiateCheckout":{"type":"boolean"},"trackPurchase":{"type":"boolean"},"trackCompleteRegistration":{"type":"boolean"},"trackLead":{"type":"boolean"},"trackSearch":{"type":"boolean"}}},"ProductPage":{"type":"object","required":["items","page","limit","total","hasMore"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"page":{"example":1,"type":"integer"},"limit":{"example":24,"type":"integer"},"total":{"example":1,"type":"integer"},"hasMore":{"example":false,"type":"boolean"}}},"ProductSummary":{"type":"object","required":["id","name","status","purchasable","createdAt","categoryId","price","images","skus","variants"],"properties":{"id":{"example":"clx0prod","type":"string"},"name":{"example":"Remera","type":"string"},"slug":{"example":"remera","type":["string","null"],"description":"Puede ser nulo y puede cambiar. Un valor anterior no redirige al nuevo: responde\n404. Para guardar una referencia estable, usar `id`.\n"},"shortDescription":{"example":"Remera de algodón.","type":["string","null"]},"brand":{"example":"Marca Demo","type":["string","null"]},"status":{"example":"EN_VENTA","type":"string","enum":["EN_VENTA","AGOTADO"]},"purchasable":{"example":true,"type":"boolean","description":"`true` si está `EN_VENTA` y le queda alguna combinación disponible. Un producto\n`EN_VENTA` con todos sus SKU agotados es `false`, como en la tienda.\n"},"isFeatured":{"example":false,"type":"boolean"},"createdAt":{"example":"2026-10-01T12:00:00.000Z","type":"string","format":"date-time"},"categoryId":{"example":"clx0cat","type":"string"},"price":{"example":75000,"type":["integer","null"],"description":"Precio de lista del producto simple."},"salePrice":{"example":null,"type":["integer","null"],"description":"Precio promocional. Nulo significa que no hay promoción."},"images":{"type":"array","description":"En la lista, solo la primera. En el detalle, todas y en orden.","items":{"$ref":"#/components/schemas/ProductImage"}},"variants":{"type":"array","description":"Ejes de variante. Vacío en un producto simple.","items":{"$ref":"#/components/schemas/VariantAxis"}},"skus":{"type":"array","description":"Solo combinaciones comprables.","items":{"$ref":"#/components/schemas/Sku"}}}},"ProductDetail":{"allOf":[{"$ref":"#/components/schemas/ProductSummary"},{"type":"object","required":["description","offers"],"properties":{"description":{"example":"<p>Remera de algodón peinado.</p>","type":"string","description":"HTML sanitizado."},"metaTitle":{"example":null,"type":["string","null"]},"metaDescription":{"example":null,"type":["string","null"]},"offers":{"$ref":"#/components/schemas/ProductOffers"}}}]},"ProductImage":{"type":"object","required":["url","alt"],"properties":{"url":{"example":"https://img.example.com/remera-rojo.jpg","type":"string","format":"uri","description":"URL absoluta de entrega."},"alt":{"example":null,"type":["string","null"],"description":"Texto alternativo de la imagen. Hoy siempre `null`, porque el panel todavía no permite cargarlo."}}},"VariantAxis":{"type":"object","required":["id","name","options"],"properties":{"id":{"example":"clx0var","type":"string"},"name":{"example":"Color","type":"string"},"options":{"type":"array","items":{"type":"object","required":["id","name","status"],"properties":{"id":{"example":"clx0opt","type":"string"},"name":{"example":"Rojo","type":"string"},"status":{"example":"DISPONIBLE","type":"string","enum":["DISPONIBLE","AGOTADO"]},"imageUrl":{"example":null,"type":["string","null"],"format":"uri"}}}}}},"Sku":{"type":"object","required":["id","key","price","unitPrice","stock","status","options"],"properties":{"id":{"example":"clx0sku","type":"string"},"key":{"example":"color:rojo","type":"string"},"price":{"example":75000,"type":"integer"},"salePrice":{"example":null,"type":["integer","null"],"description":"Nulo significa que no hay promoción."},"unitPrice":{"example":75000,"type":"integer","description":"Lo que cuesta una unidad antes de ofertas."},"stock":{"example":12,"type":["integer","null"],"description":"Stock online: la suma de las ubicaciones de la tienda que despachan pedidos online,\nlo mismo que verifica el checkout. `null` significa que la tienda no controla el\nstock de este SKU: no hay límite. `0` es agotado.\n"},"status":{"example":"DISPONIBLE","type":"string","enum":["DISPONIBLE","AGOTADO"],"description":"`AGOTADO` si la tienda lo marcó así o si `stock` (el stock online) es `0`."},"options":{"type":"array","items":{"type":"object","required":["variantName","optionId","optionName"],"properties":{"variantName":{"example":"Color","type":"string"},"optionId":{"example":"clx0opt","type":"string"},"optionName":{"example":"Rojo","type":"string"}}}}}},"ProductOffers":{"type":"object","required":["quantityOffer","combo"],"description":"Solo para mostrar. El descuento real sale de `POST /cart/quote` y `POST /checkout`.","properties":{"quantityOffer":{"oneOf":[{"$ref":"#/components/schemas/QuantityOffer"},{"type":"null"}]},"combo":{"example":null,"oneOf":[{"$ref":"#/components/schemas/ComboOffer"},{"type":"null"}]}}},"QuantityOffer":{"type":"object","required":["id","name","combinesWithCoupons","tiers"],"properties":{"id":{"example":"clx0offer","type":"string"},"name":{"example":"Llevá 2 y ahorrá","type":"string"},"combinesWithCoupons":{"example":true,"type":"boolean"},"tiers":{"type":"array","items":{"type":"object","required":["minQuantity","discountType","value"],"properties":{"minQuantity":{"example":2,"type":"integer"},"discountType":{"example":"PERCENT","type":"string","enum":["PERCENT","FIXED_OFF","FIXED_PRICE"]},"value":{"example":20,"type":"integer","description":"`PERCENT`: 1 a 100. Los otros dos: monto de todo el conjunto."},"label":{"example":"2 unidades","type":["string","null"]},"badge":{"example":null,"type":["string","null"]},"preselected":{"example":false,"type":"boolean"}}}}}},"ComboOffer":{"type":"object","required":["id","name","combinesWithCoupons","items","addable","total","listTotal","saving"],"properties":{"id":{"example":"clx0combo","type":"string"},"name":{"example":"Combo Remera","type":"string"},"combinesWithCoupons":{"example":false,"type":"boolean"},"addable":{"example":true,"type":"boolean","description":"Cada ítem resuelve a una sola línea, así que el combo se puede agregar directo."},"total":{"example":120000,"type":["integer","null"],"description":"Nulo mientras algún ítem necesite elegir variante."},"listTotal":{"example":150000,"type":["integer","null"]},"saving":{"example":30000,"type":["integer","null"]},"items":{"type":"array","items":{"type":"object","required":["productId","name","quantity","needsVariant","soldOut"],"properties":{"productId":{"example":"clx0prod","type":"string"},"name":{"example":"Remera","type":"string"},"imageUrl":{"example":"https://img.example.com/remera-rojo.jpg","type":["string","null"],"format":"uri"},"quantity":{"example":2,"type":"integer"},"unitPrice":{"example":75000,"type":["integer","null"]},"needsVariant":{"example":false,"type":"boolean"},"soldOut":{"example":false,"type":"boolean"},"line":{"description":"La línea lista para el carrito, si el ítem resuelve a una sola.","oneOf":[{"$ref":"#/components/schemas/CartLine"},{"type":"null"}]}}}}}},"Category":{"type":"object","required":["id","name","children"],"properties":{"id":{"example":"clx0cat","type":"string"},"name":{"example":"Remeras","type":"string"},"slug":{"example":"remeras","type":["string","null"]},"description":{"example":null,"type":["string","null"]},"imageUrl":{"example":null,"type":["string","null"],"format":"uri"},"children":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"example":"clx0sub","type":"string"},"name":{"example":"Manga corta","type":"string"},"slug":{"example":"manga-corta","type":["string","null"]},"description":{"example":null,"type":["string","null"]},"imageUrl":{"example":null,"type":["string","null"],"format":"uri"}}}}}},"GeoCatalog":{"type":"object","required":["departments","cities"],"properties":{"departments":{"type":"array","items":{"type":"object","required":["code","name"],"properties":{"code":{"example":"11","type":"string"},"name":{"example":"CENTRAL","type":"string"}}}},"cities":{"type":"array","items":{"type":"object","required":["code","departmentCode","name"],"properties":{"code":{"example":"1101","type":"string"},"departmentCode":{"example":"11","type":"string"},"name":{"example":"AREGUÁ","type":"string"}}}}}},"CartLine":{"type":"object","required":["productId","quantity"],"properties":{"productId":{"example":"clx0prod","type":"string"},"skuId":{"example":"clx0sku","type":"string","description":"Obligatorio en productos con variantes. En un producto simple se omite y el\nservidor usa su SKU por defecto.\n"},"quantity":{"example":2,"type":"integer","minimum":1,"maximum":100000}}},"QuoteRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/CartLine"}},"shippingMethodId":{"example":"1f2e3d4c","type":"string","description":"Id de un método, o `NINGUNO` para «Retiro en local / Sin envío»."},"cityId":{"example":"1101","type":"string","description":"Código de `GET /geo/cities`. Decide la cobertura de envío."},"couponCode":{"example":"VERANO","type":"string","minLength":1,"maxLength":64}}},"Quote":{"type":"object","description":"`listSubtotal - bundleSavings = subtotal` y `subtotal - couponDiscount + shippingPrice = total`.","required":["currency","lines","listSubtotal","bundleSavings","subtotal","couponDiscount","shippingPrice","total","availableShippingMethodIds","stockIssues"],"properties":{"currency":{"example":"PYG","type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}},"listSubtotal":{"example":150000,"type":"integer"},"bundleSavings":{"example":30000,"type":"integer"},"subtotal":{"example":120000,"type":"integer","description":"Neto de ofertas y antes del cupón. Es la base del envío por umbral y del cupón."},"couponDiscount":{"example":20000,"type":"integer"},"shippingPrice":{"example":15000,"type":"integer"},"total":{"example":115000,"type":"integer"},"availableShippingMethodIds":{"example":["1f2e3d4c"],"type":"array","description":"Métodos activos que cubren `cityId`.","items":{"type":"string"}},"stockIssues":{"example":[],"type":"array","description":"Faltantes al momento de cotizar, contra el stock online. No es una reserva; quien\ndecide es el checkout.\n","items":{"$ref":"#/components/schemas/StockIssue"}}}},"QuoteLine":{"type":"object","required":["productId","productName","quantity","unitPrice","listTotal","bundleDiscount","total"],"properties":{"productId":{"example":"clx0prod","type":"string"},"skuId":{"example":"clx0sku","type":["string","null"]},"productName":{"example":"Remera","type":"string"},"variantLabel":{"example":"Color: Rojo","type":["string","null"]},"quantity":{"example":2,"type":"integer"},"unitPrice":{"example":75000,"type":"integer"},"listTotal":{"example":150000,"type":"integer"},"bundleDiscount":{"example":30000,"type":"integer"},"bundleName":{"example":"Llevá 2 y ahorrá","type":["string","null"]},"total":{"example":120000,"type":"integer","description":"Lo cobrado por la línea, `listTotal - bundleDiscount`."}}},"CheckoutRequest":{"type":"object","description":"Se ignora cualquier total, y también `storeId`, `isExistingCustomer` y campos\ndesconocidos. Qué campos del comprador son obligatorios lo define\n`Store.checkout.fields`, salvo `tel`, siempre obligatorio.\n","required":["items","tel","paymentMethod","viaPagopar"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/CartLine"}},"tel":{"example":"0981123456","type":"string","description":"Teléfono en cualquier forma legible (`0981...`, `981...`, `595981...`,\n`+595...`). Sin código de país se interpreta como Paraguay y se guarda en E.164.\n"},"email":{"example":"ana@example.com","type":"string","format":"email","description":"Opcional salvo que la tienda lo exija. Identifica al comprador junto\ncon `tel`. Vacío equivale a ausente. Mal formado responde 400 `INVALID_BODY`, también\nsi la tienda oculta el campo.\n"},"name":{"example":"Ana","type":"string"},"lastName":{"example":"Gómez","type":"string"},"ruc":{"example":"1234567-9","type":"string","description":"Número de documento."},"taxIdCountry":{"example":"PY","type":"string","description":"País del documento. Hoy: `PY`. Va junto con `taxIdType`.","enum":["PY"]},"taxIdType":{"example":"RUC","type":"string","description":"Tipo de documento. Con el par presente, el servidor valida `ruc`, incluido el dígito verificador.","enum":["RUC","CI","PASSPORT","FOREIGN_ID","RESIDENCE_CARD","DIPLOMATIC_CARD","OTHER","UNNAMED"]},"rucName":{"example":"Ana Gómez","type":"string","description":"Razón social."},"cityId":{"example":"1101","type":"string","description":"Código de `GET /geo/cities`. Desconocido o retirado responde 400. Gana sobre `city`."},"city":{"example":"Areguá","type":"string","description":"Texto libre, solo cuando no hay `cityId`. Si no coincide exactamente con una\nciudad, el pedido sale igual, sin control de cobertura.\n"},"direction1":{"example":"Av. Mariscal López 1234","type":"string"},"direction2":{"example":"Casa con portón negro","type":"string","description":"Referencia o apartado."},"shippingMethodId":{"example":"1f2e3d4c","type":"string","description":"Id de un método activo de la tienda, o `NINGUNO`/ausente para «Retiro en local / Sin\nenvío». Con un método de tipo `RETIRO` no se puede elegir la sucursal: el pedido se\ncrea sin ella.\n"},"paymentMethod":{"example":"TRANSFERENCIA","$ref":"#/components/schemas/PaymentMethod"},"customPaymentMethodId":{"example":"7a8b9c0d","type":"string","description":"Solo en opciones `manual`. Tiene que ser un método activo de la tienda."},"viaPagopar":{"example":false,"type":"boolean","description":"Obligatorio, y hoy siempre `false`: Pagopar está retirado y `true` responde 400\n`PAGOPAR_NOT_ACTIVE`.\n"},"viaStripe":{"example":false,"type":"boolean","description":"`true` si este pedido se paga con tarjeta (Stripe): la opción `stripe` de\n`store.paymentOptions`. Opcional; ausente equivale a `false`. Exige `TARJETA`,\nsin `customPaymentMethodId` y con `viaPagopar: false` (si no, 400\n`PAYMENT_METHOD_UNAVAILABLE`). Si la tienda no lo tiene disponible, 400\n`STRIPE_NOT_AVAILABLE` o `STRIPE_CURRENCY_NOT_SUPPORTED`; si el total supera\n`stripe.maxTotal`, 400 `STRIPE_AMOUNT_NOT_ALLOWED`. El pedido se paga después\ncon `POST /orders/{token}/pay`.\n"},"couponCode":{"example":"VERANO","type":"string","minLength":1,"maxLength":64,"description":"Solo el código; el descuento lo calcula el servidor."},"deliveryLocation":{"$ref":"#/components/schemas/DeliveryLocation"},"metaContext":{"$ref":"#/components/schemas/MetaContext"},"altchaChallenge":{"description":"El desafío de `GET /altcha/challenge`, tal como se recibió.","$ref":"#/components/schemas/AltchaChallenge"},"altchaSolution":{"type":"object","description":"La solución devuelta por `altcha-lib`.","additionalProperties":true}}},"DeliveryLocation":{"type":"object","description":"Punto de entrega opcional. Un valor inválido se descarta, nunca frena la venta.","required":["lat","lng","source"],"properties":{"lat":{"example":-25.3083,"type":"number","minimum":-90,"maximum":90},"lng":{"example":-57.3842,"type":"number","minimum":-180,"maximum":180},"source":{"example":"GPS","type":"string","enum":["GPS","LINK","MANUAL"]},"accuracyM":{"example":12,"type":["number","null"],"minimum":0}}},"MetaContext":{"type":"object","description":"Contexto opcional para la API de Conversiones de Meta. Nunca decide si se crea el pedido.","properties":{"eventSourceUrl":{"example":"https://landing.example.com/checkout","type":"string","maxLength":2048},"fbclid":{"example":"IwAR0ejemplo","type":"string","maxLength":500},"fbp":{"example":"fb.1.1793718245000.1234567890","type":"string","description":"Valor de la cookie `_fbp` de la landing. Si es inválido, se descarta."},"fbc":{"example":"fb.1.1793718245000.IwAR0ejemplo","type":"string","description":"Valor de la cookie `_fbc` de la landing. Si es inválido, se descarta."},"consent":{"example":"granted","type":"string","enum":["granted","denied","unknown"]},"initiateCheckoutEventId":{"example":"5d3f9a1c-2b47-4e80-8c6d-1a2b3c4d5e6f","type":"string","format":"uuid","description":"UUID v4 con el que el navegador disparó InitiateCheckout. Si es inválido, el servidor no envía ese evento."}}},"AltchaChallenge":{"type":"object","description":"Objeto opaco. Se reenvía sin modificar.","additionalProperties":true},"CheckoutResponse":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","required":["metaEvents"],"properties":{"metaEvents":{"type":"array","description":"Eventos que la landing dispara ahora en su píxel, con estos ids.","items":{"$ref":"#/components/schemas/MetaEvent"}}}}]},"MetaEvent":{"type":"object","required":["name","eventId","params"],"properties":{"name":{"example":"Lead","type":"string","enum":["Lead","CompleteRegistration"]},"eventId":{"example":"lead-1234","type":"string","examples":["lead-1042"]},"params":{"type":"object","required":["value"],"properties":{"value":{"example":115000,"type":"integer"}}}}},"WebhookEventType":{"type":"string","enum":["order.created","order.paid","order.status_changed","order.proof_uploaded"]},"WebhookOrder":{"type":"object","description":"El mismo `OrderView` que devuelve la API, sin `metaPurchase` (es solo para el\nnavegador) y con el canal del pedido. Sin datos del comprador ni `publicToken`;\n`trackingUrl` siempre es `null`.\n","required":["id","status","paymentStatus","createdAt","currency","total","lines","payment","proof","source"],"properties":{"id":{"$ref":"#/components/schemas/OrderView/properties/id"},"status":{"$ref":"#/components/schemas/OrderView/properties/status"},"paymentStatus":{"$ref":"#/components/schemas/OrderView/properties/paymentStatus"},"createdAt":{"$ref":"#/components/schemas/OrderView/properties/createdAt"},"currency":{"$ref":"#/components/schemas/OrderView/properties/currency"},"listSubtotal":{"$ref":"#/components/schemas/OrderView/properties/listSubtotal"},"bundleSavings":{"$ref":"#/components/schemas/OrderView/properties/bundleSavings"},"subtotal":{"$ref":"#/components/schemas/OrderView/properties/subtotal"},"couponCode":{"$ref":"#/components/schemas/OrderView/properties/couponCode"},"couponDiscount":{"$ref":"#/components/schemas/OrderView/properties/couponDiscount"},"shippingName":{"$ref":"#/components/schemas/OrderView/properties/shippingName"},"shippingPrice":{"$ref":"#/components/schemas/OrderView/properties/shippingPrice"},"total":{"$ref":"#/components/schemas/OrderView/properties/total"},"lines":{"$ref":"#/components/schemas/OrderView/properties/lines"},"payment":{"$ref":"#/components/schemas/OrderView/properties/payment"},"proof":{"$ref":"#/components/schemas/OrderView/properties/proof"},"trackingUrl":{"example":null,"$ref":"#/components/schemas/OrderView/properties/trackingUrl"},"source":{"example":"STOREFRONT_API","type":["string","null"],"enum":["STOREFRONT","STOREFRONT_API","MARKETPLACE","ADMIN","POS",null],"description":"Canal del pedido. `null` en pedidos anteriores a la columna."}}},"OrderWebhookEvent":{"type":"object","required":["id","type","createdAt","storeId","data"],"properties":{"id":{"example":"7c0e0b8a-2f0e-4a51-9a63-3f1f7d3a9c11","type":"string","format":"uuid","description":"Id del evento. Es el mismo en todos los endpoints de la tienda y en cada reintento."},"type":{"$ref":"#/components/schemas/WebhookEventType"},"createdAt":{"example":"2026-11-03T15:04:05.000Z","type":"string","format":"date-time","description":"Cuándo ocurrió el evento. Los eventos pueden llegar desordenados."},"storeId":{"example":"clx0store","type":"string"},"data":{"type":"object","required":["order"],"properties":{"order":{"$ref":"#/components/schemas/WebhookOrder"}}}}},"OrderStatusChangedWebhookEvent":{"allOf":[{"$ref":"#/components/schemas/OrderWebhookEvent"},{"type":"object","properties":{"data":{"type":"object","required":["order","previousStatus","status"],"properties":{"previousStatus":{"example":"PENDIENTE","type":"string","enum":["PENDIENTE","CONFIRMADO","PREPARANDO","EN_CAMINO","ENTREGADO","CANCELADO"]},"status":{"example":"PREPARANDO","type":"string","enum":["PENDIENTE","CONFIRMADO","PREPARANDO","EN_CAMINO","ENTREGADO","CANCELADO"]}}}}}]},"OrderView":{"type":"object","description":"Nunca incluye datos personales del comprador (nombre, email, teléfono, documento,\ndirección, ubicación), costos, ni datos de Pagopar o de la tienda. De un pago con\ntarjeta solo dice `payment.gateway`: nunca lo que se descuenta de la venta, el neto\ndel comercio ni los identificadores de Stripe.\n","required":["id","status","paymentStatus","createdAt","currency","listSubtotal","bundleSavings","subtotal","couponDiscount","shippingPrice","total","lines","payment","proof","metaPurchase"],"properties":{"id":{"example":1234,"type":"integer","description":"Número de pedido, para mostrar. Es correlativo y no sirve para operar."},"status":{"example":"PENDIENTE","type":"string","enum":["PENDIENTE","CONFIRMADO","PREPARANDO","EN_CAMINO","ENTREGADO","CANCELADO"]},"paymentStatus":{"example":"PENDIENTE","type":"string","enum":["PENDIENTE","PARCIAL","PAGADO","CANCELADO"]},"createdAt":{"example":"2026-11-03T15:04:05.000Z","type":"string","format":"date-time"},"currency":{"example":"PYG","type":"string"},"listSubtotal":{"example":150000,"type":"integer"},"bundleSavings":{"example":30000,"type":"integer"},"subtotal":{"example":120000,"type":"integer"},"couponCode":{"example":"VERANO","type":["string","null"]},"couponDiscount":{"example":20000,"type":"integer"},"shippingName":{"example":"Envío a domicilio","type":["string","null"]},"shippingPrice":{"example":15000,"type":["integer","null"],"description":"Nulo si el pedido no tiene método de envío."},"total":{"example":115000,"type":"integer","description":"Es el monto que vale. Hay que mostrar este, no el cotizado."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"payment":{"type":"object","required":["method"],"properties":{"method":{"example":"TRANSFERENCIA","oneOf":[{"$ref":"#/components/schemas/PaymentMethod"},{"type":"null"}]},"customPaymentMethodId":{"example":"7a8b9c0d","type":["string","null"]},"customPaymentMethodName":{"example":"Transferencia bancaria","type":["string","null"]},"gateway":{"example":null,"type":["string","null"],"enum":["stripe",null],"description":"`stripe` en un pedido creado con la opción `stripe`: se paga con\n`POST /orders/{token}/pay`. `null` en todos los demás.\n"}}},"proof":{"type":"object","required":["requested","uploaded"],"properties":{"requested":{"example":true,"type":"boolean","description":"Mostrar la invitación a subir el comprobante."},"uploaded":{"example":false,"type":"boolean"}}},"metaPurchase":{"$ref":"#/components/schemas/MetaPurchase"},"trackingUrl":{"example":null,"type":["string","null"],"format":"uri","description":"Página de seguimiento en Tiendy, la misma que reciben los emails del comprador.\nSiempre `null` en `GET /orders/by-payment-hash/{hash}`: la URL incluye el `publicToken`.\n"}}},"Order":{"allOf":[{"$ref":"#/components/schemas/OrderView"},{"type":"object","required":["publicToken"],"properties":{"publicToken":{"example":"3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13","type":"string","format":"uuid","description":"Prueba de que se tiene el pedido. Tratarlo como un secreto del comprador."},"trackingUrl":{"example":"https://www.tiendy.com.py/tienda-demo/order/3f2b8c1e-5d47-4a9b-8e21-6c0f9d7a4b13"}}}]},"OrderLine":{"type":"object","required":["productId","productName","quantity","bundleDiscount","total"],"properties":{"productId":{"example":"clx0prod","type":["string","null"]},"skuId":{"example":"clx0sku","type":["string","null"]},"productName":{"example":"Remera","type":["string","null"]},"variantLabel":{"example":"Color: Rojo","type":["string","null"]},"quantity":{"example":2,"type":"integer"},"bundleName":{"example":"Llevá 2 y ahorrá","type":["string","null"]},"bundleDiscount":{"example":30000,"type":"integer"},"total":{"example":120000,"type":"integer","description":"Lo cobrado, neto de la oferta."}}},"MetaPurchase":{"type":"object","description":"El servidor envía Purchase por la API de Conversiones. La landing reutiliza `eventId`\nen su píxel, solo cuando `due` es `true`, para que Meta no cuente la venta dos veces.\n","required":["eventId","due"],"properties":{"eventId":{"example":"purchase-1234","type":"string","examples":["purchase-1042"]},"due":{"example":true,"type":"boolean","description":"Método manual: desde la creación. Tarjeta (Stripe): desde la confirmación del pago. Deja de\nser `true` 24 horas después.\n"},"params":{"example":{"value":115000,"currency":"PYG","order_id":"1234"},"type":"object","description":"Parámetros para pasar al píxel sin modificar. `currency` incluida.","additionalProperties":true}}}}}}