# 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 para un modelo que va a escribir una integración con la API de storefront de Tiendy. La documentación completa está en un solo archivo: https://www.tiendy.com.py/docs/llms-full.txt ## 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`. ## Flujo de una venta 1. Cargar la tienda y el catálogo: `GET /store`, `GET /categories`, `GET /products`, `GET /products/{id}`, `GET /products/by-slug/{slug}`, `GET /geo/cities` 2. Cotizar: `POST /cart/quote` 3. Crear el pedido: `POST /checkout`, `POST /orders/{token}/pay` 4. Pagar con tarjeta (Stripe): `GET /store`, `POST /checkout`, `POST /orders/{token}/pay`, `GET /orders/{token}` 5. Página de retorno de Stripe: `GET /orders/{token}`, `POST /orders/{token}/pay` 6. Comprobante de pago manual: `POST /orders/{token}/proof/upload`, `POST /orders/{token}/proof` 7. Pagopar (no disponible): `POST /checkout`, `POST /orders/{token}/pay`, `GET /orders/by-payment-hash/{hash}`, `GET /orders/{token}` ## Documentos - [Documentación completa en un archivo](https://www.tiendy.com.py/docs/llms-full.txt): toda la guía, la referencia de cada endpoint con sus ejemplos y los eventos de webhook. - [Contrato OpenAPI](https://www.tiendy.com.py/docs/openapi.json): el contrato en JSON. Si la guía y el contrato difieren, vale el contrato. ## Guías - [Introducción](https://www.tiendy.com.py/docs/guias/introduccion): Qué permite hacer la API de storefront de Tiendy y qué hace falta antes de empezar: plan, claves, URL base y montos. - [Obtener las claves](https://www.tiendy.com.py/docs/guias/obtener-las-claves): Dónde se crean las claves de la API, los orígenes autorizados y los webhooks en el panel de Tiendy. - [Autenticación](https://www.tiendy.com.py/docs/guias/autenticacion): Claves publicables y secretas, y desde dónde se puede usar cada una. - [Vender desde la landing](https://www.tiendy.com.py/docs/guias/vender-desde-la-landing): El recorrido completo de una venta: del catálogo al pago. Tu landing guarda las líneas del carrito y el servidor calcula todo lo demás. - [Stock: se puede sobrevender](https://www.tiendy.com.py/docs/guias/stock): El checkout verifica el stock, pero no lo reserva. - [Verificación ALTCHA](https://www.tiendy.com.py/docs/guias/altcha): Cuándo una tienda pide el desafío ALTCHA y cómo resolverlo. - [Meta Pixel y métricas](https://www.tiendy.com.py/docs/guias/meta-pixel-y-metricas): Cómo evitar que Meta cuente una venta dos veces y dónde se miden los pedidos y las visitas. - [Tiendas API-only](https://www.tiendy.com.py/docs/guias/tiendas-api-only): Qué sigue funcionando y qué deja de estar disponible cuando una tienda vende solo por la API. - [Datos que nunca devuelve](https://www.tiendy.com.py/docs/guias/datos-que-nunca-devuelve): Lo que las respuestas públicas de la API nunca incluyen. - [Errores](https://www.tiendy.com.py/docs/guias/errores): Los códigos estables por los que conviene ramificar. - [Límites de frecuencia](https://www.tiendy.com.py/docs/guias/limites-de-frecuencia): Los límites provisorios por clave, por tienda y por operación. - [Webhooks](https://www.tiendy.com.py/docs/guias/webhooks): Firma, reintentos y el contrato del receptor. - [No disponible todavía](https://www.tiendy.com.py/docs/guias/no-disponible-todavia): Lo que la API todavía no ofrece y lo que falta definir. ## Referencia de endpoints - [GET /store](https://www.tiendy.com.py/docs/referencia/get-store): Configuración pública de la tienda - [GET /products](https://www.tiendy.com.py/docs/referencia/list-products): Lista paginada de productos - [GET /products/{id}](https://www.tiendy.com.py/docs/referencia/get-product): Detalle de un producto - [GET /products/by-slug/{slug}](https://www.tiendy.com.py/docs/referencia/get-product-by-slug): Detalle de un producto por su slug - [GET /categories](https://www.tiendy.com.py/docs/referencia/list-categories): Categorías visibles de la tienda - [GET /geo/cities](https://www.tiendy.com.py/docs/referencia/list-cities): Catálogo de departamentos y ciudades - [POST /cart/quote](https://www.tiendy.com.py/docs/referencia/quote-cart): Cotiza las líneas del carrito - [POST /checkout](https://www.tiendy.com.py/docs/referencia/create-checkout): Crea un pedido como invitado - [GET /altcha/challenge](https://www.tiendy.com.py/docs/referencia/get-altcha-challenge): Emite un desafío ALTCHA - [GET /orders/{token}](https://www.tiendy.com.py/docs/referencia/get-order): Estado de un pedido - [GET /orders/by-payment-hash/{hash}](https://www.tiendy.com.py/docs/referencia/get-order-by-payment-hash): Estado de un pedido por hash de Pagopar - [POST /orders/{token}/pay](https://www.tiendy.com.py/docs/referencia/pay-order): Inicia el pago con tarjeta (Stripe) - [POST /orders/{token}/proof/upload](https://www.tiendy.com.py/docs/referencia/upload-order-proof): Sube el archivo del comprobante (paso 1) - [POST /orders/{token}/proof](https://www.tiendy.com.py/docs/referencia/attach-order-proof): Asocia el comprobante al pedido (paso 2) ## Eventos de webhook - [order.created](https://www.tiendy.com.py/docs/referencia/webhook-order-created): Se creó un pedido - [order.paid](https://www.tiendy.com.py/docs/referencia/webhook-order-paid): Un pedido pasó a pagado - [order.status_changed](https://www.tiendy.com.py/docs/referencia/webhook-order-status-changed): Cambió el estado de un pedido - [order.proof_uploaded](https://www.tiendy.com.py/docs/referencia/webhook-order-proof-uploaded): El comprador subió el comprobante de pago