{ "openapi": "3.1.0", "info": { "title": "RM Ecommerce API", "version": "1.0.0", "summary": "API REST v1 para conectores, ERP e integraciones.", "description": "API REST de la plataforma de ecommerce multi-tenant RM. Cada llave de API pertenece a una tienda y solo ve sus datos.\n\n- **Autenticación:** `Authorization: Bearer rk__`. La sesión del back office no sirve.\n- **Permisos:** por área (`products`, `inventory`, `prices`, `customers`, `orders`, `integrations`); `GET` pide `read_<área>`, lo demás `write_<área>` (ADR 0007).\n- **Paginación por cursor** (ADR 0008): `?limit=` (1 a 500) y la URL `next` tal cual; no hay `offset` ni `count`.\n- **Límite:** 600 peticiones por minuto por llave; `429` con `Retry-After`.\n- **Decimales** como texto; **IDs públicos** UUID para lo que no tiene código.\n- Webhooks salientes (`order.*`, `inventory.changed`): ver la sección `webhooks` y `docs/api.md`.\n\nReglas de negocio con todo detalle: `docs/api.md`.", "license": { "name": "Propietaria" } }, "servers": [ { "url": "{base_url}", "description": "Base de la API (incluye `/api/v1`).", "variables": { "base_url": { "default": "https://retail-s.online/api/v1", "description": "VPS: `https://retail-s.online/api/v1`. Local: `http://127.0.0.1:8000/api/v1`." } } } ], "tags": [ { "name": "Conexión", "description": "Probar la llave y ver sus permisos." }, { "name": "Catálogo", "description": "Productos, variantes, imágenes, categorías, marcas, colecciones, atributos, plantillas, modificadores y traducciones. Permiso `products`." }, { "name": "Catálogo masivo", "description": "Alta masiva e importación NDJSON de productos. Permiso `products`." }, { "name": "Inventario", "description": "Existencias y ubicaciones. Permiso `inventory`." }, { "name": "Precios", "description": "Precios y listas de precios. Permiso `prices`." }, { "name": "Clientes", "description": "Clientes y grupos de clientes. Permiso `customers`." }, { "name": "Pedidos", "description": "Pedidos, cambios de estado, pagos, devoluciones, reembolsos, paqueterías y medios de pago. Permiso `orders`." }, { "name": "Integraciones", "description": "Conexiones, corridas de sincronización y referencias externas. Permiso `integrations`." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/": { "get": { "tags": [ "Conexión" ], "summary": "Probar conexión", "security": [ { "bearerAuth": [] } ], "description": "Devuelve la tienda, el nombre de la llave y sus permisos. Sirve cualquier llave válida, sin importar sus scopes.", "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Root" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_root", "x-postman-name": "Probar conexión" } }, "/categories/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar categories", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_categories" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear la categoría", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "example": { "code": "EJEMPLO", "name": "Playeras", "parent": "ROPA", "is_active": true } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_categories" } }, "/categories/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener la categoría", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la categoría (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_categories_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar la categoría (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la categoría (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "example": { "name": "Playeras", "parent": "ROPA", "is_active": true } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_categories_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de la categoría", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la categoría (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "example": { "name": "Playeras" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_categories_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar la categoría", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la categoría (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_categories_code" } }, "/variant-templates/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar variant-templates", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_VariantTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variant_templates" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear la plantilla de variantes", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" }, "example": { "code": "EJEMPLO", "name": "Ropa", "options": [ { "name": "Talla", "values": [ "CH", "M", "G" ] } ] } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_variant_templates" } }, "/variant-templates/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener la plantilla de variantes", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la plantilla de variantes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variant_templates_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar la plantilla de variantes (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la plantilla de variantes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" }, "example": { "name": "Ropa", "options": [ { "name": "Talla", "values": [ "CH", "M", "G" ] } ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_variant_templates_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de la plantilla de variantes", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la plantilla de variantes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" }, "example": { "name": "Ropa" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_variant_templates_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar la plantilla de variantes", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la plantilla de variantes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_variant_templates_code" } }, "/brands/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar brands", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Brand" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_brands" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear la marca", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" }, "example": { "code": "EJEMPLO", "name": "Marca Ejemplo", "is_active": true } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_brands" } }, "/brands/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener la marca", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la marca (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_brands_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar la marca (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la marca (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" }, "example": { "name": "Marca Ejemplo", "is_active": true } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_brands_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de la marca", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la marca (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" }, "example": { "name": "Marca Ejemplo" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_brands_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar la marca", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la marca (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_brands_code" } }, "/collections/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar collections", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_collections" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear la colección", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "code": "EJEMPLO", "name": "Novedades", "is_active": true, "featured": false, "products": [ "PLY-001" ] } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_collections" } }, "/collections/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener la colección", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la colección (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_collections_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar la colección (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la colección (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "name": "Novedades", "is_active": true, "featured": false, "products": [ "PLY-001" ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_collections_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de la colección", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la colección (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "name": "Novedades" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_collections_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar la colección", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la colección (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_collections_code" } }, "/modifier-groups/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar modifier-groups", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ModifierGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_modifier_groups" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear el grupo de modificadores", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" }, "example": { "code": "EJEMPLO", "name": "Extras", "min_select": 0, "max_select": 2, "modifiers": [ { "code": "QUESO", "name": "Queso", "price": "0.75" }, { "code": "TOCINO", "name": "Tocino", "price": "1.25" } ] } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_modifier_groups" } }, "/modifier-groups/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener el grupo de modificadores", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de modificadores (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_modifier_groups_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar el grupo de modificadores (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de modificadores (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" }, "example": { "name": "Extras", "min_select": 0, "max_select": 2, "modifiers": [ { "code": "QUESO", "name": "Queso", "price": "0.75" }, { "code": "TOCINO", "name": "Tocino", "price": "1.25" } ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_modifier_groups_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de el grupo de modificadores", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de modificadores (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" }, "example": { "name": "Extras" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifierGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_modifier_groups_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar el grupo de modificadores", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de modificadores (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_modifier_groups_code" } }, "/attributes/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar attributes", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Attribute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_attributes" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear el atributo", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" }, "example": { "code": "EJEMPLO", "name": "Material", "type": "option", "scope": "product", "options": [ "Algodón", "Poliéster" ], "is_filterable": true } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_attributes" } }, "/attributes/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener el atributo", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el atributo (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_attributes_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar el atributo (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el atributo (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" }, "example": { "name": "Material", "type": "option", "scope": "product", "options": [ "Algodón", "Poliéster" ], "is_filterable": true } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_attributes_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de el atributo", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el atributo (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" }, "example": { "name": "Material" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_attributes_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar el atributo", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el atributo (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_attributes_code" } }, "/locations/": { "get": { "tags": [ "Inventario" ], "summary": "Listar locations", "x-required-scope": "read_inventory", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_inventory`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Location" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_locations" }, "post": { "tags": [ "Inventario" ], "summary": "Crear la ubicación", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_inventory`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "code": "EJEMPLO", "name": "Centro de distribución", "kind": "warehouse", "allows_pickup": false, "ships_orders": true, "hours": [ { "weekday": 0, "opens": "09:00", "closes": "18:00" } ] } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_locations" } }, "/locations/{code}/": { "get": { "tags": [ "Inventario" ], "summary": "Obtener la ubicación", "x-required-scope": "read_inventory", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la ubicación (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_locations_code" }, "put": { "tags": [ "Inventario" ], "summary": "Crear o reemplazar la ubicación (upsert)", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la ubicación (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "name": "Centro de distribución", "kind": "warehouse", "allows_pickup": false, "ships_orders": true, "hours": [ { "weekday": 0, "opens": "09:00", "closes": "18:00" } ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_locations_code" }, "patch": { "tags": [ "Inventario" ], "summary": "Actualizar campos de la ubicación", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la ubicación (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "name": "Centro de distribución" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_locations_code" }, "delete": { "tags": [ "Inventario" ], "summary": "Eliminar la ubicación", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_inventory`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la ubicación (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_locations_code" } }, "/price-lists/": { "get": { "tags": [ "Precios" ], "summary": "Listar price-lists", "x-required-scope": "read_prices", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_prices`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PriceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_price_lists" }, "post": { "tags": [ "Precios" ], "summary": "Crear la lista de precios", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_prices`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" }, "example": { "code": "EJEMPLO", "name": "Mayoreo", "currency": "USD", "prices_include_tax": false, "priority": 10, "customer_groups": [ "MAYORISTAS" ] } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_price_lists" } }, "/price-lists/{code}/": { "get": { "tags": [ "Precios" ], "summary": "Obtener la lista de precios", "x-required-scope": "read_prices", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la lista de precios (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_price_lists_code" }, "put": { "tags": [ "Precios" ], "summary": "Crear o reemplazar la lista de precios (upsert)", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la lista de precios (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" }, "example": { "name": "Mayoreo", "currency": "USD", "prices_include_tax": false, "priority": 10, "customer_groups": [ "MAYORISTAS" ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_price_lists_code" }, "patch": { "tags": [ "Precios" ], "summary": "Actualizar campos de la lista de precios", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la lista de precios (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" }, "example": { "name": "Mayoreo" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_price_lists_code" }, "delete": { "tags": [ "Precios" ], "summary": "Eliminar la lista de precios", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_prices`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la lista de precios (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_price_lists_code" } }, "/customer-groups/": { "get": { "tags": [ "Clientes" ], "summary": "Listar customer-groups", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_customers`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CustomerGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customer_groups" }, "post": { "tags": [ "Clientes" ], "summary": "Crear el grupo de clientes", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "El cuerpo lleva `code`. `409`/`400` si el código ya existe. Permiso: `write_customers`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" }, "example": { "code": "EJEMPLO", "name": "Mayoristas", "description": "Compra por caja" } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_customer_groups" } }, "/customer-groups/{code}/": { "get": { "tags": [ "Clientes" ], "summary": "Obtener el grupo de clientes", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de clientes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customer_groups_code" }, "put": { "tags": [ "Clientes" ], "summary": "Crear o reemplazar el grupo de clientes (upsert)", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "`201` si lo crea, `200` si lo reemplaza. El código de la ruta manda sobre el del cuerpo. Permiso: `write_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de clientes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" }, "example": { "name": "Mayoristas", "description": "Compra por caja" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_customer_groups_code" }, "patch": { "tags": [ "Clientes" ], "summary": "Actualizar campos de el grupo de clientes", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Solo los campos enviados; `404` si no existe. Permiso: `write_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de clientes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" }, "example": { "name": "Mayoristas" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_customer_groups_code" }, "delete": { "tags": [ "Clientes" ], "summary": "Eliminar el grupo de clientes", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "`400` si otros registros dependen de este. Permiso: `write_customers`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el grupo de clientes (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_customer_groups_code" } }, "/products/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar productos", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Estado.", "schema": { "type": "string", "enum": [ "draft", "active", "archived" ] } }, { "name": "category", "in": "query", "description": "Código de categoría.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Texto en nombre, código o SKU.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products" }, "post": { "tags": [ "Catálogo" ], "summary": "Crear producto", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "code": "PLY-001", "name": "Playera básica", "status": "active", "category": "PLAYERAS", "short_description": "Algodón 100 %", "base_unit": "PZA", "tax_exempt": false, "track_inventory": true, "options": [ { "name": "Color", "values": [ "Negro", "Blanco" ] }, { "name": "Talla", "values": [ "CH", "M", "G" ] } ], "variants": [ { "code": "NEGRO-CH", "sku": "PLY-001-N-CH", "barcode": "7501234567890" } ], "attributes": { "MATERIAL": "Algodón" } } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products" } }, "/products/{code}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener producto", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Incluye variantes con sus opciones, existencias por ubicación y precios, imágenes y atributos. Permiso: `read_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_code" }, "put": { "tags": [ "Catálogo" ], "summary": "Crear o reemplazar producto (upsert)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`201`/`200`. `options` y `attributes` son declarativos; se aplica completo o nada. Ver `variants_mode: exact` en `docs/api.md`. Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "name": "Playera básica", "status": "active", "category": "PLAYERAS", "short_description": "Algodón 100 %", "base_unit": "PZA", "tax_exempt": false, "track_inventory": true, "options": [ { "name": "Color", "values": [ "Negro", "Blanco" ] }, { "name": "Talla", "values": [ "CH", "M", "G" ] } ], "variants": [ { "code": "NEGRO-CH", "sku": "PLY-001-N-CH", "barcode": "7501234567890" } ], "attributes": { "MATERIAL": "Algodón" } } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_products_code" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar campos de un producto", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "status": "archived" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_products_code" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar producto", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_products_code" } }, "/products/{code}/duplicate/": { "post": { "tags": [ "Catálogo" ], "summary": "Duplicar producto", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateInput" }, "example": { "code": "PLY-001-COPIA", "name": "Playera básica (copia)", "copy_images": true, "copy_prices": true } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_code_duplicate" } }, "/products/{code}/images/": { "post": { "tags": [ "Catálogo" ], "summary": "Agregar o reemplazar imagen", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`multipart/form-data` con `image`, o JSON con `url` (https, sin descargarla). Con `external_key` repetida reemplaza la imagen (`200`). Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUrl" }, "example": { "url": "https://cdn.ejemplo.com/playera.jpg", "external_key": "LS-1", "alt_text": "Playera negra de frente", "variant_skus": [ "PLY-001-N-CH" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageUpload" } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductImage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_code_images" }, "delete": { "tags": [ "Catálogo" ], "summary": "Borrar imagen por clave externa", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } }, { "name": "external_key", "in": "query", "description": "Clave externa de la imagen.", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "Borrada.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_products_code_images" } }, "/products/{code}/images/{image_id}/": { "delete": { "tags": [ "Catálogo" ], "summary": "Borrar imagen por id", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_products`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el producto (se guarda en mayúsculas).", "schema": { "type": "string" } }, { "name": "image_id", "in": "path", "required": true, "description": "`id` (UUID) de la imagen.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Borrada.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_products_code_images_image_id" } }, "/variants/": { "get": { "tags": [ "Catálogo" ], "summary": "Listar variantes", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "product", "in": "query", "description": "Código de producto.", "schema": { "type": "string" } }, { "name": "barcode", "in": "query", "description": "Código de barras exacto.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Variant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variants" } }, "/variants/{sku}/": { "get": { "tags": [ "Catálogo" ], "summary": "Obtener variante", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "SKU de la variante.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_variants_sku" }, "patch": { "tags": [ "Catálogo" ], "summary": "Actualizar variante", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Solo `sku`, `barcode`, `weight`, `is_active` y `attributes`; las combinaciones salen de las opciones del producto. Permiso: `write_products`.", "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "SKU de la variante.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" }, "example": { "barcode": "7501234567890", "is_active": true } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_variants_sku" }, "delete": { "tags": [ "Catálogo" ], "summary": "Eliminar variante", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`409` si tiene pedidos (desactívala con `is_active: false`) o si es la única del producto. Permiso: `write_products`.", "parameters": [ { "name": "sku", "in": "path", "required": true, "description": "SKU de la variante.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminada.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_variants_sku" } }, "/translations/": { "get": { "tags": [ "Catálogo" ], "summary": "Consultar traducciones", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "object_type", "in": "query", "description": "Tipo.", "schema": { "type": "string", "enum": [ "product", "category", "collection", "brand", "attribute" ] }, "required": true }, { "name": "object_key", "in": "query", "description": "Código del registro.", "schema": { "type": "string" }, "required": true }, { "name": "language", "in": "query", "description": "Idioma, p. ej. `en`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_translations" }, "put": { "tags": [ "Catálogo" ], "summary": "Guardar traducciones", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "El idioma debe estar activo como extra en la tienda. Un valor vacío borra la traducción. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationInput" }, "example": { "object_type": "product", "object_key": "PLY-001", "language": "en", "fields": { "name": "Basic T-shirt" } } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_translations" } }, "/products/bulk/": { "post": { "tags": [ "Catálogo masivo" ], "summary": "Alta masiva de productos (hasta 500)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "Upsert por código, procesado por el worker. Un producto malo no tumba a los demás. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsBulkInput" }, "example": { "items": [ { "code": "PLY-001", "name": "Playera básica" }, { "code": "PLY-002", "name": "Playera estampada" } ] } } } }, "responses": { "202": { "description": "Trabajo encolado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_bulk" } }, "/products/bulk/{id}/": { "get": { "tags": [ "Catálogo masivo" ], "summary": "Estado y resultado de una alta masiva", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el trabajo.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RowStatus" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_bulk_id" } }, "/products/import/": { "post": { "tags": [ "Catálogo masivo" ], "summary": "Importar catálogo NDJSON (solo crea)", "x-required-scope": "write_products", "security": [ { "bearerAuth": [] } ], "description": "`multipart/form-data` con `file` (NDJSON, hasta 256 MB). Pensado para primeras cargas de decenas o cientos de miles de productos. Permiso: `write_products`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImportUpload" } } } }, "responses": { "202": { "description": "Trabajo encolado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_products_import" } }, "/products/import/{id}/": { "get": { "tags": [ "Catálogo masivo" ], "summary": "Estado de una importación", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_products`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de la importación.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RowStatus" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_import_id" } }, "/products/import/{id}/rows/": { "get": { "tags": [ "Catálogo masivo" ], "summary": "Resultado completo de una importación (NDJSON)", "x-required-scope": "read_products", "security": [ { "bearerAuth": [] } ], "description": "Una fila por línea (`application/x-ndjson`), en orden y sin paginar. Permiso: `read_products`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de la importación.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RowStatus" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "Un objeto JSON por línea." } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_products_import_id_rows" } }, "/inventory/": { "get": { "tags": [ "Inventario" ], "summary": "Consultar existencias", "x-required-scope": "read_inventory", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_inventory`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "sku", "in": "query", "description": "SKU.", "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Código de ubicación.", "schema": { "type": "string" } }, { "name": "product", "in": "query", "description": "Código de producto.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_InventoryRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_inventory" } }, "/inventory/bulk/": { "post": { "tags": [ "Inventario" ], "summary": "Fijar existencias en bloque (absolutas)", "x-required-scope": "write_inventory", "security": [ { "bearerAuth": [] } ], "description": "`on_hand` es la existencia absoluta del ERP, no un ajuste. Hasta 1000 filas. Todo o nada, salvo `partial=true`. Permiso: `write_inventory`.", "parameters": [ { "$ref": "#/components/parameters/Partial" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryBulkInput" }, "example": { "items": [ { "sku": "PLY-001-N-CH", "location": "CEDIS", "on_hand": "12" }, { "sku": "PLY-001-N-CH", "location": "TDA-CENTRO", "on_hand": "3", "reference": "ERP 2026-10-14" } ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_inventory_bulk" } }, "/prices/": { "get": { "tags": [ "Precios" ], "summary": "Consultar precios", "x-required-scope": "read_prices", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_prices`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "price_list", "in": "query", "description": "Código de lista.", "schema": { "type": "string" } }, { "name": "sku", "in": "query", "description": "SKU.", "schema": { "type": "string" } }, { "name": "product", "in": "query", "description": "Código de producto.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PriceRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_prices" } }, "/prices/bulk/": { "post": { "tags": [ "Precios" ], "summary": "Fijar precios en bloque", "x-required-scope": "write_prices", "security": [ { "bearerAuth": [] } ], "description": "Hasta 1000 filas; `price: null` borra la línea. Todo o nada, salvo `partial=true`. Permiso: `write_prices`.", "parameters": [ { "$ref": "#/components/parameters/Partial" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesBulkInput" }, "example": { "items": [ { "price_list": "GENERAL", "sku": "PLY-001-N-CH", "price": "249.00", "compare_at_price": "299.00" }, { "price_list": "GENERAL", "sku": "PLY-001-N-CH", "price": "220.00", "min_quantity": "6" }, { "price_list": "MAYOREO", "sku": "PLY-001-N-M", "price": null } ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_prices_bulk" } }, "/customers/": { "get": { "tags": [ "Clientes" ], "summary": "Listar clientes", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_customers`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "q", "in": "query", "description": "Texto en nombre, apellido, correo o empresa.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Correo exacto.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "Código del cliente.", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "Código de grupo.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customers" }, "post": { "tags": [ "Clientes" ], "summary": "Crear cliente", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_customers`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "code": "C-100", "first_name": "Carlos", "last_name": "Hernández", "company": "Uniformes del Bajío", "email": "compras@ejemplo.com", "phone": "477 555 0101", "group": "MAYORISTAS", "accepts_marketing": false, "addresses": [ { "label": "Matriz", "line1": "Blvd. López Mateos 3401", "city": "León", "state": "Guanajuato", "postal_code": "37160", "country": "MX" } ] } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_customers" } }, "/customers/{id}/": { "get": { "tags": [ "Clientes" ], "summary": "Obtener cliente", "x-required-scope": "read_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el cliente.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_customers_id" }, "put": { "tags": [ "Clientes" ], "summary": "Reemplazar cliente", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "`addresses` es declarativo: si lo envías reemplaza todas las direcciones. Permiso: `write_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el cliente.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "code": "C-100", "first_name": "Carlos", "last_name": "Hernández", "company": "Uniformes del Bajío", "email": "compras@ejemplo.com", "phone": "477 555 0101", "group": "MAYORISTAS", "accepts_marketing": false, "addresses": [ { "label": "Matriz", "line1": "Blvd. López Mateos 3401", "city": "León", "state": "Guanajuato", "postal_code": "37160", "country": "MX" } ] } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "put_customers_id" }, "patch": { "tags": [ "Clientes" ], "summary": "Actualizar campos de un cliente", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el cliente.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "phone": "477 555 0102" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "patch_customers_id" }, "delete": { "tags": [ "Clientes" ], "summary": "Eliminar cliente", "x-required-scope": "write_customers", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_customers`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el cliente.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Eliminado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_customers_id" } }, "/orders/": { "get": { "tags": [ "Pedidos" ], "summary": "Listar pedidos", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Orden de alta (no por número). Para el pull del ERP usa `updated_since` o `placed_since`. Permiso: `read_orders`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "number", "in": "query", "description": "Número que ve la tienda (`1001` o `#1001`).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Estado.", "schema": { "type": "string", "enum": [ "open", "cancelled", "archived" ] } }, { "name": "payment_status", "in": "query", "description": "Estado de pago.", "schema": { "type": "string", "enum": [ "pending", "authorized", "paid", "partially_refunded", "refunded", "failed" ] } }, { "name": "fulfillment_status", "in": "query", "description": "Estado de surtido.", "schema": { "type": "string", "enum": [ "unfulfilled", "prepared", "ready_for_pickup", "shipped", "delivered" ] } }, { "name": "delivery_type", "in": "query", "description": "Tipo de entrega.", "schema": { "type": "string", "enum": [ "shipping", "pickup", "takeout", "dine_in", "delivery_app" ] } }, { "name": "customer", "in": "query", "description": "`id` (UUID) del cliente.", "schema": { "type": "string", "format": "uuid" } }, { "name": "placed_since", "in": "query", "description": "Pedidos hechos desde esta fecha (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_orders" }, "post": { "tags": [ "Pedidos" ], "summary": "Crear pedido", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "`201` la primera vez; con `Idempotency-Key` repetida y los mismos datos, `200` con el mismo pedido. Rechaza (400) sin existencia o sin precio. Permiso: `write_orders`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "example": { "customer_email": "compras@ejemplo.com", "lines": [ { "sku": "PLY-001-N-CH", "quantity": "6" }, { "sku": "COC-002", "quantity": "1", "unit_price": "14.50" } ], "shipping_address": { "line1": "Blvd. Los Próceres 12", "city": "Antiguo Cuscatlán", "state": "La Libertad", "country": "SV" }, "location": "CEDIS", "discount": "0", "shipping": "8.00", "notes": "" } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders" } }, "/orders/{id}/": { "get": { "tags": [ "Pedidos" ], "summary": "Obtener pedido", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_orders_id" } }, "/orders/{id}/pay/": { "post": { "tags": [ "Pedidos" ], "summary": "Registrar pago", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Con `Idempotency-Key` responde `200` siempre y no registra otro pago. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayInput" }, "example": { "method": "transfer", "reference": "T-123" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_pay" } }, "/orders/{id}/prepare/": { "post": { "tags": [ "Pedidos" ], "summary": "Marcar como preparado / aceptado por el ERP", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Deja el sello informativo `erp_accepted_at`; no libera ni descuenta existencia. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_prepare" } }, "/orders/{id}/ship/": { "post": { "tags": [ "Pedidos" ], "summary": "Marcar como enviado (descuenta existencia)", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Con `carrier_code` calcula `tracking_url`; con `carrier` (texto) busca primero entre las paqueterías de la tienda. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipInput" }, "example": { "carrier_code": "C807", "tracking_number": "ABC123" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_ship" } }, "/orders/{id}/ready/": { "post": { "tags": [ "Pedidos" ], "summary": "Marcar listo para recoger (descuenta existencia)", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Pedidos `pickup`. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_ready" } }, "/orders/{id}/deliver/": { "post": { "tags": [ "Pedidos" ], "summary": "Marcar como entregado", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Desde `shipped` o `ready_for_pickup`. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_deliver" } }, "/orders/{id}/cancel/": { "post": { "tags": [ "Pedidos" ], "summary": "Cancelar pedido", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Libera lo apartado; reembolsa por el pago si ya estaba cobrado. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInput" }, "example": { "reason": "El cliente lo pidió" } } } }, "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_cancel" } }, "/orders/{id}/archive/": { "post": { "tags": [ "Pedidos" ], "summary": "Archivar pedido", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Solo cancelados, entregados o reembolsados. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_archive" } }, "/orders/{id}/unarchive/": { "post": { "tags": [ "Pedidos" ], "summary": "Desarchivar pedido", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Responde con el pedido completo, o `409` si el paso no aplica. Lo regresa a como estaba. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_unarchive" } }, "/orders/{id}/returns/": { "post": { "tags": [ "Pedidos" ], "summary": "Registrar devolución", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "`201` y luego `200` al repetir con la misma `Idempotency-Key`. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnInput" }, "example": { "lines": [ { "line_id": "0192f3a4-6b1c-7d2e-9f00-1a2b3c4d5e6f", "quantity": "1" } ], "reason": "Talla", "restock": true } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_returns" } }, "/orders/{id}/refunds/": { "post": { "tags": [ "Pedidos" ], "summary": "Reembolsar un pago", "x-required-scope": "write_orders", "security": [ { "bearerAuth": [] } ], "description": "Síncrono: con pasarela se pide en la misma llamada y, si falla, `409` sin rastro. `200` al repetir con la misma llave. Permiso: `write_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" }, "example": { "amount": "25.00", "reason": "Producto dañado" } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_orders_id_refunds" } }, "/orders/{id}/payments/": { "get": { "tags": [ "Pedidos" ], "summary": "Listar pagos del pedido", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Solo lectura; cada pago trae sus `refunds`. Permiso: `read_orders`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de el pedido.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_orders_id_payments" } }, "/carriers/": { "get": { "tags": [ "Pedidos" ], "summary": "Listar paqueterías", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Solo lectura. Incluye las desactivadas. Permiso: `read_orders`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Carrier" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_carriers" } }, "/carriers/{code}/": { "get": { "tags": [ "Pedidos" ], "summary": "Obtener paquetería", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_orders`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de la paquetería (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Carrier" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_carriers_code" } }, "/payment-methods/": { "get": { "tags": [ "Pedidos" ], "summary": "Listar medios de pago", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Solo lectura. Incluye los desactivados. Permiso: `read_orders`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PaymentMethod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_payment_methods" } }, "/payment-methods/{code}/": { "get": { "tags": [ "Pedidos" ], "summary": "Obtener medio de pago", "x-required-scope": "read_orders", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_orders`.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Código de el medio de pago (se guarda en mayúsculas).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_payment_methods_code" } }, "/connections/": { "get": { "tags": [ "Integraciones" ], "summary": "Listar conexiones", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Solo lectura; las conexiones se crean en el back office. Permiso: `read_integrations`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Connection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_connections" } }, "/connections/{id}/": { "get": { "tags": [ "Integraciones" ], "summary": "Obtener conexión", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de la conexión.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_connections_id" } }, "/connections/{id}/sync-runs/": { "get": { "tags": [ "Integraciones" ], "summary": "Listar corridas de sincronización", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de la conexión.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "kind", "in": "query", "description": "Tipo de corrida (`products`, `inventory`…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SyncRun" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_connections_id_sync_runs" }, "post": { "tags": [ "Integraciones" ], "summary": "Reportar una corrida de sincronización", "x-required-scope": "write_integrations", "security": [ { "bearerAuth": [] } ], "description": "Actualiza `last_sync_at` de la conexión a `finished_at` (nunca lo retrocede; una corrida `failed` no lo mueve). Permiso: `write_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de la conexión.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRunInput" }, "example": { "kind": "inventory", "started_at": "2026-10-17T10:00:00Z", "finished_at": "2026-10-17T10:05:00Z", "records": 1200, "errors": 3, "message": "3 SKU sin variante" } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_connections_id_sync_runs" } }, "/external-references/": { "get": { "tags": [ "Integraciones" ], "summary": "Buscar referencias externas", "x-required-scope": "read_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `read_integrations`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "connection", "in": "query", "description": "`id` (UUID) de la conexión.", "schema": { "type": "string", "format": "uuid" } }, { "name": "object_type", "in": "query", "description": "Tipo de objeto local.", "schema": { "type": "string" } }, { "name": "object_key", "in": "query", "description": "Código (o SKU, o número) del objeto; requiere `object_type`.", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "description": "ID en el sistema externo.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExternalReference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "get_external_references" }, "post": { "tags": [ "Integraciones" ], "summary": "Guardar referencia externa (upsert)", "x-required-scope": "write_integrations", "security": [ { "bearerAuth": [] } ], "description": "Upsert por (conexión, registro local): `201` si crea, `200` si actualiza. Un `external_id` no puede ligarse a dos registros. Permiso: `write_integrations`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceInput" }, "example": { "connection": "0192f3a4-6b1c-7d2e-9f00-1a2b3c4d5e6f", "object_type": "product", "object_key": "PLY-001", "external_id": "5c2e0000-0000-0000-0000-000000000000", "external_code": "1000" } } } }, "responses": { "201": { "description": "Correcto.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "post_external_references" } }, "/external-references/{id}/": { "delete": { "tags": [ "Integraciones" ], "summary": "Borrar referencia externa", "x-required-scope": "write_integrations", "security": [ { "bearerAuth": [] } ], "description": "Permiso: `write_integrations`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "`id` público (UUID) de la referencia.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Borrada.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "delete_external_references_id" } } }, "webhooks": { "rmEvent": { "post": { "summary": "Evento de la tienda hacia tu sistema", "description": "Lo manda la app Webhooks de la tienda a la URL `https` configurada. Cabeceras: `X-RM-Event`, `X-RM-Event-Id` (= `id`), `X-RM-Signature` (HMAC-SHA256 hexadecimal del cuerpo exacto con el secreto de la app) y `User-Agent: RM-Webhooks/1`. Responde `2xx` para confirmar; con `5xx`, `429`, `408` o error de red se reintenta (hasta 8 veces en ~2 h, mismo cuerpo, `id` y firma). Al menos una vez y sin orden garantizado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "6f1c0000-0000-0000-0000-000000000000", "event": "order.created", "store": "mia", "occurred_at": "2026-10-15T20:31:02+00:00", "data": { "number": 1001, "payment_status": "pending" } } } } }, "responses": { "200": { "description": "Recibido." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "rk__", "description": "Llave de API de la tienda (Configuración → Llaves de API)." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "Tamaño de página (1 a 500, por omisión 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Cursor opaco; usa la URL de `next` tal cual.", "schema": { "type": "string" } }, "UpdatedSince": { "name": "updated_since", "in": "query", "description": "Solo registros modificados desde esta fecha (ISO 8601).", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-14T00:00:00Z" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Reintentos seguros (hasta 100 caracteres, sin control). Misma llave y mismos datos: no se repite la operación; otros datos: `409`.", "schema": { "type": "string", "maxLength": 100 } }, "Partial": { "name": "partial", "in": "query", "description": "`true`: aplica las filas válidas y reporta las demás (también `\"partial\": true` en el cuerpo).", "schema": { "type": "boolean", "default": false } }, "RowStatus": { "name": "status", "in": "query", "description": "`error` deja solo las filas con error.", "schema": { "type": "string", "enum": [ "error" ] } }, "Offset": { "name": "offset", "in": "query", "description": "Primera fila del resultado (las filas de un trabajo se paginan así, no por cursor).", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "headers": { "RateLimitLimit": { "description": "Peticiones permitidas por minuto (por llave).", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Peticiones que quedan en la ventana actual.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Segundo (epoch Unix) en que se libera el cupo más antiguo.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Segundos que faltan para poder reintentar.", "schema": { "type": "integer" } } }, "responses": { "Unauthorized": { "description": "Sin llave, llave inválida o desactivada. Sin cabeceras `X-RateLimit-*`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "La llave no tiene el permiso del área (`read_<área>` o `write_<área>`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No existe en la tienda de la llave (también si es de otra tienda).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Validación: detalle por campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Conflict": { "description": "El paso no aplica al estado actual, o la `Idempotency-Key` se usó con otros datos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Presupuesto de la llave agotado. Espera `Retry-After` segundos.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "detail": { "type": "string" } }, "description": "Error de autenticación, permiso o regla de negocio." }, "ValidationError": { "type": "object", "properties": {}, "description": "Error de validación (`400`): campo -> lista de mensajes (o mensaje). Las operaciones masivas usan `errors` por índice.", "additionalProperties": true }, "Root": { "type": "object", "properties": { "api_version": { "type": "string" }, "tenant": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "default_currency": { "type": "string" }, "prices_include_tax": { "type": "boolean" } } }, "api_key": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permisos de la llave: `read_<área>` y `write_<área>` (`products`, `inventory`, `prices`, `customers`, `orders`, `integrations`)." } } }, "Page_Category": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } }, "required": [ "next", "results" ] }, "Page_Brand": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } } }, "required": [ "next", "results" ] }, "Page_Collection": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } }, "required": [ "next", "results" ] }, "Page_Attribute": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } }, "required": [ "next", "results" ] }, "Page_Location": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } }, "required": [ "next", "results" ] }, "Page_PriceList": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PriceList" } } }, "required": [ "next", "results" ] }, "Page_CustomerGroup": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerGroup" } } }, "required": [ "next", "results" ] }, "Page_VariantTemplate": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VariantTemplate" } } }, "required": [ "next", "results" ] }, "Page_ModifierGroup": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ModifierGroup" } } }, "required": [ "next", "results" ] }, "Page_Customer": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } }, "required": [ "next", "results" ] }, "Page_ProductRead": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRead" } } }, "required": [ "next", "results" ] }, "Page_Variant": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } } }, "required": [ "next", "results" ] }, "Page_Order": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } }, "required": [ "next", "results" ] }, "Page_Carrier": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Carrier" } } }, "required": [ "next", "results" ] }, "Page_PaymentMethod": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } }, "required": [ "next", "results" ] }, "Page_Connection": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } }, "required": [ "next", "results" ] }, "Page_SyncRun": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRun" } } }, "required": [ "next", "results" ] }, "Page_ExternalReference": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } }, "required": [ "next", "results" ] }, "Page_PriceRow": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PriceRow" } } }, "required": [ "next", "results" ] }, "Page_InventoryRow": { "type": "object", "description": "Página de resultados por cursor. `next` es la URL de la página siguiente (se pide tal cual) o `null` en la última.", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryRow" } } }, "required": [ "next", "results" ] }, "Category": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "position": { "type": "integer" }, "is_active": { "type": "boolean" }, "attributes": { "type": "array", "items": { "type": "string" }, "description": "Códigos de atributos." }, "variant_template": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "code", "name" ] }, "Brand": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "logo": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Collection": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "image": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "featured": { "type": "boolean" }, "position": { "type": "integer" }, "products": { "type": "array", "items": { "type": "string" }, "description": "Códigos de producto; declarativo." }, "is_automatic": { "type": "boolean", "readOnly": true }, "rules": { "readOnly": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Attribute": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "integer", "decimal", "date", "boolean", "option" ] }, "scope": { "type": "string", "enum": [ "product", "variant" ] }, "unit": { "type": "string" }, "is_filterable": { "type": "boolean" }, "position": { "type": "integer" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Declarativo: solo para `type` `option`." }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "LocationHours": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 = lunes … 6 = domingo." }, "opens": { "type": "string" }, "closes": { "type": "string" } }, "required": [ "weekday", "opens", "closes" ], "description": "Rango horario `HH:MM`; si `closes` < `opens` cruza la medianoche." }, "Location": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "store", "warehouse" ] }, "address": { "type": "string" }, "allows_pickup": { "type": "boolean" }, "ships_orders": { "type": "boolean" }, "fulfills_online_orders": { "type": "boolean" }, "is_active": { "type": "boolean" }, "position": { "type": "integer" }, "hours": { "type": "array", "items": { "$ref": "#/components/schemas/LocationHours" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "PriceList": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "prices_include_tax": { "type": "boolean" }, "starts_on": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "ends_on": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "is_default": { "type": "boolean" }, "priority": { "type": "integer" }, "is_active": { "type": "boolean" }, "customer_groups": { "type": "array", "items": { "type": "string" }, "description": "Códigos de grupo; vacío = todos." }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "CustomerGroup": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "VariantTemplate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionInput" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Modifier": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, "is_active": { "type": "boolean" } }, "required": [ "code", "name" ] }, "ModifierGroup": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "min_select": { "type": "integer" }, "max_select": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "position": { "type": "integer" }, "modifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Modifier" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ] }, "Address": { "type": "object", "properties": { "label": { "type": "string" }, "recipient": { "type": "string" }, "company": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "description": "Código de país de 2 letras (MX, SV, US…)." }, "phone": { "type": "string" }, "is_default_shipping": { "type": "boolean" }, "is_default_billing": { "type": "boolean" } }, "required": [ "line1", "city", "country" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "code": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "type": "string" }, "tax_id": { "type": "string" }, "group": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "accepts_marketing": { "type": "boolean" }, "notes": { "type": "string" }, "is_active": { "type": "boolean" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "first_name" ] }, "ProductOptionInput": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string" }, "color": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "value" ] } ] }, "description": "Textos o `{value, color}` con color `#RRGGBB`." } }, "required": [ "name", "values" ] }, "VariantInput": { "type": "object", "properties": { "code": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Solo con `variants_mode: exact`: `{\"Color\": \"Negro\"}`." }, "attributes": { "type": "object", "additionalProperties": true, "description": "`{CODIGO: valor}` de atributos de `scope` `variant`; `null` borra." } } }, "Variant": { "type": "object", "properties": { "product": { "type": "string" }, "code": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "type": "string" } }, "option_colors": { "type": "object", "additionalProperties": true }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "attributes": { "type": "object", "additionalProperties": true }, "position": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProductImage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "url": { "type": "string", "readOnly": true }, "thumbnail_url": { "type": "string", "readOnly": true }, "external_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "readOnly": true }, "external_key": { "type": "string", "readOnly": true }, "alt_text": { "type": "string", "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "width": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "readOnly": true }, "height": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "readOnly": true }, "variant_skus": { "type": "array", "items": { "type": "string" }, "readOnly": true } } }, "Product": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "short_description": { "type": "string" }, "description": { "type": "string" }, "base_unit": { "type": "string" }, "tax_exempt": { "type": "boolean" }, "tax_code": { "type": "string" }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "track_inventory": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionInput" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/VariantInput" } }, "variants_mode": { "type": "string", "enum": [ "exact" ], "description": "Opcional; ver `docs/api.md` (#68)." }, "attributes": { "type": "object", "additionalProperties": true }, "units": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "modifier_groups": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "code", "name" ], "description": "En la lectura, `variants` trae además existencias por ubicación y precios, e `images` las imágenes." }, "ProductOptionRead": { "type": "object", "properties": { "name": { "type": "string", "readOnly": true }, "values": { "type": "array", "items": { "type": "string" }, "readOnly": true }, "colors": { "type": "object", "additionalProperties": { "type": "string" }, "description": "`{valor: #RRGGBB}`, solo los valores con color.", "readOnly": true } } }, "VariantInventory": { "type": "object", "properties": { "location": { "type": "string", "readOnly": true }, "on_hand": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "reserved": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "available": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true } } }, "VariantPrice": { "type": "object", "properties": { "price_list": { "type": "string", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "compare_at_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ], "readOnly": true }, "min_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true } } }, "ProductVariantRead": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "sku": { "type": "string", "readOnly": true }, "barcode": { "type": "string", "readOnly": true }, "title": { "type": "string", "readOnly": true }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "readOnly": true }, "option_colors": { "type": "object", "additionalProperties": true, "readOnly": true }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ], "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "attributes": { "type": "object", "additionalProperties": true, "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "inventory": { "type": "array", "items": { "$ref": "#/components/schemas/VariantInventory" }, "readOnly": true }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/VariantPrice" }, "readOnly": true } } }, "ProductRead": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "short_description": { "type": "string" }, "description": { "type": "string" }, "base_unit": { "type": "string" }, "tax_exempt": { "type": "boolean" }, "tax_code": { "type": "string" }, "weight": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "track_inventory": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionRead" }, "readOnly": true }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantRead" }, "readOnly": true }, "attributes": { "type": "object", "additionalProperties": true }, "units": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "modifier_groups": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "readOnly": true }, "collections": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "Códigos de las colecciones del producto." } }, "description": "Lo que la API devuelve de un producto. Para escribir, ver `Product`." }, "OrderAddress": { "type": "object", "properties": { "label": { "type": "string" }, "recipient": { "type": "string" }, "company": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "description": "Código de país de 2 letras (MX, SV, US…)." }, "phone": { "type": "string" }, "is_default_shipping": { "type": "boolean" }, "is_default_billing": { "type": "boolean" } }, "required": [ "line1", "city", "country" ] }, "OrderLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "parent_line": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "readOnly": true }, "sku": { "type": "string", "readOnly": true }, "product_name": { "type": "string", "readOnly": true }, "variant_title": { "type": "string", "readOnly": true }, "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "unit_code": { "type": "string", "readOnly": true }, "unit_name": { "type": "string", "readOnly": true }, "unit_factor": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "unit_price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "line_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "returned_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true } } }, "OrderReturn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "reason": { "type": "string", "readOnly": true }, "restock": { "type": "boolean", "readOnly": true }, "refund_amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ], "readOnly": true }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "number": { "type": "integer", "readOnly": true }, "status": { "type": "string", "enum": [ "open", "cancelled", "archived" ], "readOnly": true }, "payment_status": { "type": "string", "enum": [ "pending", "authorized", "paid", "partially_refunded", "refunded", "failed" ], "readOnly": true }, "fulfillment_status": { "type": "string", "enum": [ "unfulfilled", "prepared", "ready_for_pickup", "shipped", "delivered" ], "readOnly": true }, "delivery_type": { "type": "string", "enum": [ "shipping", "pickup", "takeout", "dine_in", "delivery_app" ], "readOnly": true }, "table_number": { "type": "string", "readOnly": true }, "source": { "type": "string", "readOnly": true }, "customer": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "readOnly": true }, "customer_name": { "type": "string", "readOnly": true }, "email": { "type": "string", "readOnly": true }, "phone": { "type": "string", "readOnly": true }, "shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/OrderAddress" }, { "type": "null" } ], "readOnly": true }, "billing_address": { "oneOf": [ { "$ref": "#/components/schemas/OrderAddress" }, { "type": "null" } ], "readOnly": true }, "location": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "prices_include_tax": { "type": "boolean", "readOnly": true }, "tax_rate": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "subtotal": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "discount_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "shipping_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "tax_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "refunded_total": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "payment_method": { "type": "string", "readOnly": true }, "payment_method_name": { "type": "string", "readOnly": true }, "payment_reference": { "type": "string", "readOnly": true }, "carrier": { "type": "string", "readOnly": true }, "carrier_code": { "type": "string", "readOnly": true }, "carrier_service_code": { "type": "string", "readOnly": true }, "carrier_service_name": { "type": "string", "readOnly": true }, "carrier_fee": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "tracking_number": { "type": "string", "readOnly": true }, "tracking_url": { "type": "string", "readOnly": true }, "notes": { "type": "string", "readOnly": true }, "cancel_reason": { "type": "string", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" }, "readOnly": true }, "returns": { "type": "array", "items": { "$ref": "#/components/schemas/OrderReturn" }, "readOnly": true }, "placed_at": { "type": "string", "format": "date-time", "readOnly": true }, "paid_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "shipped_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "delivered_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "cancelled_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "archived_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "reservation_expires_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "erp_accepted_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Sello informativo: el ERP recibió el pedido.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "OrderLineInput": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, "unit_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "unit": { "type": "string" }, "modifiers": { "type": "array", "items": { "type": "string" }, "description": "Códigos de modificador." } }, "required": [ "sku", "quantity" ] }, "OrderCreate": { "type": "object", "properties": { "customer": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customer_email": { "type": "string" }, "customer_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineInput" }, "minItems": 1 }, "shipping_address": { "$ref": "#/components/schemas/OrderAddress" }, "billing_address": { "$ref": "#/components/schemas/OrderAddress" }, "location": { "type": "string" }, "discount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, "shipping": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, "notes": { "type": "string" }, "delivery_type": { "type": "string", "enum": [ "shipping", "pickup", "dine_in", "takeout", "delivery_app" ], "default": "shipping", "description": "Depende de lo que tenga activo la tienda; un tipo no aceptado responde `400`." }, "table_number": { "type": "string" }, "payment_method": { "type": "string" }, "carrier_code": { "type": "string" }, "carrier_service_code": { "type": "string" } }, "required": [ "lines" ] }, "PayInput": { "type": "object", "properties": { "method": { "type": "string" }, "reference": { "type": "string" } } }, "ShipInput": { "type": "object", "properties": { "carrier": { "type": "string" }, "carrier_code": { "type": "string" }, "tracking_number": { "type": "string" } } }, "CancelInput": { "type": "object", "properties": { "reason": { "type": "string" } } }, "ReturnInput": { "type": "object", "properties": { "lines": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "line_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." } }, "required": [ "line_id", "quantity" ] } }, "reason": { "type": "string" }, "restock": { "type": "boolean" }, "refund_amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] } }, "required": [ "lines", "reason" ] }, "RefundInput": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, "reason": { "type": "string" }, "payment": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "amount", "reason" ] }, "DuplicateInput": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "copy_images": { "type": "boolean" }, "copy_prices": { "type": "boolean" } } }, "PaymentRefund": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "pending", "done", "failed" ], "readOnly": true }, "reason": { "type": "string", "readOnly": true }, "provider_reference": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "completed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "provider": { "type": "string", "readOnly": true }, "method": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "pending", "authorized", "paid", "partially_refunded", "refunded", "failed", "expired" ], "readOnly": true }, "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "currency": { "type": "string", "readOnly": true }, "refunded_amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "provider_reference": { "type": "string", "readOnly": true }, "needs_review": { "type": "boolean", "readOnly": true }, "review_reason": { "type": "string", "enum": [ "late", "amount_mismatch", "duplicate", "" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "paid_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "failed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRefund" }, "readOnly": true } } }, "CarrierService": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "level": { "type": "string", "enum": [ "standard", "express" ], "readOnly": true }, "fee": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "position": { "type": "integer", "readOnly": true } } }, "Carrier": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "tracking_url_template": { "type": "string", "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierService" }, "readOnly": true } } }, "PaymentMethod": { "type": "object", "properties": { "code": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "kind": { "type": "string", "enum": [ "card", "payment_link", "transfer", "cash_on_delivery", "in_store", "other" ], "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "position": { "type": "integer", "readOnly": true }, "reservation_hours": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "readOnly": true } } }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "kind": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "config": { "type": "object", "additionalProperties": true, "readOnly": true }, "is_active": { "type": "boolean", "readOnly": true }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "readOnly": true } } }, "SyncRunInput": { "type": "object", "properties": { "kind": { "type": "string", "maxLength": 30 }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "records": { "type": "integer" }, "errors": { "type": "integer" }, "status": { "type": "string", "enum": [ "ok", "partial", "failed" ] }, "message": { "type": "string", "maxLength": 2000 } }, "required": [ "kind", "started_at", "finished_at" ] }, "SyncRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "records": { "type": "integer" }, "errors": { "type": "integer" }, "status": { "type": "string", "enum": [ "ok", "partial", "failed" ] }, "message": { "type": "string" } } }, "ExternalReferenceInput": { "type": "object", "properties": { "connection": { "type": "string", "format": "uuid" }, "object_type": { "type": "string", "enum": [ "product", "variant", "category", "brand", "collection", "modifier_group", "modifier", "attribute", "location", "price_list", "customer_group", "customer", "order" ] }, "object_key": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Código; SKU para variantes; número (entero) para pedidos." }, "external_id": { "type": "string" }, "external_code": { "type": "string" }, "data_hash": { "type": "string" }, "synced_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "connection", "object_type", "object_key", "external_id" ] }, "ExternalReference": { "type": "object", "properties": { "connection": { "type": "string", "format": "uuid" }, "object_type": { "type": "string", "enum": [ "product", "variant", "category", "brand", "collection", "modifier_group", "modifier", "attribute", "location", "price_list", "customer_group", "customer", "order" ] }, "object_key": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Código; SKU para variantes; número (entero) para pedidos." }, "external_id": { "type": "string" }, "external_code": { "type": "string" }, "data_hash": { "type": "string" }, "synced_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "readOnly": true } }, "required": [ "connection", "object_type", "object_key", "external_id" ] }, "Translation": { "type": "object", "properties": { "language": { "type": "string" }, "field": { "type": "string" }, "value": { "type": "string" } } }, "TranslationInput": { "type": "object", "properties": { "object_type": { "type": "string", "enum": [ "product", "category", "collection", "brand", "attribute" ] }, "object_key": { "type": "string" }, "language": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Campo -> texto (name, description…). Vacío borra." } }, "required": [ "object_type", "object_key", "language", "fields" ] }, "PriceRow": { "type": "object", "properties": { "price_list": { "type": "string", "readOnly": true }, "sku": { "type": "string", "readOnly": true }, "price": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "compare_at_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ], "readOnly": true }, "min_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "PriceBulkItem": { "type": "object", "properties": { "price_list": { "type": "string" }, "sku": { "type": "string" }, "price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "compare_at_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, { "type": "null" } ] }, "min_quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." } }, "required": [ "price_list", "sku", "price" ] }, "PricesBulkInput": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/PriceBulkItem" } }, "partial": { "type": "boolean" } }, "required": [ "items" ] }, "InventoryRow": { "type": "object", "properties": { "sku": { "type": "string", "readOnly": true }, "location": { "type": "string", "readOnly": true }, "on_hand": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "reserved": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "available": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto.", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "InventoryBulkItem": { "type": "object", "properties": { "sku": { "type": "string" }, "location": { "type": "string" }, "on_hand": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal como texto." }, "reference": { "type": "string" } }, "required": [ "sku", "location", "on_hand" ] }, "InventoryBulkInput": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/InventoryBulkItem" } }, "partial": { "type": "boolean" } }, "required": [ "items" ] }, "BulkRowReport": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "BulkResult": { "type": "object", "properties": { "updated": { "type": "integer" }, "deleted": { "type": "integer" }, "received": { "type": "integer" }, "changed": { "type": "integer" }, "failed": { "type": "integer" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BulkRowReport" } } }, "description": "Precios devuelve `updated`/`deleted`; inventario `received`/`changed`. `failed` y `rows` solo con `partial`." }, "BulkJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "error": { "type": "string" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "updated", "error" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "sku": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Trabajo asíncrono de alta masiva. `rows` solo en la consulta, paginado con `offset`/`limit`." }, "ImportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "error": { "type": "string" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "updated", "error" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "sku": { "type": "string" } } } }, "errors": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Trabajo asíncrono de importación NDJSON (solo crea). `updated` siempre 0." }, "ProductsBulkInput": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "allOf": [ { "$ref": "#/components/schemas/Product" } ], "required": [ "code" ] } } }, "required": [ "items" ] }, "ImportUpload": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "NDJSON UTF-8, hasta 256 MB." } }, "required": [ "file" ] }, "ImageUpload": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPG, PNG, WEBP o GIF, hasta 10 MB." }, "alt_text": { "type": "string" }, "external_key": { "type": "string", "maxLength": 100 }, "variant_skus": { "type": "string", "description": "SKU separados por coma (o lista JSON)." } } }, "ImageUrl": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Solo https; se guarda sin descargar." }, "external_key": { "type": "string" }, "alt_text": { "type": "string" }, "variant_skus": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Igual en cada reintento: deduplica por este valor." }, "event": { "type": "string", "enum": [ "order.created", "order.updated", "order.paid", "order.payment_failed", "order.shipped", "order.ready_for_pickup", "order.delivered", "order.cancelled", "order.returned", "order.refunded", "inventory.changed" ] }, "store": { "type": "string", "description": "Slug de la tienda." }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "description": "Pedido (`id`, `number`, estados, líneas, envío…) o, en `inventory.changed`, `sku`, `product_code`, `product_name` y `available`. `order.refunded` suma `refund`." } }, "required": [ "id", "event", "store", "occurred_at", "data" ], "description": "Cuerpo de cada entrega." } } } }