{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Wendoshop Developers API","version":"1.0.0","summary":"API pública para integrar catálogo, órdenes, 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.","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":"Carritos","description":"Consulta de carritos abandonados."},{"name":"Webhooks","description":"Suscripciones a eventos de la tienda."}],"paths":{"/api/v1/productos":{"get":{"operationId":"listProducts","tags":["Productos"],"summary":"Listar productos","description":"Lista el catálogo de la tienda con categoría, galería y variantes. Por defecto devuelve únicamente productos activos.","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":"categoria_id","in":"query","description":"Categoría principal o adicional.","schema":{"type":"integer","minimum":1}},{"name":"estado","in":"query","schema":{"type":"string","enum":["activo","inactivo","borrador","todos"],"default":"activo"}},{"name":"activo","in":"query","deprecated":true,"description":"Compatibilidad: false equivale a estado=todos.","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","nombre","slug","precio","stock","estado","imagenes","variantes"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"sku":{"type":["string","null"],"maxLength":120},"codigo_barras":{"type":["string","null"],"maxLength":120},"descripcion_corta":{"type":["string","null"],"maxLength":500},"descripcion":{"type":["string","null"],"maxLength":20000},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"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"},"tipo_producto":{"type":"string"},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"activo":{"type":"boolean"},"categoria":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"imagenes":{"type":"array","items":{"type":"object","required":["id","url","alt","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"maxItems":20},"variantes":{"type":"array","items":{"type":"object","required":["id","atributos","sku","precio","stock","activa"],"properties":{"id":{"type":"integer","minimum":1},"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"costo":{"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"},"mostrar_precio":{"type":"boolean"},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_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":["resultados","meta"],"properties":{"resultados":{"type":"array","items":{"type":"object","required":["sku","actualizado","recurso"],"properties":{"sku":{"type":"string"},"actualizado":{"type":"boolean"},"recurso":{"type":["string","null"],"enum":["producto","variante",null]},"ids":{"type":"array","items":{"type":"integer","minimum":1}},"producto_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_REQUERIDO","STOCK_INVALIDO","SOURCE_UPDATED_AT_INVALIDO","SKU_DUPLICADO_EN_LOTE","SKU_NO_ENCONTRADO","SKU_AMBIGUO","STOCK_DESACTUALIZADO"]},"detalle":{"type":"string"}},"additionalProperties":false}},"meta":{"type":"object","required":["recibidos","actualizados","fallidos","idempotent_replay"],"properties":{"recibidos":{"type":"integer","minimum":0,"maximum":500},"actualizados":{"type":"integer","minimum":0,"maximum":500},"fallidos":{"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":["codigo"],"properties":{"codigo":{"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 y una modalidad de imágenes.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Crea un producto","Puede crear una categoría por nombre","Actualiza la galería","Invalida caché pública"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"nombre":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"descripcion":{"type":["string","null"],"maxLength":20000},"descripcion_corta":{"type":["string","null"],"maxLength":500},"categoria":{"type":["string","null"],"maxLength":100,"description":"No combinar con categoria_id ni categoria_slug."},"categoria_id":{"type":["integer","null"],"minimum":1,"description":"No combinar con categoria ni categoria_slug."},"categoria_slug":{"type":["string","null"],"maxLength":100,"description":"No combinar con categoria ni categoria_id."},"sku":{"type":["string","null"],"maxLength":120},"codigo_barras":{"type":["string","null"],"maxLength":120},"tags":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":60}},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500,"description":"No combinar con imagenes."},"imagenes":{"type":"array","maxItems":20,"description":"No combinar con imagen_url.","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0}},"additionalProperties":false}},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"envio_gratis":{"type":"boolean"}},"additionalProperties":false},{"required":["nombre","precio"]}]},"example":{"nombre":"Producto de ejemplo","precio":15000,"estado":"inactivo","sku":"SKU-001","stock":10}}}},"responses":{"201":{"description":"Producto creado.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","nombre","slug","precio","estado"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string"},"slug":{"type":"string"},"sku":{"type":["string","null"]},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"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"},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"categoria":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"string"},{"type":"null"}]},"categoria_detalle":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"imagen_url":{"type":["string","null"],"format":"uri"},"imagenes":{"type":"array","items":{"type":"object","required":["id","url","alt","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}},"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"}}}},"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":["codigo"],"properties":{"codigo":{"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":["codigo"],"properties":{"codigo":{"type":"string"}}}]}}}},"422":{"description":"La categoría referenciada no existe.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["codigo"],"properties":{"codigo":{"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/productos/{id}":{"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.","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","nombre","slug","precio","stock","estado","imagenes","variantes"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"sku":{"type":["string","null"],"maxLength":120},"codigo_barras":{"type":["string","null"],"maxLength":120},"descripcion_corta":{"type":["string","null"],"maxLength":500},"descripcion":{"type":["string","null"],"maxLength":20000},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"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"},"tipo_producto":{"type":"string"},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"activo":{"type":"boolean"},"categoria":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"imagenes":{"type":"array","items":{"type":"object","required":["id","url","alt","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"maxItems":20},"variantes":{"type":"array","items":{"type":"object","required":["id","atributos","sku","precio","stock","activa"],"properties":{"id":{"type":"integer","minimum":1},"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"costo":{"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"},"mostrar_precio":{"type":"boolean"},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_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. En productos con variantes activas, el precio y el stock se administran por variante.","x-api-tier":"advanced","x-required-scopes":["products:write"],"x-side-effects":["Actualiza catálogo","Puede reemplazar la galería","Invalida caché pública"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"descripcion":{"type":["string","null"],"maxLength":20000},"descripcion_corta":{"type":["string","null"],"maxLength":500},"categoria":{"type":["string","null"],"maxLength":100,"description":"No combinar con categoria_id ni categoria_slug."},"categoria_id":{"type":["integer","null"],"minimum":1,"description":"No combinar con categoria ni categoria_slug."},"categoria_slug":{"type":["string","null"],"maxLength":100,"description":"No combinar con categoria ni categoria_id."},"sku":{"type":["string","null"],"maxLength":120},"codigo_barras":{"type":["string","null"],"maxLength":120},"tags":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":60}},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500,"description":"No combinar con imagenes."},"imagenes":{"type":"array","maxItems":20,"description":"No combinar con imagen_url.","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0}},"additionalProperties":false}},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"envio_gratis":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Producto actualizado.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","nombre","slug","precio","estado"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string"},"slug":{"type":"string"},"sku":{"type":["string","null"]},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"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"},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"categoria":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"string"},{"type":"null"}]},"categoria_detalle":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"imagen_url":{"type":["string","null"],"format":"uri"},"imagenes":{"type":"array","items":{"type":"object","required":["id","url","alt","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false}}},"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":"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":["codigo"],"properties":{"codigo":{"type":"string"}}}]}}}},"422":{"description":"Categoría inexistente o producto con variantes que requiere actualización por variante.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},{"type":"object","required":["codigo"],"properties":{"codigo":{"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/productos/{id}/variantes":{"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":{"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"mostrar_precio":{"type":"boolean"},"costo":{"type":["number","null"],"minimum":0},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":false},{"required":["atributos"]}]},"example":{"atributos":{"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","atributos","sku","precio","stock","activa"],"properties":{"id":{"type":"integer","minimum":1},"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"costo":{"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"},"mostrar_precio":{"type":"boolean"},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_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":["codigo"],"properties":{"codigo":{"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/productos/{id}/variantes/{varianteId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"varianteId","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 activa=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":{"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"stock":{"type":["integer","null"],"minimum":0,"description":"null representa disponibilidad sin límite; 0 representa falta de unidades."},"mostrar_precio":{"type":"boolean"},"costo":{"type":["number","null"],"minimum":0},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_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","atributos","sku","precio","stock","activa"],"properties":{"id":{"type":"integer","minimum":1},"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"costo":{"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"},"mostrar_precio":{"type":"boolean"},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_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":["codigo"],"properties":{"codigo":{"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/productos/{id}/imagenes":{"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","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"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},"orden":{"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","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"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":["imagenes"],"properties":{"imagenes":{"type":"array","maxItems":20,"items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"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","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"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":["orden"],"properties":{"orden":{"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","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"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/productos/{id}/imagenes/{imagenId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"imagenId","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},"orden":{"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","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"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/categorias":{"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","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_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":{"nombre":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"visible_en_nav":{"type":"boolean","default":true}},"additionalProperties":false},{"required":["nombre"]}]},"example":{"nombre":"Categoría de ejemplo","visible_en_nav":true}}}},"responses":{"201":{"description":"Categoría creada.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_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/categorias/{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","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_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":{"nombre":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"visible_en_nav":{"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","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_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":"desasignar_productos","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Categoría eliminada.","content":{"application/json":{"schema":{"type":"object","required":["ok","productos_desasignados"],"properties":{"ok":{"const":true},"productos_desasignados":{"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/ordenes":{"get":{"operationId":"listOrders","tags":["Órdenes"],"summary":"Listar órdenes","description":"Lista las órdenes de la tienda con sus pagos e items.","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":"estado","in":"query","schema":{"type":"string","enum":["pendiente","por_empaquetar","empaquetado","listo_para_retirar","enviada","entregada","cancelada"]}},{"name":"desde","in":"query","description":"Incluye órdenes creadas desde esta fecha.","schema":{"type":"string","format":"date-time"}},{"name":"hasta","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","numero_orden","estado","subtotal","total","moneda","items","pagos"],"properties":{"id":{"type":"integer","minimum":1},"numero_orden":{"type":"integer","minimum":1},"comprador_email":{"type":["string","null"],"format":"email"},"comprador_nombre":{"type":["string","null"]},"estado":{"type":"string","enum":["pendiente","por_empaquetar","empaquetado","listo_para_retirar","enviada","entregada","cancelada"]},"pago_estado":{"type":"string"},"subtotal":{"type":"number","minimum":0},"costo_envio":{"type":"number","minimum":0},"descuento":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"moneda":{"type":"string"},"metodo_pago":{"type":["string","null"]},"metodo_envio":{"type":["string","null"]},"id_transaccion_pago":{"type":["string","null"]},"numero_seguimiento":{"type":["string","null"]},"fuente":{"type":["string","null"]},"canal_origen":{"type":["string","null"]},"referencia_externa":{"type":["string","null"]},"ocurrio_en":{"type":["string","null"],"format":"date-time"},"direccion_envio":{"type":["object","null"],"additionalProperties":true},"notas":{"type":["string","null"]},"pagos":{"type":"array","items":{"type":"object","required":["id","estado","metodo","monto","moneda"],"properties":{"id":{"type":"integer","minimum":1},"estado":{"type":"string"},"metodo":{"type":"string"},"proveedor":{"type":["string","null"]},"monto":{"type":"number","minimum":0},"moneda":{"type":"string"},"referencia_externa":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","required":["producto_id","variante_id","nombre","sku","cantidad","precio_unitario","subtotal"],"properties":{"producto_id":{"type":"integer","minimum":1},"variante_id":{"type":["integer","null"],"minimum":1},"nombre":{"type":"string"},"sku":{"type":["string","null"]},"cantidad":{"type":"integer","minimum":1},"precio_unitario":{"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":"Estado 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."}}}},"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. pago.estado=pagado requiere además payments:write_external.","x-api-tier":"advanced","x-required-scopes":["orders:create"],"x-conditional-scopes":[{"when":"pago.estado = pagado","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":["referencia_externa","items","pago"],"properties":{"referencia_externa":{"type":"string","minLength":1,"maxLength":200},"canal":{"const":"pos","default":"pos"},"ocurrio_en":{"type":"string","format":"date-time","description":"Debe incluir zona horaria y no adelantarse más de cinco minutos al reloj del servidor."},"cliente":{"type":"object","properties":{"nombre":{"type":"string","maxLength":200,"default":"Consumidor final"},"email":{"type":"string","format":"email","maxLength":255},"telefono":{"type":["string","null"],"maxLength":50}},"additionalProperties":false},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["producto_id","cantidad"],"properties":{"producto_id":{"type":"integer","minimum":1},"variante_id":{"type":["integer","null"],"minimum":1},"cantidad":{"type":"integer","minimum":1,"maximum":1000}},"additionalProperties":false}},"pago":{"type":"object","required":["estado","metodo"],"properties":{"estado":{"type":"string","enum":["pendiente","pagado"]},"metodo":{"type":"string","enum":["efectivo","tarjeta_debito","tarjeta_credito","transferencia","billetera","otro"]},"proveedor":{"type":["string","null"],"maxLength":80},"referencia_externa":{"type":["string","null"],"maxLength":300,"description":"Obligatoria para un pago confirmado que no sea en efectivo."}},"additionalProperties":false},"comportamiento_inventario":{"type":"string","enum":["descontar","omitir"],"default":"descontar"},"estado_entrega":{"type":"string","enum":["pendiente","entregada"],"default":"entregada"},"notificar_cliente":{"type":"boolean","default":false},"notificar_admin":{"type":"boolean","default":false},"notas":{"type":["string","null"],"maxLength":2000}},"additionalProperties":false},"example":{"referencia_externa":"ticket-8472","canal":"pos","items":[{"producto_id":12,"variante_id":34,"cantidad":2}],"pago":{"estado":"pagado","metodo":"efectivo"},"comportamiento_inventario":"descontar","estado_entrega":"entregada"}}}},"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","numero_orden","referencia_externa","canal","estado","pago","subtotal","total","moneda","comportamiento_inventario","items"],"properties":{"id":{"type":"integer","minimum":1},"numero_orden":{"type":"integer","minimum":1},"referencia_externa":{"type":"string"},"canal":{"const":"pos"},"estado":{"type":"string","enum":["pendiente","entregada"]},"pago":{"type":"object","required":["estado","metodo"],"properties":{"estado":{"type":"string","enum":["pendiente","pagado"]},"metodo":{"type":"string","enum":["efectivo","tarjeta_debito","tarjeta_credito","transferencia","billetera","otro"]},"proveedor":{"type":["string","null"],"maxLength":80},"referencia_externa":{"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},"moneda":{"const":"ARS"},"comportamiento_inventario":{"type":"string","enum":["descontar","omitir"]},"items":{"type":"array","items":{"type":"object","required":["producto_id","variante_id","sku","cantidad","precio_unitario","subtotal"],"properties":{"producto_id":{"type":"integer","minimum":1},"variante_id":{"type":["integer","null"],"minimum":1},"sku":{"type":["string","null"]},"cantidad":{"type":"integer","minimum":1},"precio_unitario":{"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":["codigo"],"properties":{"codigo":{"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":["codigo"],"properties":{"codigo":{"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":["codigo"],"properties":{"codigo":{"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":["codigo"],"properties":{"codigo":{"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":["codigo"],"properties":{"codigo":{"type":"string"}}}]}}}}}}},"/api/v1/ordenes/{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","numero_orden","estado","subtotal","total","moneda","items","pagos"],"properties":{"id":{"type":"integer","minimum":1},"numero_orden":{"type":"integer","minimum":1},"comprador_email":{"type":["string","null"],"format":"email"},"comprador_nombre":{"type":["string","null"]},"estado":{"type":"string","enum":["pendiente","por_empaquetar","empaquetado","listo_para_retirar","enviada","entregada","cancelada"]},"pago_estado":{"type":"string"},"subtotal":{"type":"number","minimum":0},"costo_envio":{"type":"number","minimum":0},"descuento":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"moneda":{"type":"string"},"metodo_pago":{"type":["string","null"]},"metodo_envio":{"type":["string","null"]},"id_transaccion_pago":{"type":["string","null"]},"numero_seguimiento":{"type":["string","null"]},"fuente":{"type":["string","null"]},"canal_origen":{"type":["string","null"]},"referencia_externa":{"type":["string","null"]},"ocurrio_en":{"type":["string","null"],"format":"date-time"},"direccion_envio":{"type":["object","null"],"additionalProperties":true},"notas":{"type":["string","null"]},"pagos":{"type":"array","items":{"type":"object","required":["id","estado","metodo","monto","moneda"],"properties":{"id":{"type":"integer","minimum":1},"estado":{"type":"string"},"metodo":{"type":"string"},"proveedor":{"type":["string","null"]},"monto":{"type":"number","minimum":0},"moneda":{"type":"string"},"referencia_externa":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","required":["producto_id","variante_id","nombre","sku","cantidad","precio_unitario","subtotal"],"properties":{"producto_id":{"type":"integer","minimum":1},"variante_id":{"type":["integer","null"],"minimum":1},"nombre":{"type":"string"},"sku":{"type":["string","null"]},"cantidad":{"type":"integer","minimum":1},"precio_unitario":{"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":{"estado":{"type":"string","enum":["pendiente","por_empaquetar","empaquetado","listo_para_retirar","enviada","entregada","cancelada"]},"numero_seguimiento":{"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/carritos-abandonados":{"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":"desde","in":"query","description":"Filtra por fecha de actualización desde este instante.","schema":{"type":"string","format":"date-time"}},{"name":"hasta","in":"query","description":"Filtra por fecha de actualización hasta este instante.","schema":{"type":"string","format":"date-time"}},{"name":"recuperacion_enviada","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","recuperacion_enviada"],"properties":{"id":{"type":"integer","minimum":1},"email":{"type":"string","format":"email"},"comprador_nombre":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"recuperacion_enviada":{"type":"boolean"},"recuperacion_enviada_en":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","minItems":1,"items":{"type":"object","required":["producto_id","nombre","sku","cantidad","precio_unitario"],"properties":{"producto_id":{"type":"integer","minimum":1},"nombre":{"type":"string"},"sku":{"type":["string","null"]},"cantidad":{"type":"integer","minimum":1},"precio_unitario":{"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}}}},"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","eventos","activo"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"eventos":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["orden.creada","orden.pagada","pago.reembolsado","orden.cancelada","stock.actualizado","contacto.creado","orden.preparando","orden.empaquetado","orden.lista_para_retirar","orden.enviada","orden.entregada","orden.envio_mayorista_actualizado","carrito.abandonado","devolucion.actualizada","producto.creado","producto.actualizado","variante.actualizada"]}},"activo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"ultimo_intento_en":{"type":["string","null"],"format":"date-time"},"ultimo_estado":{"type":["integer","null"]},"ultimo_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","eventos"],"properties":{"url":{"type":"string","format":"uri","description":"URL HTTP(S) pública que supera las validaciones SSRF del servidor."},"eventos":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["orden.creada","orden.pagada","pago.reembolsado","orden.cancelada","stock.actualizado","contacto.creado","orden.preparando","orden.empaquetado","orden.lista_para_retirar","orden.enviada","orden.entregada","orden.envio_mayorista_actualizado","carrito.abandonado","devolucion.actualizada","producto.creado","producto.actualizado","variante.actualizada"]},"description":"Los eventos habilitados dependen del nivel de API de la tienda."}},"additionalProperties":false},"example":{"url":"https://integracion.example.com/events","eventos":["orden.creada","stock.actualizado"]}}}},"responses":{"201":{"description":"Webhook creado. Guardar el secret inmediatamente.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["id","url","eventos","activo"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"eventos":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["orden.creada","orden.pagada","pago.reembolsado","orden.cancelada","stock.actualizado","contacto.creado","orden.preparando","orden.empaquetado","orden.lista_para_retirar","orden.enviada","orden.entregada","orden.envio_mayorista_actualizado","carrito.abandonado","devolucion.actualizada","producto.creado","producto.actualizado","variante.actualizada"]}},"activo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"ultimo_intento_en":{"type":["string","null"],"format":"date-time"},"ultimo_estado":{"type":["integer","null"]},"ultimo_error":{"type":["string","null"]}},"additionalProperties":true},{"type":"object","required":["secret","advertencia"],"properties":{"secret":{"type":"string","readOnly":true},"advertencia":{"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"},"eventos":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["orden.creada","orden.pagada","pago.reembolsado","orden.cancelada","stock.actualizado","contacto.creado","orden.preparando","orden.empaquetado","orden.lista_para_retirar","orden.enviada","orden.entregada","orden.envio_mayorista_actualizado","carrito.abandonado","devolucion.actualizada","producto.creado","producto.actualizado","variante.actualizada"]}},"activo":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Webhook actualizado.","content":{"application/json":{"schema":{"type":"object","required":["id","url","eventos","activo"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"eventos":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["orden.creada","orden.pagada","pago.reembolsado","orden.cancelada","stock.actualizado","contacto.creado","orden.preparando","orden.empaquetado","orden.lista_para_retirar","orden.enviada","orden.entregada","orden.envio_mayorista_actualizado","carrito.abandonado","devolucion.actualizada","producto.creado","producto.actualizado","variante.actualizada"]}},"activo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"ultimo_intento_en":{"type":["string","null"],"format":"date-time"},"ultimo_estado":{"type":["integer","null"]},"ultimo_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."}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token de API enviado como Authorization: Bearer <token>."}},"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":["codigo"],"properties":{"codigo":{"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","nombre","slug","precio","stock","estado","imagenes","variantes"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","maxLength":200},"sku":{"type":["string","null"],"maxLength":120},"codigo_barras":{"type":["string","null"],"maxLength":120},"descripcion_corta":{"type":["string","null"],"maxLength":500},"descripcion":{"type":["string","null"],"maxLength":20000},"precio":{"type":"number","minimum":0},"precio_oferta":{"type":["number","null"],"minimum":0},"costo":{"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"},"tipo_producto":{"type":"string"},"estado":{"type":"string","enum":["activo","inactivo","borrador"]},"activo":{"type":"boolean"},"categoria":{"oneOf":[{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},{"type":"null"}]},"imagenes":{"type":"array","items":{"type":"object","required":["id","url","alt","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"maxItems":20},"variantes":{"type":"array","items":{"type":"object","required":["id","atributos","sku","precio","stock","activa"],"properties":{"id":{"type":"integer","minimum":1},"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"costo":{"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"},"mostrar_precio":{"type":"boolean"},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_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","orden"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri","maxLength":500},"alt":{"type":["string","null"],"maxLength":300},"orden":{"type":"integer","minimum":0,"maximum":19}},"additionalProperties":false},"ProductVariant":{"type":"object","required":["id","atributos","sku","precio","stock","activa"],"properties":{"id":{"type":"integer","minimum":1},"atributos":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"minLength":1,"maxLength":60},"additionalProperties":{"type":"string","minLength":1,"maxLength":120}},"sku":{"type":["string","null"],"maxLength":100},"precio":{"type":["number","null"],"minimum":0},"precio_promo":{"type":["number","null"],"minimum":0},"costo":{"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"},"mostrar_precio":{"type":"boolean"},"codigo_barras":{"type":["string","null"],"maxLength":50},"peso":{"type":["number","null"],"minimum":0},"alto":{"type":["number","null"],"minimum":0},"ancho":{"type":["number","null"],"minimum":0},"profundidad":{"type":["number","null"],"minimum":0},"mpn":{"type":["string","null"],"maxLength":100},"activa":{"type":"boolean"},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500}},"additionalProperties":true},"Category":{"type":"object","required":["id","nombre","slug"],"properties":{"id":{"type":"integer","minimum":1},"nombre":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":200},"descripcion":{"type":["string","null"],"maxLength":20000},"imagen_url":{"type":["string","null"],"format":"uri","maxLength":500},"parent_id":{"type":["integer","null"],"minimum":1},"orden":{"type":"integer"},"visible_en_nav":{"type":"boolean"},"productos_count":{"type":"integer","minimum":0}},"additionalProperties":true},"Order":{"type":"object","required":["id","numero_orden","estado","subtotal","total","moneda","items","pagos"],"properties":{"id":{"type":"integer","minimum":1},"numero_orden":{"type":"integer","minimum":1},"comprador_email":{"type":["string","null"],"format":"email"},"comprador_nombre":{"type":["string","null"]},"estado":{"type":"string","enum":["pendiente","por_empaquetar","empaquetado","listo_para_retirar","enviada","entregada","cancelada"]},"pago_estado":{"type":"string"},"subtotal":{"type":"number","minimum":0},"costo_envio":{"type":"number","minimum":0},"descuento":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"moneda":{"type":"string"},"metodo_pago":{"type":["string","null"]},"metodo_envio":{"type":["string","null"]},"id_transaccion_pago":{"type":["string","null"]},"numero_seguimiento":{"type":["string","null"]},"fuente":{"type":["string","null"]},"canal_origen":{"type":["string","null"]},"referencia_externa":{"type":["string","null"]},"ocurrio_en":{"type":["string","null"],"format":"date-time"},"direccion_envio":{"type":["object","null"],"additionalProperties":true},"notas":{"type":["string","null"]},"pagos":{"type":"array","items":{"type":"object","required":["id","estado","metodo","monto","moneda"],"properties":{"id":{"type":"integer","minimum":1},"estado":{"type":"string"},"metodo":{"type":"string"},"proveedor":{"type":["string","null"]},"monto":{"type":"number","minimum":0},"moneda":{"type":"string"},"referencia_externa":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"items":{"type":"array","items":{"type":"object","required":["producto_id","variante_id","nombre","sku","cantidad","precio_unitario","subtotal"],"properties":{"producto_id":{"type":"integer","minimum":1},"variante_id":{"type":["integer","null"],"minimum":1},"nombre":{"type":"string"},"sku":{"type":["string","null"]},"cantidad":{"type":"integer","minimum":1},"precio_unitario":{"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},"Webhook":{"type":"object","required":["id","url","eventos","activo"],"properties":{"id":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"eventos":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["orden.creada","orden.pagada","pago.reembolsado","orden.cancelada","stock.actualizado","contacto.creado","orden.preparando","orden.empaquetado","orden.lista_para_retirar","orden.enviada","orden.entregada","orden.envio_mayorista_actualizado","carrito.abandonado","devolucion.actualizada","producto.creado","producto.actualizado","variante.actualizada"]}},"activo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"ultimo_intento_en":{"type":["string","null"],"format":"date-time"},"ultimo_estado":{"type":["integer","null"]},"ultimo_error":{"type":["string","null"]}},"additionalProperties":true}},"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}}}}}