{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Wendoshop Developers API","version":"1.10.0","summary":"API pública para integrar catálogo, órdenes, clientes, carritos y webhooks.","description":"El nombre público, el contacto y los dominios de marca se incorporan al publicar este contrato. Todas las operaciones están aisladas por la tienda asociada al token. Las rutas /api/v1/* siguen disponibles con la página en construcción o mantenimiento activa, tanto en el dominio propio como en el subdominio de la tienda. Conservan la autenticación Bearer, los permisos, el nivel de API y los límites de solicitudes. El modo construcción no evita el bloqueo de una tienda suspendida.","contact":{"name":"Wendoshop Developers","email":"hola@wendoshop.com"}},"servers":[{"url":"https://{storeDomain}","description":"Dominio público de la tienda","variables":{"storeDomain":{"default":"store.example.com","description":"Dominio propio o subdominio asignado a la tienda"}}}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Productos","description":"Consulta, creación y actualización del catálogo."},{"name":"Stock","description":"Sincronización masiva de stock por SKU."},{"name":"Variantes","description":"Administración de variantes de producto."},{"name":"Imágenes","description":"Galerías de imágenes de producto."},{"name":"Categorías","description":"Consulta y administración de categorías."},{"name":"Órdenes","description":"Consulta y creación de órdenes externas."},{"name":"Customers","description":"Consulta protegida de perfiles y actividad de clientes."},{"name":"Carritos","description":"Consulta de carritos abandonados."},{"name":"Webhooks","description":"Suscripciones a eventos de la tienda."}],"paths":{"/api/v1/products":{"get":{"operationId":"listProducts","tags":["Productos"],"summary":"Listar productos","description":"Lista el catálogo de la tienda con categoría principal, additional_category_ids, galería y variantes. Cada variante incluye sale_price, cost, barcode e image_url, con null cuando no tienen valor. Por defecto devuelve únicamente productos activos. Incluye show_in_offers y show_sale_badge en cada producto.","x-api-tier":"basic","x-required-scopes":["products:read"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sku","in":"query","description":"SKU exacto del producto base.","schema":{"type":"string"}},{"name":"category_id","in":"query","description":"Categoría principal o adicional.","schema":{"type":"integer","minimum":1}},{"name":"tag","in":"query","description":"Una etiqueta exacta. Ignora mayúsculas y espacios exteriores; conserva acentos y guiones. Se combina con brand y category_id mediante AND. La API permite consultar todas las etiquetas de la tienda, independientemente de su visibilidad pública.","schema":{"type":"string","maxLength":60}},{"name":"brand","in":"query","description":"Marca exacta. Ignora mayúsculas y espacios exteriores. Se combina con tag y category_id mediante AND.","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","inactive","draft","all"],"default":"active"}},{"name":"active","in":"query","deprecated":true,"description":"Compatibilidad: false equivale a status=all.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Listado paginado de productos.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","slug","price","stock","status","images","variants","brand","tags","show_in_offers","show_sale_badge","additional_category_ids"],"properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"brand":{"type":["string","null"],"maxLength":120},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas guardadas del producto; [] cuando no tiene etiquetas."},"sku":{"type":["string","null"],"maxLength":120},"barcode":{"type":["string","null"],"maxLength":120},"short_description":{"type":["string","null"],"maxLength":500},"description":{"type":["string","null"],"maxLength":20000},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"product_type":{"type":"string","enum":["physical","digital_download","manual_digital_delivery","service"]},"requires_shipping":{"type":"boolean"},"requires_stock":{"type":"boolean"},"automatic_delivery":{"type":"boolean"},"limits_service_capacity":{"type":"boolean"},"available_service_capacity":{"type":["integer","null"],"minimum":0},"max_service_capacity_per_order":{"type":["integer","null"],"minimum":0},"shows_service_capacity":{"type":"boolean"},"status":{"type":"string","enum":["active","inactive","draft"]},"active":{"type":"boolean"},"additional_category_ids":{"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647},"uniqueItems":true,"description":"Additional category IDs in assignment order, excluding the primary category. Always returned, including [] when none are assigned."},"category":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"images":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"maxItems":20},"variants":{"type":"array","items":{"type":"object","required":["id","attributes","sku","price","sale_price","cost","barcode","image_url","stock","active"],"properties":{"id":{"type":"integer","minimum":1},"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"show_price":{"type":"boolean"},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true}},"meta":{"type":"object","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0,"maximum":200},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Filtros inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"patch":{"operationId":"syncProductStock","tags":["Stock"],"summary":"Sincronizar stock por SKU","description":"Procesa hasta 500 entradas, rechaza SKU ambiguos y evita aplicar snapshots obsoletos. Cada entrada informa su propio resultado.","x-api-tier":"basic","x-required-scopes":["products:write_stock"],"x-idempotency":{"header":"Idempotency-Key","required":false,"retention":"24 horas","scope":"tienda y credencial"},"x-side-effects":["Actualiza stock de productos o variantes","Puede emitir eventos de stock"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9._~:+-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","maxItems":500,"items":{"type":"object","required":["sku","stock"],"properties":{"sku":{"type":"string","minLength":1},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"source_updated_at":{"type":"string","format":"date-time","description":"Debe incluir zona horaria y no puede adelantarse más de cinco minutos al reloj del servidor."}},"additionalProperties":true}},"example":[{"sku":"SKU-001","stock":30,"source_updated_at":"2026-08-14T14:30:00Z"}]}}},"responses":{"200":{"description":"Resultado por cada SKU recibido.","content":{"application/json":{"schema":{"type":"object","required":["results","meta"],"properties":{"results":{"type":"array","items":{"type":"object","required":["sku","updated","resource"],"properties":{"sku":{"type":"string"},"updated":{"type":"boolean"},"resource":{"type":["string","null"],"enum":["product","variant",null]},"ids":{"type":"array","items":{"type":"integer","minimum":1}},"product_ids":{"type":"array","items":{"type":"integer","minimum":1}},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"updated_at":{"type":"string","format":"date-time"},"stock_updated_at":{"type":"string","format":"date-time"},"source_updated_at":{"type":["string","null"],"format":"date-time"},"error":{"type":"string","enum":["SKU_REQUIRED","INVALID_STOCK","INVALID_SOURCE_UPDATED_AT","DUPLICATE_SKU_IN_BATCH","SKU_NOT_FOUND","AMBIGUOUS_SKU","STALE_STOCK_UPDATE"]},"details":{"type":"string"}},"additionalProperties":false}},"meta":{"type":"object","required":["received","updated","failed","idempotent_replay"],"properties":{"received":{"type":"integer","minimum":0,"maximum":500},"updated":{"type":"integer","minimum":0,"maximum":500},"failed":{"type":"integer","minimum":0,"maximum":500},"idempotent_replay":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Body o Idempotency-Key inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"409":{"description":"La clave de idempotencia fue reutilizada con otro body o sigue en proceso.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"post":{"operationId":"createProduct","tags":["Productos"],"summary":"Crear un producto físico","description":"Crea un producto físico y opcionalmente su categoría y galería inicial. Solo se puede enviar una referencia de categoría principal y una modalidad de imágenes. additional_category_ids asigna categorías adicionales existentes de la misma tienda sin reemplazar la principal. Producto y asignaciones se guardan en una única transacción. Con copy_images=true se guarda el producto y se encola una copia asíncrona; image_import aparece fuera de data. La galería anterior se conserva hasta completar todas las copias. Requiere que la API key y el acceso avanzado sigan vigentes al procesar. POST no es idempotente: si una creación se repite puede devolver 409; recuperar el producto por SKU y usar PATCH para reintentar imágenes.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Crea un producto","Puede crear una categoría por nombre","Asigna categorías adicionales existentes","Actualiza la galería","Invalida caché pública"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"copy_images":{"type":"boolean","default":false,"description":"Opt-in asynchronous copying to managed storage. Requires a non-empty images array or image_url. Omit or set false to keep storing URLs without copying. With true, existing images stay unchanged until every copy succeeds; new products initially have an empty gallery. Images must be public HTTP/HTTPS on default ports, at most 8 MiB each, JPEG/PNG/WebP/AVIF/GIF and at most 40 million decoded pixels. Copies are resized within 1600x1600 and converted to WebP. Not supported on variant or gallery endpoints."},"name":{"type":"string","minLength":2,"maxLength":200},"brand":{"type":["string","null"],"maxLength":120,"description":"Marca opcional del fabricante. null o texto vacío la limpia. Omitirla en PATCH conserva el valor actual."},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"slug":{"type":"string","maxLength":200},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"status":{"type":"string","enum":["active","inactive","draft"]},"description":{"type":["string","null"],"maxLength":20000,"description":"Text or HTML. Storefront rendering allows p, br, strong, b, em, i, u, s, del, h1-h6, ul, ol, li, a, img, blockquote, pre, code, table, thead, tbody, tr, th, td, div, span and hr. Scripts, event handlers and unsafe attributes/styles are removed. Images embedded in description are not copied by copy_images."},"short_description":{"type":["string","null"],"maxLength":500},"category":{"type":["string","null"],"maxLength":100,"description":"No combinar con category_id ni category_slug. En PATCH cambia o limpia la categoría principal; conserva las adicionales salvo que se envíe additional_category_ids. Omitir este campo conserva la principal."},"category_id":{"type":["integer","null"],"minimum":1,"description":"No combinar con category ni category_slug. En PATCH cambia o limpia la categoría principal; conserva las adicionales salvo que se envíe additional_category_ids. Omitir este campo conserva la principal."},"category_slug":{"type":["string","null"],"maxLength":100,"description":"No combinar con category ni category_id. En PATCH cambia o limpia la categoría principal; conserva las adicionales salvo que se envíe additional_category_ids. Omitir este campo conserva la principal."},"additional_category_ids":{"type":"array","maxItems":20,"items":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Replaces additional categories without changing the primary category. Omit in PATCH to preserve extras; [] clears them; null is invalid. All IDs must exist in this store (422 INVALID_ADDITIONAL_CATEGORIES otherwise); categories are not created by this field. Duplicate IDs and the effective primary ID are removed. May be combined with one primary-category reference. If both are sent, the supplied extras replace the previous extras; the old primary can be explicitly retained as an extra. Allowed without a primary category. Assignment order is preserved. Updates are atomic with the product write; repeated PATCH assignments preserve the same memberships. POST defaults to no additional categories."},"sku":{"type":["string","null"],"maxLength":120},"barcode":{"type":["string","null"],"maxLength":120},"tags":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":60},"description":"Reemplaza todas las etiquetas; [] las limpia. Omitir tags en PATCH conserva las existentes. Guardarlas no las publica como filtros: el seller elige las etiquetas públicas en Configuración → Catálogo."},"image_url":{"type":["string","null"],"format":"uri","maxLength":500,"description":"No combinar con images."},"images":{"type":"array","maxItems":20,"description":"No combinar con image_url.","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0}},"additionalProperties":false}},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"free_shipping":{"type":"boolean"}},"additionalProperties":false},{"required":["name","price"]}]},"example":{"name":"Producto de ejemplo","price":15000,"status":"inactive","sku":"SKU-001","stock":10,"brand":"Marca de ejemplo","tags":["Exterior"],"label":"Nuevo","label_color":"blue","label_icon":"star","category_id":123,"additional_category_ids":[456]}}}},"responses":{"201":{"description":"Producto creado.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","slug","price","status","brand","tags","show_in_offers","show_sale_badge","additional_category_ids"],"properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"id":{"type":"integer","minimum":1},"name":{"type":"string"},"brand":{"type":["string","null"],"maxLength":120},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"tags":{"type":"array","items":{"type":"string"}},"slug":{"type":"string"},"sku":{"type":["string","null"]},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["active","inactive","draft"]},"additional_category_ids":{"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647},"uniqueItems":true,"description":"Additional category IDs in assignment order, excluding the primary category. Always returned, including [] when none are assigned."},"category":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"string"},{"type":"null"}]},"category_details":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"image_url":{"type":["string","null"],"format":"uri"},"images":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}},"additionalProperties":true},"image_import":{"type":"object","required":["id","status","status_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","superseded"]},"status_url":{"type":"string","description":"Relative authenticated status URL. Poll no more often than every 5 seconds and respect API rate limits."}}}}}}}},"400":{"description":"Body o campos inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"402":{"description":"La tienda alcanzó su límite de productos.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"409":{"description":"Slug o SKU duplicado.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"422":{"description":"La categoría principal referenciada no existe, o additional_category_ids contiene una categoría inexistente o de otra tienda (code=INVALID_ADDITIONAL_CATEGORIES). Se revierte toda la escritura.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo crear el producto.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/v1/products/{id}":{"delete":{"operationId":"deleteProduct","tags":["Productos"],"summary":"Eliminar definitivamente un producto","description":"Borra el producto de la tienda autenticada, sus variantes y relaciones de catálogo. Es irreversible. Conserva los snapshots de órdenes y el historial comercial. Para retirar temporalmente un producto, usar PATCH con status=inactive. Requiere una API key con products:delete elegido expresamente; products:write y las claves heredadas no lo habilitan. Repetir DELETE no duplica efectos: después del primer éxito devuelve 404. No requiere body ni Idempotency-Key. Los recursos multimedia no compartidos se limpian de forma best-effort después del commit; no se emite un webhook de borrado.","x-api-tier":"advanced","x-required-scopes":["products:delete"],"x-side-effects":["Elimina definitivamente producto y variantes","Registra actor y eliminación en el historial","Invalida caché pública","Programa limpieza de multimedia no compartida"],"responses":{"200":{"description":"Producto eliminado.","content":{"application/json":{"schema":{"type":"object","required":["deleted_id"],"properties":{"deleted_id":{"type":"integer","minimum":1}},"additionalProperties":false},"example":{"deleted_id":123}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"El producto no existe en esta tienda o ya fue eliminado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo eliminar el producto.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getProduct","tags":["Productos"],"summary":"Obtener un producto","description":"Devuelve un producto de la tienda aunque esté activo, inactivo o en borrador. variants incluye sale_price, cost, barcode e image_url, con null cuando no tienen valor. Incluye additional_category_ids, show_in_offers y show_sale_badge a nivel producto.","x-api-tier":"basic","x-required-scopes":["products:read"],"responses":{"200":{"description":"Producto encontrado.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","slug","price","stock","status","images","variants","brand","tags","show_in_offers","show_sale_badge","additional_category_ids"],"properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"brand":{"type":["string","null"],"maxLength":120},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas guardadas del producto; [] cuando no tiene etiquetas."},"sku":{"type":["string","null"],"maxLength":120},"barcode":{"type":["string","null"],"maxLength":120},"short_description":{"type":["string","null"],"maxLength":500},"description":{"type":["string","null"],"maxLength":20000},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"product_type":{"type":"string","enum":["physical","digital_download","manual_digital_delivery","service"]},"requires_shipping":{"type":"boolean"},"requires_stock":{"type":"boolean"},"automatic_delivery":{"type":"boolean"},"limits_service_capacity":{"type":"boolean"},"available_service_capacity":{"type":["integer","null"],"minimum":0},"max_service_capacity_per_order":{"type":["integer","null"],"minimum":0},"shows_service_capacity":{"type":"boolean"},"status":{"type":"string","enum":["active","inactive","draft"]},"active":{"type":"boolean"},"additional_category_ids":{"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647},"uniqueItems":true,"description":"Additional category IDs in assignment order, excluding the primary category. Always returned, including [] when none are assigned."},"category":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"images":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"maxItems":20},"variants":{"type":"array","items":{"type":"object","required":["id","attributes","sku","price","sale_price","cost","barcode","image_url","stock","active"],"properties":{"id":{"type":"integer","minimum":1},"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"show_price":{"type":"boolean"},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true}}}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado en la tienda del token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"patch":{"operationId":"updateProduct","tags":["Productos"],"summary":"Actualizar un producto","description":"Actualiza únicamente los campos enviados. show_in_offers y show_sale_badge aceptan solo booleanos y conservan su valor si se omiten. No modifican precios ni etiquetas manuales. category, category_id o category_slug actualizan solo la categoría principal y conservan las adicionales si se omite additional_category_ids. Cambiarla quita la principal anterior de sus asignaciones; null quita solo esa principal. additional_category_ids reemplaza las adicionales: [] las limpia; omitirlas las conserva. Se puede enviar junto a la principal y retener la principal anterior como adicional explícita. Los IDs repetidos y la principal efectiva se excluyen de las adicionales. Producto y asignaciones se guardan atómicamente; repetir solo la asignación mantiene el mismo resultado. No modifica las reglas automáticas de Novedades u Ofertas. En productos con variantes activas, el precio y el stock se administran por variante. Con copy_images=true se guarda el producto y se encola una copia asíncrona; image_import aparece fuera de data. La galería anterior se conserva hasta completar todas las copias. Requiere que la API key y el acceso avanzado sigan vigentes al procesar. POST no es idempotente: si una creación se repite puede devolver 409; recuperar el producto por SKU y usar PATCH para reintentar imágenes.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Actualiza catálogo","Puede reemplazar la galería","Puede reemplazar categorías adicionales","Invalida caché pública"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"copy_images":{"type":"boolean","default":false,"description":"Opt-in asynchronous copying to managed storage. Requires a non-empty images array or image_url. Omit or set false to keep storing URLs without copying. With true, existing images stay unchanged until every copy succeeds; new products initially have an empty gallery. Images must be public HTTP/HTTPS on default ports, at most 8 MiB each, JPEG/PNG/WebP/AVIF/GIF and at most 40 million decoded pixels. Copies are resized within 1600x1600 and converted to WebP. Not supported on variant or gallery endpoints."},"name":{"type":"string","minLength":2,"maxLength":200},"brand":{"type":["string","null"],"maxLength":120,"description":"Marca opcional del fabricante. null o texto vacío la limpia. Omitirla en PATCH conserva el valor actual."},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"slug":{"type":"string","maxLength":200},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"status":{"type":"string","enum":["active","inactive","draft"]},"description":{"type":["string","null"],"maxLength":20000,"description":"Text or HTML. Storefront rendering allows p, br, strong, b, em, i, u, s, del, h1-h6, ul, ol, li, a, img, blockquote, pre, code, table, thead, tbody, tr, th, td, div, span and hr. Scripts, event handlers and unsafe attributes/styles are removed. Images embedded in description are not copied by copy_images."},"short_description":{"type":["string","null"],"maxLength":500},"category":{"type":["string","null"],"maxLength":100,"description":"No combinar con category_id ni category_slug. En PATCH cambia o limpia la categoría principal; conserva las adicionales salvo que se envíe additional_category_ids. Omitir este campo conserva la principal."},"category_id":{"type":["integer","null"],"minimum":1,"description":"No combinar con category ni category_slug. En PATCH cambia o limpia la categoría principal; conserva las adicionales salvo que se envíe additional_category_ids. Omitir este campo conserva la principal."},"category_slug":{"type":["string","null"],"maxLength":100,"description":"No combinar con category ni category_id. En PATCH cambia o limpia la categoría principal; conserva las adicionales salvo que se envíe additional_category_ids. Omitir este campo conserva la principal."},"additional_category_ids":{"type":"array","maxItems":20,"items":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Replaces additional categories without changing the primary category. Omit in PATCH to preserve extras; [] clears them; null is invalid. All IDs must exist in this store (422 INVALID_ADDITIONAL_CATEGORIES otherwise); categories are not created by this field. Duplicate IDs and the effective primary ID are removed. May be combined with one primary-category reference. If both are sent, the supplied extras replace the previous extras; the old primary can be explicitly retained as an extra. Allowed without a primary category. Assignment order is preserved. Updates are atomic with the product write; repeated PATCH assignments preserve the same memberships. POST defaults to no additional categories."},"sku":{"type":["string","null"],"maxLength":120},"barcode":{"type":["string","null"],"maxLength":120},"tags":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":60},"description":"Reemplaza todas las etiquetas; [] las limpia. Omitir tags en PATCH conserva las existentes. Guardarlas no las publica como filtros: el seller elige las etiquetas públicas en Configuración → Catálogo."},"image_url":{"type":["string","null"],"format":"uri","maxLength":500,"description":"No combinar con images."},"images":{"type":"array","maxItems":20,"description":"No combinar con image_url.","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0}},"additionalProperties":false}},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"free_shipping":{"type":"boolean"}},"additionalProperties":false},"example":{"additional_category_ids":[456]}}}},"responses":{"200":{"description":"Producto actualizado.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","slug","price","status","brand","tags","show_in_offers","show_sale_badge","additional_category_ids"],"properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"id":{"type":"integer","minimum":1},"name":{"type":"string"},"brand":{"type":["string","null"],"maxLength":120},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"tags":{"type":"array","items":{"type":"string"}},"slug":{"type":"string"},"sku":{"type":["string","null"]},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["active","inactive","draft"]},"additional_category_ids":{"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647},"uniqueItems":true,"description":"Additional category IDs in assignment order, excluding the primary category. Always returned, including [] when none are assigned."},"category":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"string"},{"type":"null"}]},"category_details":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"image_url":{"type":["string","null"],"format":"uri"},"images":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}},"additionalProperties":true},"image_import":{"type":"object","required":["id","status","status_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","superseded"]},"status_url":{"type":"string","description":"Relative authenticated status URL. Poll no more often than every 5 seconds and respect API rate limits."}}}}}}}},"400":{"description":"Body o campos inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"Slug o SKU duplicado.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"422":{"description":"Categoría principal inexistente, categorías adicionales inválidas (code=INVALID_ADDITIONAL_CATEGORIES) o producto con variantes que requiere actualización por variante. Se revierte toda la escritura.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo actualizar el producto.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/v1/products/{id}/image-imports/{importId}":{"get":{"operationId":"getProductImageImport","tags":["Imágenes"],"summary":"Consultar una importación de imágenes","description":"Consulta una tarea de la tienda autenticada. completed indica que todas las copias se aplicaron a la galería. failed conserva la galería anterior; superseded indica una solicitud reemplazada o una galería modificada posteriormente. Las descargas transitorias se reintentan hasta tres veces, con esperas de 30 y 60 segundos y recuperación por un worker global cada minuto; el tiempo total depende de la cola. Repetir el mismo PATCH con copy_images=true reutiliza la tarea si la galería no cambió y reintenta los ítems fallidos sin volver a copiar los completados. Una nueva solicitud distinta reemplaza la pendiente. No hay un webhook nuevo: consultar este endpoint y luego GET del producto. Las tareas desaparecen si se elimina el producto o la tienda.","x-api-tier":"basic","x-required-scopes":["products:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"importId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado y resultado por imagen.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"type":"object","required":["id","status","status_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","superseded"]},"status_url":{"type":"string","description":"Relative authenticated status URL. Poll no more often than every 5 seconds and respect API rate limits."}}},{"type":"object","required":["product_id","total","copied","error","items","created_at","updated_at"],"properties":{"product_id":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":1,"maximum":20},"copied":{"type":"integer","minimum":0,"maximum":20},"error":{"type":["object","null"],"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable English code. Includes IMAGE_SOURCE_BLOCKED, IMAGE_SOURCE_HTTP_ERROR, IMAGE_SOURCE_UNREACHABLE, IMAGE_REDIRECT_FAILED, IMAGE_TOO_LARGE, UNSUPPORTED_IMAGE, IMAGE_PROCESSING_FAILED, IMAGE_STORAGE_FAILED, IMAGE_COPY_FAILED, IMAGE_RETRIES_EXHAUSTED, IMPORT_ACCESS_REVOKED, IMPORT_SUPERSEDED and GALLERY_CHANGED."},"message":{"type":"string"}},"additionalProperties":false},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["index","status","attempts","error","url"],"properties":{"index":{"type":"integer","minimum":0,"description":"Zero-based input position."},"status":{"type":"string","enum":["pending","copied","failed"]},"attempts":{"type":"integer","minimum":0,"maximum":3},"error":{"type":["object","null"],"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable English code. Includes IMAGE_SOURCE_BLOCKED, IMAGE_SOURCE_HTTP_ERROR, IMAGE_SOURCE_UNREACHABLE, IMAGE_REDIRECT_FAILED, IMAGE_TOO_LARGE, UNSUPPORTED_IMAGE, IMAGE_PROCESSING_FAILED, IMAGE_STORAGE_FAILED, IMAGE_COPY_FAILED, IMAGE_RETRIES_EXHAUSTED, IMPORT_ACCESS_REVOKED, IMPORT_SUPERSEDED and GALLERY_CHANGED."},"message":{"type":"string"}},"additionalProperties":false},"url":{"type":["string","null"],"format":"uri","description":"Managed URL, returned only when the whole import has completed. Source URLs are never returned here."}},"additionalProperties":false}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}]}},"additionalProperties":false}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Image import not found. Invalid identifiers and imports belonging to another store also return 404.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/products/{id}/variants":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"post":{"operationId":"createProductVariant","tags":["Variantes"],"summary":"Crear una variante","description":"Crea una combinación de atributos y rechaza SKU o combinaciones duplicadas dentro de la tienda.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Crea una variante","Registra historial de producto"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"show_price":{"type":"boolean"},"cost":{"type":["number","null"],"minimum":0},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":false},{"required":["attributes"]}]},"example":{"attributes":{"Talle":"M","Color":"Blanco"},"sku":"SKU-001-M","stock":10}}}},"responses":{"201":{"description":"Variante creada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","attributes","sku","price","sale_price","cost","barcode","image_url","stock","active"],"properties":{"id":{"type":"integer","minimum":1},"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"show_price":{"type":"boolean"},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true}}}}}},"400":{"description":"Body, precio o campos inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"SKU o combinación de atributos duplicados.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo crear la variante.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/v1/products/{id}/variants/{variantId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"variantId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"patch":{"operationId":"updateProductVariant","tags":["Variantes"],"summary":"Actualizar una variante","description":"Actualiza únicamente los campos enviados. Para retirarla sin perder trazabilidad, se puede enviar active=false.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Actualiza variante","Registra historial de producto"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"show_price":{"type":"boolean"},"cost":{"type":["number","null"],"minimum":0},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":false},{"minProperties":1}]}}}},"responses":{"200":{"description":"Variante actualizada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","attributes","sku","price","sale_price","cost","barcode","image_url","stock","active"],"properties":{"id":{"type":"integer","minimum":1},"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"show_price":{"type":"boolean"},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true}}}}}},"400":{"description":"Body, precio o campos inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Variante no encontrada en el producto y tienda indicados.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"SKU o combinación de atributos duplicados.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo actualizar la variante.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/v1/products/{id}/images":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"get":{"operationId":"listProductImages","tags":["Imágenes"],"summary":"Listar imágenes","x-api-tier":"basic","x-required-scopes":["products:read"],"responses":{"200":{"description":"Galería ordenada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}}}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"post":{"operationId":"createProductImage","tags":["Imágenes"],"summary":"Agregar una imagen","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Agrega imagen","Reordena galería cuando se indica una posición"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"responses":{"201":{"description":"Imagen agregada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}}}}},"400":{"description":"Body, URL u orden inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"422":{"description":"La galería alcanzó el máximo de 20 imágenes.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo agregar la imagen.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}}}},"put":{"operationId":"replaceProductImages","tags":["Imágenes"],"summary":"Reemplazar la galería","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Elimina y reemplaza la galería completa"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["images"],"properties":{"images":{"type":"array","maxItems":20,"items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0}},"additionalProperties":false}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Galería reemplazada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}}}}}},"400":{"description":"Body o imágenes inválidas.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"patch":{"operationId":"reorderProductImages","tags":["Imágenes"],"summary":"Reordenar la galería","description":"El array debe contener todos los IDs actuales exactamente una vez.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Reordena la galería"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ordered_image_ids"],"properties":{"ordered_image_ids":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"integer","minimum":1}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Galería reordenada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}}}}}},"400":{"description":"Body, IDs o conjunto de imágenes inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Producto no encontrado.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/products/{id}/images/{imageId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"imageId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"patch":{"operationId":"updateProductImage","tags":["Imágenes"],"summary":"Actualizar una imagen","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Actualiza imagen","Puede reordenar la galería"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}}},"responses":{"200":{"description":"Imagen actualizada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}}}}},"400":{"description":"Body o campos inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Imagen no encontrada en el producto y tienda indicados.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"delete":{"operationId":"deleteProductImage","tags":["Imágenes"],"summary":"Eliminar una imagen","description":"Elimina la imagen y normaliza el orden de las restantes.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Elimina imagen","Reordena la galería restante"],"responses":{"200":{"description":"Imagen eliminada.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}},"additionalProperties":false}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Imagen no encontrada en el producto y tienda indicados.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","tags":["Categorías"],"summary":"Listar categorías","description":"Lista las categorías de la tienda y la cantidad de productos asignados directa o adicionalmente.","x-api-tier":"basic","x-required-scopes":["products:read"],"responses":{"200":{"description":"Categorías de la tienda.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true}}}}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"post":{"operationId":"createCategory","tags":["Categorías"],"summary":"Crear una categoría","description":"Crea una categoría. Si el slug solicitado ya existe, el servicio de categorías genera uno disponible.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Crea una categoría","Invalida caché de categorías"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"visible_in_navigation":{"type":"boolean","default":true}},"additionalProperties":false},{"required":["name"]}]},"example":{"name":"Categoría de ejemplo","visible_in_navigation":true}}}},"responses":{"201":{"description":"Categoría creada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true}}}}}},"400":{"description":"Body o campos inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Categoría padre no encontrada.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getCategory","tags":["Categorías"],"summary":"Obtener una categoría","x-api-tier":"basic","x-required-scopes":["products:read"],"responses":{"200":{"description":"Categoría encontrada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true}}}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Categoría no encontrada.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"patch":{"operationId":"updateCategory","tags":["Categorías"],"summary":"Actualizar una categoría","description":"Actualiza parcialmente una categoría y rechaza una categoría padre inexistente o una jerarquía cíclica.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Actualiza categoría","Invalida caché de categorías"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"visible_in_navigation":{"type":"boolean","default":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Categoría actualizada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true}}}}}},"400":{"description":"Body inválido o sin campos modificables.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Categoría o categoría padre no encontrada.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"Slug duplicado o jerarquía cíclica.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"delete":{"operationId":"deleteCategory","tags":["Categorías"],"summary":"Eliminar una categoría","description":"Elimina una categoría sin subcategorías. Si tiene productos, requiere confirmación explícita para desasignarlos; nunca elimina productos.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Puede desasignar productos","Elimina categoría","Invalida caché de categorías"],"parameters":[{"name":"unassign_products","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Categoría eliminada.","content":{"application/json":{"schema":{"type":"object","required":["ok","products_unassigned"],"properties":{"ok":{"const":true},"products_unassigned":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Categoría no encontrada.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"Tiene subcategorías, requiere confirmación o recibió nuevas relaciones.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/orders":{"get":{"operationId":"listOrders","tags":["Órdenes"],"summary":"Listar órdenes","description":"Lista las órdenes de la tienda con sus pagos e items. Las entregas semanales elegidas en checkout incluyen el snapshot delivery_schedule en shipping_address.shipping_metadata; selected_date conserva la fecha local elegida al crear el pedido.","x-api-tier":"basic","x-required-scopes":["orders:read"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","ready_to_pack","packed","ready_for_pickup","shipped","delivered","cancelled"]}},{"name":"from","in":"query","description":"Incluye órdenes creadas desde esta fecha.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Incluye órdenes creadas hasta esta fecha.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Listado paginado de órdenes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","order_number","status","subtotal","total","currency","items","payments"],"properties":{"id":{"type":"integer","minimum":1},"order_number":{"type":"integer","minimum":1},"customer_email":{"type":["string","null"],"format":"email"},"customer_name":{"type":["string","null"]},"status":{"type":"string","enum":["pending","ready_to_pack","packed","ready_for_pickup","shipped","delivered","cancelled"]},"payment_status":{"type":"string"},"subtotal":{"type":"number","minimum":0},"shipping_cost":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"currency":{"type":"string"},"payment_method":{"type":["string","null"]},"shipping_method":{"type":["string","null"]},"payment_transaction_id":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"source":{"type":["string","null"]},"source_channel":{"type":["string","null"]},"external_reference":{"type":["string","null"]},"occurred_at":{"type":["string","null"],"format":"date-time"},"shipping_address":{"type":["object","null"],"properties":{"shipping_metadata":{"type":"object","properties":{"delivery_schedule":{"type":"object","description":"Delivery date selected during storefront checkout for a custom weekly delivery method. Stored at order creation; later configuration changes and payment retries do not reschedule it. Calendar days use the store time zone. Holidays are not automatically excluded.","required":["mode","weekdays","minimum_notice_days","time_zone","selected_date"],"properties":{"mode":{"const":"weekdays","type":"string"},"weekdays":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":7},"description":"ISO weekdays: Monday is 1 and Sunday is 7."},"minimum_notice_days":{"type":"integer","minimum":1,"maximum":365},"time_zone":{"type":"string","description":"IANA time zone used to calculate available dates."},"selected_date":{"type":"string","format":"date","description":"Selected local delivery date, YYYY-MM-DD."}},"additionalProperties":false}},"additionalProperties":true}},"additionalProperties":true},"notes":{"type":["string","null"]},"payments":{"type":"array","items":{"type":"object","required":["id","status","method","amount","currency"],"properties":{"id":{"type":"integer","minimum":1},"status":{"type":"string"},"method":{"type":"string"},"provider":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":"string"},"external_reference":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","required":["product_id","variant_id","name","sku","quantity","unit_price","subtotal"],"properties":{"product_id":{"type":"integer","minimum":1},"variant_id":{"type":["integer","null"],"minimum":1},"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"number","minimum":0},"subtotal":{"type":"number","minimum":0}},"additionalProperties":false}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true}},"meta":{"type":"object","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0,"maximum":200},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Paginación, fechas o estado inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"post":{"operationId":"createExternalOrder","tags":["Órdenes"],"summary":"Crear una venta externa","description":"Registra una venta física originada en un punto de venta externo. El servidor valida productos y precios. payment.status=paid requiere además payments:write_external.","x-api-tier":"advanced","x-required-scopes":["orders:create"],"x-conditional-scopes":[{"when":"payment.status = paid","scope":"payments:write_external"}],"x-idempotency":{"header":"Idempotency-Key","required":true,"retention":"30 días","scope":"tienda y credencial"},"x-side-effects":["Crea orden y pago externo","Puede descontar stock","Puede crear o actualizar comprador","Encola eventos","Puede notificar al seller o cliente"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9._~:+-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["external_reference","items","payment"],"properties":{"external_reference":{"type":"string","minLength":1,"maxLength":200},"channel":{"const":"pos","default":"pos"},"occurred_at":{"type":"string","format":"date-time","description":"Debe incluir zona horaria y no adelantarse más de cinco minutos al reloj del servidor."},"customer":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"default":"Consumidor final"},"email":{"type":"string","format":"email","maxLength":255},"phone":{"type":["string","null"],"maxLength":50}},"additionalProperties":false},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["product_id","quantity"],"properties":{"product_id":{"type":"integer","minimum":1},"variant_id":{"type":["integer","null"],"minimum":1},"quantity":{"type":"integer","minimum":1,"maximum":1000}},"additionalProperties":false}},"payment":{"type":"object","required":["status","method"],"properties":{"status":{"type":"string","enum":["pending","paid"]},"method":{"type":"string","enum":["cash","debit_card","credit_card","bank_transfer","wallet","other"]},"provider":{"type":["string","null"],"maxLength":80},"external_reference":{"type":["string","null"],"maxLength":300,"description":"Obligatoria para un pago confirmado que no sea en efectivo."}},"additionalProperties":false},"inventory_behavior":{"type":"string","enum":["deduct","skip"],"default":"deduct"},"fulfillment_status":{"type":"string","enum":["pending","delivered"],"default":"delivered"},"notify_customer":{"type":"boolean","default":false},"notify_admin":{"type":"boolean","default":false},"notes":{"type":["string","null"],"maxLength":2000}},"additionalProperties":false},"example":{"external_reference":"ticket-8472","channel":"pos","items":[{"product_id":12,"variant_id":34,"quantity":2}],"payment":{"status":"paid","method":"cash"},"inventory_behavior":"deduct","fulfillment_status":"delivered"}}}},"responses":{"201":{"description":"Orden creada o respuesta original recuperada por idempotencia.","headers":{"Idempotent-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Solo aparece en un replay completado."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","order_number","external_reference","channel","status","payment","subtotal","total","currency","inventory_behavior","items"],"properties":{"id":{"type":"integer","minimum":1},"order_number":{"type":"integer","minimum":1},"external_reference":{"type":"string"},"channel":{"const":"pos"},"status":{"type":"string","enum":["pending","delivered"]},"payment":{"type":"object","required":["status","method"],"properties":{"status":{"type":"string","enum":["pending","paid"]},"method":{"type":"string","enum":["cash","debit_card","credit_card","bank_transfer","wallet","other"]},"provider":{"type":["string","null"],"maxLength":80},"external_reference":{"type":["string","null"],"maxLength":300,"description":"Obligatoria para un pago confirmado que no sea en efectivo."}},"additionalProperties":false},"subtotal":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"currency":{"const":"ARS"},"inventory_behavior":{"type":"string","enum":["deduct","skip"]},"items":{"type":"array","items":{"type":"object","required":["product_id","variant_id","sku","quantity","unit_price","subtotal"],"properties":{"product_id":{"type":"integer","minimum":1},"variant_id":{"type":["integer","null"],"minimum":1},"sku":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"number","minimum":0},"subtotal":{"type":"number","minimum":0}},"additionalProperties":false}}},"additionalProperties":false},"meta":{"type":"object","required":["idempotent_replay"],"properties":{"idempotent_replay":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Body, campos o Idempotency-Key inválidos.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"Falta el plan, orders:create o el scope condicional de pagos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Producto o variante no encontrada en esta tienda.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"409":{"description":"Referencia duplicada, stock insuficiente o conflicto de idempotencia.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"422":{"description":"Producto no publicable, variante requerida, precio o total inválido.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}},"500":{"description":"No se pudo crear la orden.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]}}}}}}},"/api/v1/orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getOrder","tags":["Órdenes"],"summary":"Obtener una orden","x-api-tier":"basic","x-required-scopes":["orders:read"],"responses":{"200":{"description":"Orden encontrada.","content":{"application/json":{"schema":{"type":"object","required":["id","order_number","status","subtotal","total","currency","items","payments"],"properties":{"id":{"type":"integer","minimum":1},"order_number":{"type":"integer","minimum":1},"customer_email":{"type":["string","null"],"format":"email"},"customer_name":{"type":["string","null"]},"status":{"type":"string","enum":["pending","ready_to_pack","packed","ready_for_pickup","shipped","delivered","cancelled"]},"payment_status":{"type":"string"},"subtotal":{"type":"number","minimum":0},"shipping_cost":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"currency":{"type":"string"},"payment_method":{"type":["string","null"]},"shipping_method":{"type":["string","null"]},"payment_transaction_id":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"source":{"type":["string","null"]},"source_channel":{"type":["string","null"]},"external_reference":{"type":["string","null"]},"occurred_at":{"type":["string","null"],"format":"date-time"},"shipping_address":{"type":["object","null"],"properties":{"shipping_metadata":{"type":"object","properties":{"delivery_schedule":{"type":"object","description":"Delivery date selected during storefront checkout for a custom weekly delivery method. Stored at order creation; later configuration changes and payment retries do not reschedule it. Calendar days use the store time zone. Holidays are not automatically excluded.","required":["mode","weekdays","minimum_notice_days","time_zone","selected_date"],"properties":{"mode":{"const":"weekdays","type":"string"},"weekdays":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":7},"description":"ISO weekdays: Monday is 1 and Sunday is 7."},"minimum_notice_days":{"type":"integer","minimum":1,"maximum":365},"time_zone":{"type":"string","description":"IANA time zone used to calculate available dates."},"selected_date":{"type":"string","format":"date","description":"Selected local delivery date, YYYY-MM-DD."}},"additionalProperties":false}},"additionalProperties":true}},"additionalProperties":true},"notes":{"type":["string","null"]},"payments":{"type":"array","items":{"type":"object","required":["id","status","method","amount","currency"],"properties":{"id":{"type":"integer","minimum":1},"status":{"type":"string"},"method":{"type":"string"},"provider":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":"string"},"external_reference":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","required":["product_id","variant_id","name","sku","quantity","unit_price","subtotal"],"properties":{"product_id":{"type":"integer","minimum":1},"variant_id":{"type":["integer","null"],"minimum":1},"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"number","minimum":0},"subtotal":{"type":"number","minimum":0}},"additionalProperties":false}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Orden no encontrada en la tienda del token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"patch":{"operationId":"updateOrder","tags":["Órdenes"],"summary":"Actualizar estado o seguimiento","description":"Actualiza el estado operativo y/o el número de seguimiento de una orden de la tienda.","x-api-tier":"advanced","x-required-scopes":["orders:write"],"x-side-effects":["Actualiza estado operativo o seguimiento"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"status":{"type":"string","enum":["pending","ready_to_pack","packed","ready_for_pickup","shipped","delivered","cancelled"]},"tracking_number":{"type":"string"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Orden actualizada.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}},"additionalProperties":false}}}},"400":{"description":"Estado inválido o ningún campo reconocido.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Orden no encontrada.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/customers":{"get":{"operationId":"listCustomers","tags":["Customers"],"summary":"Listar clientes","description":"Lista perfiles registrados e invitados deduplicados por email dentro de la tienda. Para invitados, created_at corresponde a la primera orden. Los datos de contacto se ocultan por defecto.","x-api-tier":"advanced","x-required-scopes":["customers:read"],"x-conditional-scopes":[{"when":"include_contact = true","scope":"customers:read_contact"}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"query","in":"query","description":"Busca por email, nombre o apellido.","schema":{"type":"string","maxLength":200}},{"name":"profile_type","in":"query","schema":{"type":"string","enum":["all","registered","guest"],"default":"all"}},{"name":"activity","in":"query","schema":{"type":"string","enum":["all","with_orders","without_orders"],"default":"all"}},{"name":"archived","in":"query","description":"false devuelve perfiles activos; true devuelve únicamente perfiles archivados.","schema":{"type":"boolean","default":false}},{"name":"include_contact","in":"query","description":"Incluye email y teléfono completos. Requiere customers:read_contact.","schema":{"type":"boolean","default":false}},{"name":"from","in":"query","description":"Incluye perfiles creados desde esta fecha. Para invitados usa la fecha de la primera orden.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Incluye perfiles creados hasta esta fecha. Para invitados usa la fecha de la primera orden.","schema":{"type":"string","format":"date-time"}},{"name":"last_order_from","in":"query","description":"Incluye clientes cuya última orden ocurrió desde esta fecha.","schema":{"type":"string","format":"date-time"}},{"name":"last_order_to","in":"query","description":"Incluye clientes cuya última orden ocurrió hasta esta fecha.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Listado paginado de clientes.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["customer_key","profile_type","name","email_masked","email","phone","contact_included","email_verified","archived","order_count","last_order_at","created_at"],"properties":{"customer_key":{"type":"string","pattern":"^(registered:[1-9][0-9]*|guest:[a-f0-9]{32})$","description":"Clave del perfil dentro de la tienda. Debe tratarse como un identificador opaco y no derivarse ni interpretarse."},"profile_type":{"type":"string","enum":["registered","guest"]},"name":{"type":["string","null"]},"email_masked":{"type":"string","description":"Versión enmascarada disponible con customers:read."},"email":{"type":["string","null"],"format":"email","description":"Solo contiene el email completo cuando include_contact=true y la credencial tiene customers:read_contact."},"phone":{"type":["string","null"],"description":"Solo contiene el teléfono cuando include_contact=true y la credencial tiene customers:read_contact."},"contact_included":{"type":"boolean"},"email_verified":{"type":"boolean"},"archived":{"type":"boolean"},"order_count":{"type":"integer","minimum":0,"description":"Cantidad de órdenes asociadas, incluyendo todos los estados."},"last_order_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time","description":"Fecha de registro o, para invitados, fecha de su primera orden."}},"additionalProperties":false}},"meta":{"type":"object","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0,"maximum":200},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Filtros inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"Falta el plan avanzado, customers:read o el scope condicional de contacto.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/customers/{customerKey}":{"parameters":[{"name":"customerKey","in":"path","required":true,"description":"Clave opaca devuelta por listCustomers.","schema":{"type":"string","pattern":"^(registered:[1-9][0-9]*|guest:[a-f0-9]{32})$"}}],"get":{"operationId":"getCustomer","tags":["Customers"],"summary":"Obtener un cliente","description":"Obtiene un perfil registrado o invitado de la tienda. Los datos de contacto se ocultan por defecto.","x-api-tier":"advanced","x-required-scopes":["customers:read"],"x-conditional-scopes":[{"when":"include_contact = true","scope":"customers:read_contact"}],"parameters":[{"name":"include_contact","in":"query","description":"Incluye email y teléfono completos. Requiere customers:read_contact.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Cliente encontrado.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["customer_key","profile_type","name","email_masked","email","phone","contact_included","email_verified","archived","order_count","last_order_at","created_at"],"properties":{"customer_key":{"type":"string","pattern":"^(registered:[1-9][0-9]*|guest:[a-f0-9]{32})$","description":"Clave del perfil dentro de la tienda. Debe tratarse como un identificador opaco y no derivarse ni interpretarse."},"profile_type":{"type":"string","enum":["registered","guest"]},"name":{"type":["string","null"]},"email_masked":{"type":"string","description":"Versión enmascarada disponible con customers:read."},"email":{"type":["string","null"],"format":"email","description":"Solo contiene el email completo cuando include_contact=true y la credencial tiene customers:read_contact."},"phone":{"type":["string","null"],"description":"Solo contiene el teléfono cuando include_contact=true y la credencial tiene customers:read_contact."},"contact_included":{"type":"boolean"},"email_verified":{"type":"boolean"},"archived":{"type":"boolean"},"order_count":{"type":"integer","minimum":0,"description":"Cantidad de órdenes asociadas, incluyendo todos los estados."},"last_order_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time","description":"Fecha de registro o, para invitados, fecha de su primera orden."}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Clave o parámetros inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"Falta el plan avanzado, customers:read o el scope condicional de contacto.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Cliente no encontrado en la tienda de la credencial.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/abandoned-carts":{"get":{"operationId":"listAbandonedCarts","tags":["Carritos"],"summary":"Listar carritos abandonados","description":"Lista carritos con email e items, junto con su estado de recuperación.","x-api-tier":"advanced","x-required-scopes":["carts:read"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"from","in":"query","description":"Filtra por fecha de actualización desde este instante.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Filtra por fecha de actualización hasta este instante.","schema":{"type":"string","format":"date-time"}},{"name":"recovery_sent","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Listado paginado de carritos abandonados.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","email","items","total","recovery_sent"],"properties":{"id":{"type":"integer","minimum":1},"email":{"type":"string","format":"email"},"customer_name":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"recovery_sent":{"type":"boolean"},"recovery_sent_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","minItems":1,"items":{"type":"object","required":["product_id","name","sku","quantity","unit_price"],"properties":{"product_id":{"type":"integer","minimum":1},"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"number","minimum":0}},"additionalProperties":false}},"total":{"type":"number","minimum":0}},"additionalProperties":false}},"meta":{"type":"object","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0,"maximum":200},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Paginación, fechas o recovery_sent inválidos.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"Listar webhooks","description":"Lista los webhooks registrados para la tienda. El secret nunca se incluye.","x-api-tier":"basic","x-required-scopes":["webhooks:read"],"responses":{"200":{"description":"Webhooks de la tienda.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","url","events","active"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"last_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]}},"additionalProperties":true}}}}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Registrar un webhook","description":"Registra una URL pública y los eventos permitidos por el nivel de API. El secret se devuelve una sola vez.","x-api-tier":"basic","x-required-scopes":["webhooks:write"],"x-side-effects":["Crea suscripción durable","Genera un secret de firma"],"x-plan-limits":{"basic":2,"advanced":10,"enterprise":null},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"URL HTTP(S) pública que supera las validaciones SSRF del servidor."},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]},"description":"Los eventos habilitados dependen del nivel de API de la tienda."}},"additionalProperties":false},"example":{"url":"https://integracion.example.com/events","events":["order.created","stock.updated"]}}}},"responses":{"201":{"description":"Webhook creado. Guardar el secret inmediatamente.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["id","url","events","active"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"last_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]}},"additionalProperties":true},{"type":"object","required":["secret","warning"],"properties":{"secret":{"type":"string","readOnly":true},"warning":{"type":"string"}}}]}}}},"400":{"description":"Body, URL o eventos inválidos para el nivel de API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"422":{"description":"La tienda alcanzó su límite de webhooks.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}},"/api/v1/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Actualizar un webhook","description":"Activa, pausa o actualiza la URL y los eventos permitidos por el nivel de API.","x-api-tier":"basic","x-required-scopes":["webhooks:write"],"x-side-effects":["Actualiza suscripción de webhook"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]}},"active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Webhook actualizado.","content":{"application/json":{"schema":{"type":"object","required":["id","url","events","active"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"last_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]}},"additionalProperties":true}}}},"400":{"description":"ID, body, URL o eventos inválidos; también cuando no hay campos para actualizar.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Webhook no encontrado en la tienda del token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}},"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Eliminar un webhook","x-api-tier":"basic","x-required-scopes":["webhooks:write"],"x-side-effects":["Elimina suscripción de webhook"],"responses":{"200":{"description":"Webhook eliminado.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}},"additionalProperties":false}}}},"400":{"description":"ID inválido.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"403":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"404":{"description":"Webhook no encontrado en la tienda del token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}}}}},"webhooks":{"storeEvent":{"post":{"operationId":"receiveStoreEvent","summary":"Recibir un evento de tienda","description":"Wendo envía este request a la URL registrada. El body exacto se firma con HMAC-SHA256 usando el secret entregado al crear la suscripción. Una respuesta 2xx confirma la entrega; otras respuestas o errores de red se reintentan con backoff.","parameters":[{"name":"X-Wendo-Event","in":"header","required":true,"schema":{"anyOf":[{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]},{"type":"string","const":"webhook.test"}]}},{"name":"X-Wendo-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Wendo-Signature","in":"header","required":true,"description":"Firma con formato sha256=<hex> calculada sobre el body sin modificar.","schema":{"type":"string","pattern":"^sha256=[a-f0-9]{64}$"}},{"name":"X-Wendo-Store-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]*$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","store_id","created_at","data"],"properties":{"event":{"anyOf":[{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]},{"type":"string","const":"webhook.test"}]},"store_id":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["resource_type","resource_id"],"properties":{"resource_type":{"type":"string","enum":["order","contact","cart","return","product","variant","webhook"]},"resource_id":{"type":"integer","minimum":1},"order_id":{"type":"integer","minimum":1},"order_number":{"type":"integer","minimum":1},"return_id":{"type":"integer","minimum":1},"product_id":{"type":"integer","minimum":1},"variant_id":{"type":"integer","minimum":1},"amount":{"type":"number"},"reason":{"type":"string","enum":["pending_payment_expired"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":["string","null"]},"subject":{"type":["string","null"]},"message":{"type":"string"},"status":{"type":"string","enum":["new","spam","approved","rejected","refunded"]},"spam_status":{"type":"string","enum":["approved","suspicious"]},"source":{"type":"string","enum":["contact_form"]},"customer_name":{"type":["string","null"]},"customer_email":{"type":["string","null"],"format":"email"},"customer_message":{"type":["string","null"]},"items":{"type":"array","items":{"type":"object","properties":{"product_name":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"number"}},"additionalProperties":false}},"total":{"type":"number"},"action":{"type":"string","enum":["created","updated","deleted"]},"stock":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false},"example":{"event":"order.created","store_id":42,"created_at":"2026-08-19T12:00:00.000Z","data":{"resource_type":"order","resource_id":91,"order_id":91,"order_number":1201}}}}},"responses":{"2XX":{"description":"Entrega aceptada por el integrador."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Store API key enviada como Authorization: Bearer <token>. Las claves nuevas usan el prefijo wnd_sk_; las claves históricas con prefijo wsk_ continúan siendo válidas."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"CodedError":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]},"Pagination":{"type":"object","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0,"maximum":200},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"additionalProperties":false},"Product":{"type":"object","required":["id","name","slug","price","stock","status","images","variants","brand","tags","show_in_offers","show_sale_badge","additional_category_ids"],"properties":{"show_in_offers":{"type":"boolean","description":"Whether valid product or active variant sale prices include the product in automatic offer listings. Defaults to true on creation. Omit in PATCH to preserve. Does not change prices, tags, categories or manual labels. Applies to the entire product, including all its variants."},"show_sale_badge":{"type":"boolean","description":"Whether product cards show the automatic discount percentage or the notice about discounts on other variants. Defaults to true on creation. Omit in PATCH to preserve. Independent of show_in_offers; prices and manual labels remain visible."},"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"brand":{"type":["string","null"],"maxLength":120},"label":{"type":["string","null"],"maxLength":100,"description":"Single promotional label displayed using the store's product-card design. It is independent of tags and tag badges. null or an empty string clears the label. Omit in PATCH to preserve it. Defaults to null on creation."},"label_color":{"type":"string","enum":["black","red","orange","green","blue","purple"],"description":"Promotional label color. Defaults to black on creation. Omit in PATCH to preserve it; null is not accepted. Store design may override this color."},"label_icon":{"type":"string","enum":["lightning","star","flame","gift","heart","megaphone","none"],"description":"Promotional label icon. Defaults to lightning on creation. Omit in PATCH to preserve it; use none to hide it. Visibility depends on the product-card label style."},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas guardadas del producto; [] cuando no tiene etiquetas."},"sku":{"type":["string","null"],"maxLength":120},"barcode":{"type":["string","null"],"maxLength":120},"short_description":{"type":["string","null"],"maxLength":500},"description":{"type":["string","null"],"maxLength":20000},"price":{"type":"number","minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"product_type":{"type":"string","enum":["physical","digital_download","manual_digital_delivery","service"]},"requires_shipping":{"type":"boolean"},"requires_stock":{"type":"boolean"},"automatic_delivery":{"type":"boolean"},"limits_service_capacity":{"type":"boolean"},"available_service_capacity":{"type":["integer","null"],"minimum":0},"max_service_capacity_per_order":{"type":["integer","null"],"minimum":0},"shows_service_capacity":{"type":"boolean"},"status":{"type":"string","enum":["active","inactive","draft"]},"active":{"type":"boolean"},"additional_category_ids":{"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647},"uniqueItems":true,"description":"Additional category IDs in assignment order, excluding the primary category. Always returned, including [] when none are assigned."},"category":{"oneOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"images":{"type":"array","items":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"maxItems":20},"variants":{"type":"array","items":{"type":"object","required":["id","attributes","sku","price","sale_price","cost","barcode","image_url","stock","active"],"properties":{"id":{"type":"integer","minimum":1},"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"show_price":{"type":"boolean"},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"ProductImage":{"type":"object","required":["id","url","alt","sort_order"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"sort_order":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"ProductImageImport":{"allOf":[{"type":"object","required":["id","status","status_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","superseded"]},"status_url":{"type":"string","description":"Relative authenticated status URL. Poll no more often than every 5 seconds and respect API rate limits."}}},{"type":"object","required":["product_id","total","copied","error","items","created_at","updated_at"],"properties":{"product_id":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":1,"maximum":20},"copied":{"type":"integer","minimum":0,"maximum":20},"error":{"type":["object","null"],"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable English code. Includes IMAGE_SOURCE_BLOCKED, IMAGE_SOURCE_HTTP_ERROR, IMAGE_SOURCE_UNREACHABLE, IMAGE_REDIRECT_FAILED, IMAGE_TOO_LARGE, UNSUPPORTED_IMAGE, IMAGE_PROCESSING_FAILED, IMAGE_STORAGE_FAILED, IMAGE_COPY_FAILED, IMAGE_RETRIES_EXHAUSTED, IMPORT_ACCESS_REVOKED, IMPORT_SUPERSEDED and GALLERY_CHANGED."},"message":{"type":"string"}},"additionalProperties":false},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["index","status","attempts","error","url"],"properties":{"index":{"type":"integer","minimum":0,"description":"Zero-based input position."},"status":{"type":"string","enum":["pending","copied","failed"]},"attempts":{"type":"integer","minimum":0,"maximum":3},"error":{"type":["object","null"],"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable English code. Includes IMAGE_SOURCE_BLOCKED, IMAGE_SOURCE_HTTP_ERROR, IMAGE_SOURCE_UNREACHABLE, IMAGE_REDIRECT_FAILED, IMAGE_TOO_LARGE, UNSUPPORTED_IMAGE, IMAGE_PROCESSING_FAILED, IMAGE_STORAGE_FAILED, IMAGE_COPY_FAILED, IMAGE_RETRIES_EXHAUSTED, IMPORT_ACCESS_REVOKED, IMPORT_SUPERSEDED and GALLERY_CHANGED."},"message":{"type":"string"}},"additionalProperties":false},"url":{"type":["string","null"],"format":"uri","description":"Managed URL, returned only when the whole import has completed. Source URLs are never returned here."}},"additionalProperties":false}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}]},"ProductVariant":{"type":"object","required":["id","attributes","sku","price","sale_price","cost","barcode","image_url","stock","active"],"properties":{"id":{"type":"integer","minimum":1},"attributes":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":["number","null"],"minimum":0},"sale_price":{"type":["number","null"],"minimum":0},"cost":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"stock_updated_at":{"type":"string","format":"date-time"},"stock_source_updated_at":{"type":["string","null"],"format":"date-time"},"show_price":{"type":"boolean"},"barcode":{"type":["string","null"],"maxLength":50},"weight":{"type":["number","null"],"minimum":0},"height":{"type":["number","null"],"minimum":0},"width":{"type":["number","null"],"minimum":0},"depth":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"active":{"type":"boolean"},"image_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true},"Category":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":20000},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"sort_order":{"type":"integer"},"visible_in_navigation":{"type":"boolean"},"product_count":{"type":"integer","minimum":0}},"additionalProperties":true},"Order":{"type":"object","required":["id","order_number","status","subtotal","total","currency","items","payments"],"properties":{"id":{"type":"integer","minimum":1},"order_number":{"type":"integer","minimum":1},"customer_email":{"type":["string","null"],"format":"email"},"customer_name":{"type":["string","null"]},"status":{"type":"string","enum":["pending","ready_to_pack","packed","ready_for_pickup","shipped","delivered","cancelled"]},"payment_status":{"type":"string"},"subtotal":{"type":"number","minimum":0},"shipping_cost":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"currency":{"type":"string"},"payment_method":{"type":["string","null"]},"shipping_method":{"type":["string","null"]},"payment_transaction_id":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"source":{"type":["string","null"]},"source_channel":{"type":["string","null"]},"external_reference":{"type":["string","null"]},"occurred_at":{"type":["string","null"],"format":"date-time"},"shipping_address":{"type":["object","null"],"properties":{"shipping_metadata":{"type":"object","properties":{"delivery_schedule":{"type":"object","description":"Delivery date selected during storefront checkout for a custom weekly delivery method. Stored at order creation; later configuration changes and payment retries do not reschedule it. Calendar days use the store time zone. Holidays are not automatically excluded.","required":["mode","weekdays","minimum_notice_days","time_zone","selected_date"],"properties":{"mode":{"const":"weekdays","type":"string"},"weekdays":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":7},"description":"ISO weekdays: Monday is 1 and Sunday is 7."},"minimum_notice_days":{"type":"integer","minimum":1,"maximum":365},"time_zone":{"type":"string","description":"IANA time zone used to calculate available dates."},"selected_date":{"type":"string","format":"date","description":"Selected local delivery date, YYYY-MM-DD."}},"additionalProperties":false}},"additionalProperties":true}},"additionalProperties":true},"notes":{"type":["string","null"]},"payments":{"type":"array","items":{"type":"object","required":["id","status","method","amount","currency"],"properties":{"id":{"type":"integer","minimum":1},"status":{"type":"string"},"method":{"type":"string"},"provider":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":"string"},"external_reference":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","required":["product_id","variant_id","name","sku","quantity","unit_price","subtotal"],"properties":{"product_id":{"type":"integer","minimum":1},"variant_id":{"type":["integer","null"],"minimum":1},"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"number","minimum":0},"subtotal":{"type":"number","minimum":0}},"additionalProperties":false}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"Customer":{"type":"object","required":["customer_key","profile_type","name","email_masked","email","phone","contact_included","email_verified","archived","order_count","last_order_at","created_at"],"properties":{"customer_key":{"type":"string","pattern":"^(registered:[1-9][0-9]*|guest:[a-f0-9]{32})$","description":"Clave del perfil dentro de la tienda. Debe tratarse como un identificador opaco y no derivarse ni interpretarse."},"profile_type":{"type":"string","enum":["registered","guest"]},"name":{"type":["string","null"]},"email_masked":{"type":"string","description":"Versión enmascarada disponible con customers:read."},"email":{"type":["string","null"],"format":"email","description":"Solo contiene el email completo cuando include_contact=true y la credencial tiene customers:read_contact."},"phone":{"type":["string","null"],"description":"Solo contiene el teléfono cuando include_contact=true y la credencial tiene customers:read_contact."},"contact_included":{"type":"boolean"},"email_verified":{"type":"boolean"},"archived":{"type":"boolean"},"order_count":{"type":"integer","minimum":0,"description":"Cantidad de órdenes asociadas, incluyendo todos los estados."},"last_order_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time","description":"Fecha de registro o, para invitados, fecha de su primera orden."}},"additionalProperties":false},"Webhook":{"type":"object","required":["id","url","events","active"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"last_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]}},"additionalProperties":true},"WebhookDeliveryEnvelope":{"type":"object","required":["event","store_id","created_at","data"],"properties":{"event":{"anyOf":[{"type":"string","enum":["order.created","order.paid","payment.refunded","order.cancelled","stock.updated","contact.created","order.preparing","order.packed","order.ready_for_pickup","order.shipped","order.delivered","order.wholesale_shipping_updated","cart.abandoned","return.updated","product.created","product.updated","variant.updated"]},{"type":"string","const":"webhook.test"}]},"store_id":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["resource_type","resource_id"],"properties":{"resource_type":{"type":"string","enum":["order","contact","cart","return","product","variant","webhook"]},"resource_id":{"type":"integer","minimum":1},"order_id":{"type":"integer","minimum":1},"order_number":{"type":"integer","minimum":1},"return_id":{"type":"integer","minimum":1},"product_id":{"type":"integer","minimum":1},"variant_id":{"type":"integer","minimum":1},"amount":{"type":"number"},"reason":{"type":"string","enum":["pending_payment_expired"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":["string","null"]},"subject":{"type":["string","null"]},"message":{"type":"string"},"status":{"type":"string","enum":["new","spam","approved","rejected","refunded"]},"spam_status":{"type":"string","enum":["approved","suspicious"]},"source":{"type":"string","enum":["contact_form"]},"customer_name":{"type":["string","null"]},"customer_email":{"type":["string","null"],"format":"email"},"customer_message":{"type":["string","null"]},"items":{"type":"array","items":{"type":"object","properties":{"product_name":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"number"}},"additionalProperties":false}},"total":{"type":"number"},"action":{"type":"string","enum":["created","updated","deleted"]},"stock":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}},"responses":{"Unauthorized":{"description":"Token inválido, revocado, ausente o sin acceso vigente a la API.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Unauthorized","message":"API key inválida o no proporcionada"}}}},"Forbidden":{"description":"El plan o los scopes del token no permiten ejecutar la operación.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Forbidden","message":"Tu token o plan no tiene acceso a este endpoint."}}}},"RateLimited":{"description":"Se superó un límite por credencial, tienda o ventana de ráfaga.","headers":{"X-RateLimit-Limit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reason":{"schema":{"type":"string","enum":["credential_minute","store_minute","credential_burst","store_burst"]}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Segundos mínimos antes de reintentar."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"example":{"error":"Rate limit exceeded","message":"Demasiadas requests para tu plan. Intentá nuevamente en unos segundos."}}}}},"headers":{"RateLimitLimit":{"description":"Menor límite efectivo por minuto entre credencial y tienda.","schema":{"type":"integer","minimum":0}},"RateLimitRemaining":{"description":"Solicitudes restantes en la ventana por minuto.","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"Instante de reinicio de la ventana expresado como Unix timestamp en segundos.","schema":{"type":"integer","minimum":0}}}}}