Variantes

Lo que se vende y se guarda en stock: SKU, códigos de barras, precios, unidad y forma de venta. Cambian bajo la versión de la ficha del producto.

Cargando el índice de búsqueda…

Variantes

Objetos

Variant

  • idintegerobligatorio

    ID del registro, único entre los registros de su tipo en la tienda.

  • external_idstring o nullobligatorio

    ID externo: el ID del registro en tu sistema; null si la aplicación no lo fijó. Cada aplicación ve solo sus propios ID.

  • versionintegerobligatorio

    Versión de la ficha del producto: las variantes cambian bajo la versión común de la ficha, así que cambiar cualquier variante o la ficha la mueve.

  • product_idintegerobligatorio

    ID del producto.

  • skustring o nullobligatorio

    Código de artículo (SKU); null si no está definido.

  • namemapa de stringobligatorio

    Nombre de la variante por idioma, por ejemplo {"es": "Grande"}.

  • positionintegerobligatorio

    Posición entre las variantes del producto: la menor va primero.

  • is_activebooleanobligatorio

    false retira la variante de la venta.

  • barcodesarray de objectobligatorio

    Códigos de barras de la variante.

    Campos · 3
    • valuestringobligatorio

      El código de barras.

    • typestringobligatorio

      Simbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.

    • is_primarybooleanobligatorio

      El código de barras principal de la variante: lo imprimen las etiquetas y los tickets.

  • option_valuesarray de objectobligatorio

    Valores de opción de la variante: un valor de cada opción del producto.

    Campos · 2
    • option_idintegerobligatorio

      ID de la opción en options del producto.

    • value_idintegerobligatorio

      ID del valor en values de esa opción.

  • sold_bystringobligatorio

    Cómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.

    Valores:
    eachweightvolume
  • unitstringobligatorio

    Unidad de todas las cantidades de la variante: pcs — unidades; g — gramos; ml — mililitros.

    Valores:
    pcsgml
  • quantity_decimalsintegerobligatorio

    Decimales de las cantidades de la variante: 0 por unidad, 3 por peso y por volumen.

    Valores:
    03
  • priceintegerobligatorio

    Precio por price_per_quantity unidades, entero en unidades mínimas de currency.

  • compare_at_priceinteger o nullobligatorio

    Precio antes del descuento, se muestra tachado; null si no hay descuento.

  • list_priceinteger o nullobligatorio

    Precio tal como lo fijó el dueño, en unidades mínimas de list_price_currency; null — el precio se fijó en la moneda de la tienda (price). En esa variante price lo calcula el sistema con la cotización de la lista y no se acepta en la entrada.

  • list_price_currencystring o nullobligatorio

    Moneda del precio fijado (lista de la tienda en otra moneda); null — precio en la moneda de la tienda currency. En la entrada: la moneda de la lista de la tienda o currency.

  • currencystringobligatorio

    Moneda de los precios, código ISO 4217: la moneda de la tienda.

  • price_per_quantitystring o nullobligatorio

    Por cuántas unidades es el precio, como cadena decimal: una unidad, o 1000 para el precio por kilo de una variante por peso. null si una variante por peso o volumen no lo tiene definido.

  • measure_stepstring o nullobligatorio

    Paso de la cantidad en un ítem de una variante por peso o volumen, en su unidad; null si no está definido.

  • min_measure_qtystring o nullobligatorio

    Cantidad mínima en un ítem de una variante por peso o volumen; null si no está definida.

  • max_measure_qtystring o nullobligatorio

    Cantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.

  • net_contentobject o nullobligatorio

    Contenido neto de una unidad: paquete de 500 g, botella de 1000 ml. Un pack de varias unidades de otra variante lo toma de ella, una unidad envasada, de su propia medida; solo se puede escribir en una variante común por unidad. null en variantes por peso o volumen y en unidades sin contenido neto.

    Campos · 2
    • quantitystringobligatorio

      Medida como cadena decimal en unit: "500", "0.5".

    • unitstringobligatorio

      Unidad de la medida: g — gramos; ml — mililitros.

      Valores:
      gml
  • sale_starts_atstring (date-time) o nullobligatorio

    Cuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.

  • sale_ends_atstring (date-time) o nullobligatorio

    Cuándo termina la oferta; null — sin fin.

  • cost_price_microinteger o null

    Costo por cost_per_quantity unidades en millonésimas de la unidad mínima de currency: 1,50 USD = 150000000. Solo con el scope costs:read.

  • cost_per_quantitystring

    Por cuántas unidades es el costo, como cadena decimal: la unidad de compra, por ejemplo 1000 g. Solo con el scope costs:read.

  • track_inventorybooleanobligatorio

    La tienda lleva el stock de la variante; false — se vende sin contar stock.

  • stock_source_variant_idinteger o nullobligatorio

    En un pack de varias unidades de otra variante: esa variante. El pack se vende de su stock y no tiene niveles de stock propios. null en una variante común.

  • stock_source_quantitystring o nullobligatorio

    Cuánto de la variante base consume una unidad del pack, como cadena decimal en la unidad de la variante base; null en una variante común.

  • weight_gramsinteger o nullobligatorio

    Peso para el envío en gramos; null si no está definido.

  • length_mminteger o nullobligatorio

    Largo del paquete en milímetros; null si no está definido.

  • width_mminteger o nullobligatorio

    Ancho del paquete en milímetros; null si no está definido.

  • height_mminteger o nullobligatorio

    Alto del paquete en milímetros; null si no está definido.

  • created_atstring (date-time)obligatorio

    Cuándo se creó el registro.

  • updated_atstring (date-time)obligatorio

    Cuándo cambió el registro por última vez.

  • deleted_atstring (date-time) o nullobligatorio

    Cuándo se archivó el registro; null en un registro vigente.

VariantRecipe

  • variant_idintegerobligatorio

    ID de la variante a la que pertenece la receta: un plato, un preelaborado u otro ítem hecho de componentes.

  • product_idintegerobligatorio

    ID del producto de la variante. La receta se versiona en su ficha: ETag e If-Match llevan la versión del producto.

  • versionintegerobligatorio

    Versión de la ficha del producto: el contador que verifica If-Match. Un cambio de la receta la mueve; la misma receta enviada otra vez, no.

  • componentsarray de objectobligatorio

    Componentes de la receta en orden: insumos y preelaborados con su cantidad. La lista completa reemplaza la receta; una lista vacía la vacía.

    Campos · 3
    • variant_idintegerobligatorio

      ID de la variante componente: un insumo o un preelaborado de la tienda.

    • quantitystring o nullobligatorio

      Cantidad del componente por porción de un plato o por tanda de un preelaborado, como texto decimal en la unidad del componente (stock_unit de su producto); null — a gusto: el componente figura pero no se descuenta.

    • measure_modestringobligatorio

      Cómo mide la producción el componente: fixed — la cantidad planificada; captured — se pesa al producir; proportional — se escala según un componente pesado. Solo lo lee la producción de preelaborados.

      Valores:
      fixedcapturedproportional
  • yield_quantitystring o nullobligatorio

    Rendimiento de una tanda de un preelaborado, como texto decimal en la unidad del preelaborado. Obligatorio en un preelaborado; null en un plato. Con puntos de control de rendimiento en los pasos de producción, los pasos fijan el rendimiento.

  • option_recipesarray de objectobligatorio

    Cantidades de las opciones por plato (recipe_per_variant) en esta variante: un bloque por cada opción así de los grupos del producto. Componentes vacíos — sin cantidad, y la opción no se ofrece en esta variante. Al escribir, un bloque fija la cantidad de la opción completa y los componentes vacíos la quitan; las opciones que faltan en la lista y un cuerpo sin el campo quedan como están.

    Campos · 2
    • option_idintegerobligatorio

      ID de una opción por plato de los grupos de modificadores del producto.

    • componentsarray de objectobligatorio

      Qué consume la opción cuando se toma con esta variante: insumos y preelaborados con su cantidad.

      Campos · 2
      • variant_idintegerobligatorio

        ID de la variante del producto.

      • quantitystring o nullobligatorio

        Cantidad del componente por un uso de la opción, como texto decimal en la unidad del componente; null — a gusto.

Endpoints

Listar las variantes: SKU, códigos de barras, precios y unidades

get/variants

Scope: catalog:read

Parámetros

Query

  • limitinteger

    Tamaño de página: hasta 250 registros; 50 por defecto.

    Mínimo:
    1
    Máximo:
    250
  • cursorstring

    Cursor opaco: next_cursor de la página anterior, o sync_cursor de la última página guardado por la sincronización anterior. El listado va en orden de confirmación, así que el cursor de sincronización devuelve luego solo lo que cambió después de él.

    Largo máximo:
    4096
  • updated_sincestring (date-time)

    Solo los registros cambiados después de este momento, ISO 8601 con zona horaria. Un filtro de la primera sincronización; después se sigue con el cursor.

    Patrón:
    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
  • include_deletedboolean

    true — devolver también los registros eliminados: los archivados con deleted_at y los borrados de la base como marcas de eliminación {id, deleted_at} en la continuación por el cursor de sincronización. Activalo para sincronizar.

  • product_idinteger

    Solo los registros de este producto.

    Mínimo:
    1
  • skustring

    Solo la variante con este SKU.

    Largo máximo:
    64
  • barcodestring

    Solo las variantes con este código de barras.

    Largo máximo:
    512

Respuestas

200Éxito

application/json

  • dataarray de Variantobligatorio

    Registros de la página.

  • deletedarray de objectobligatorio

    Registros borrados de la base desde el cursor, como marcas de eliminación: solo con include_deleted=true en la continuación por el cursor de sincronización.

    Campos · 2
    • idintegerobligatorio

      ID del registro borrado.

    • deleted_atstring (date-time)obligatorio

      Cuándo se borró el registro.

  • next_cursorstring o nullobligatorio

    Cursor de la página siguiente; null en la última.

  • has_morebooleanobligatorio

    true si hay una página siguiente.

  • sync_cursorstring o nullobligatorio

    En la última página — el cursor desde el que continuar más tarde: con él llega solo lo que cambió después de esta página. null en las demás.

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

410El cursor de sincronización supera el plazo de conservación de eliminaciones o se emitió antes de restaurar la base de datos

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/variants" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "data": [
    {
      "id": 0,
      "external_id": "string",
      "version": 0,
      "product_id": 0,
      "sku": "string",
      "name": {
        "key": "string"
      },
      "position": 0,
      "is_active": true,
      "barcodes": [
        {
          "value": "string",
          "type": "string",
          "is_primary": true
        }
      ],
      "option_values": [
        {
          "option_id": 0,
          "value_id": 0
        }
      ],
      "sold_by": "each",
      "unit": "pcs",
      "quantity_decimals": 0,
      "price": 0,
      "compare_at_price": 0,
      "list_price": 0,
      "list_price_currency": "string",
      "currency": "string",
      "price_per_quantity": "string",
      "measure_step": "string",
      "min_measure_qty": "string",
      "max_measure_qty": "string",
      "net_content": {
        "quantity": "string",
        "unit": "g"
      },
      "sale_starts_at": "2026-01-15T12:00:00Z",
      "sale_ends_at": "2026-01-15T12:00:00Z",
      "cost_price_micro": 0,
      "cost_per_quantity": "string",
      "track_inventory": true,
      "stock_source_variant_id": 0,
      "stock_source_quantity": "string",
      "weight_grams": 0,
      "length_mm": 0,
      "width_mm": 0,
      "height_mm": 0,
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z",
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "deleted": [
    {
      "id": 0,
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": true,
  "sync_cursor": "string"
}

Agregar una variante a un producto

post/variants

Scope: catalog:write

Parámetros

Encabezado

  • Idempotency-Keystring

    Clave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.

    Largo mínimo:
    1
    Largo máximo:
    255
    Ejemplo:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Cuerpo de la solicitud application/json

  • product_idintegerobligatorio

    ID del producto.

  • external_idstring o null

    ID externo: el ID del registro en tu sistema; null si la aplicación no lo fijó. Cada aplicación ve solo sus propios ID.

  • skustring o null

    Código de artículo (SKU); null si no está definido.

    Largo máximo:
    64
  • namemapa de string o null o null

    Nombre de la variante por idioma, por ejemplo {"es": "Grande"}.

    Largo máximo:
    255
  • priceintegerobligatorio

    Precio por price_per_quantity unidades, entero en unidades mínimas de currency.

    Mínimo:
    0
    Máximo:
    10000000000
  • track_inventoryboolean

    La tienda lleva el stock de la variante; false — se vende sin contar stock.

  • is_activeboolean

    false retira la variante de la venta.

  • positioninteger

    Posición entre las variantes del producto: la menor va primero.

    Mínimo:
    0
    Máximo:
    2147483647
  • list_priceinteger

    Precio tal como lo fijó el dueño, en unidades mínimas de list_price_currency; null — el precio se fijó en la moneda de la tienda (price). En esa variante price lo calcula el sistema con la cotización de la lista y no se acepta en la entrada.

    Mínimo:
    0
    Máximo:
    10000000000
  • list_price_currencystring o null

    Moneda del precio fijado (lista de la tienda en otra moneda); null — precio en la moneda de la tienda currency. En la entrada: la moneda de la lista de la tienda o currency.

    Valores:
    ARSUSDBRLCLPCOPMXNPENRUBnull
  • compare_at_priceinteger o null

    Precio antes del descuento, se muestra tachado; null si no hay descuento.

    Máximo:
    10000000000
  • weight_gramsinteger o null

    Peso para el envío en gramos; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • length_mminteger o null

    Largo del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • width_mminteger o null

    Ancho del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • height_mminteger o null

    Alto del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • sale_starts_atstring (date-time) o null

    Cuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.

  • sale_ends_atstring (date-time) o null

    Cuándo termina la oferta; null — sin fin.

  • sold_bystring

    Cómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.

    Valores:
    eachweightvolume
  • price_per_quantitystring o null

    Por cuántas unidades es el precio, como cadena decimal: una unidad, o 1000 para el precio por kilo de una variante por peso. null si una variante por peso o volumen no lo tiene definido.

    Largo máximo:
    32
  • measure_stepstring o null

    Paso de la cantidad en un ítem de una variante por peso o volumen, en su unidad; null si no está definido.

    Largo máximo:
    32
  • min_measure_qtystring o null

    Cantidad mínima en un ítem de una variante por peso o volumen; null si no está definida.

    Largo máximo:
    32
  • max_measure_qtystring o null

    Cantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.

    Largo máximo:
    32
  • net_contentobject

    Contenido neto de una unidad: paquete de 500 g, botella de 1000 ml. Un pack de varias unidades de otra variante lo toma de ella, una unidad envasada, de su propia medida; solo se puede escribir en una variante común por unidad. null en variantes por peso o volumen y en unidades sin contenido neto.

    Campos · 2
    • quantitystring

      Medida como cadena decimal en unit: "500", "0.5".

      Largo máximo:
      32
    • unitstring

      Unidad de la medida: g — gramos; ml — mililitros.

      Valores:
      gml
  • barcodesarray de object o null

    Códigos de barras de la variante.

    Máximo de elementos:
    20
    Campos · 3
    • typestringobligatorio

      Simbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.

      Valores:
      ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
    • valuestringobligatorio

      El código de barras.

    • is_primaryboolean o null

      El código de barras principal de la variante: lo imprimen las etiquetas y los tickets.

  • option_valuesarray de object

    Valores de opción de la variante: un valor de cada opción del producto.

    Máximo de elementos:
    10
    Campos · 2
    • option_idintegerobligatorio

      ID de la opción en options del producto.

    • value_idintegerobligatorio

      ID del valor en values de esa opción.

  • stock_source_variant_idinteger o null

    En un pack de varias unidades de otra variante: esa variante. El pack se vende de su stock y no tiene niveles de stock propios. null en una variante común.

  • stock_source_quantitystring o null

    Cuánto de la variante base consume una unidad del pack, como cadena decimal en la unidad de la variante base; null en una variante común.

    Largo máximo:
    32
  • sibling_namemapa de string o null

    Nombre por idioma de la única variante del producto, que esta solicitud convierte en una de varias: la única variante no tiene nombre propio, una de varias debe tenerlo.

    Largo máximo:
    255

Respuestas

201Creado

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"
  • Locationstring (uri)obligatorio

    Dirección del registro creado; en una solicitud aceptada (202), la dirección donde seguir su resultado.

application/json

Devuelve Variant

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl -X POST "https://api.saleya.app/v1/variants" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "product_id": 0,
  "external_id": "string",
  "sku": "string",
  "name": {
    "key": "string"
  },
  "price": 0,
  "track_inventory": true,
  "is_active": true,
  "position": 0,
  "list_price": 0,
  "list_price_currency": "ARS",
  "compare_at_price": 0,
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "sold_by": "each",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "barcodes": [
    {
      "type": "ean13",
      "value": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "sibling_name": {
    "key": "string"
  }
}
Ejemplo de respuesta · 201
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "product_id": 0,
  "sku": "string",
  "name": {
    "key": "string"
  },
  "position": 0,
  "is_active": true,
  "barcodes": [
    {
      "value": "string",
      "type": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "sold_by": "each",
  "unit": "pcs",
  "quantity_decimals": 0,
  "price": 0,
  "compare_at_price": 0,
  "list_price": 0,
  "list_price_currency": "string",
  "currency": "string",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "cost_price_micro": 0,
  "cost_per_quantity": "string",
  "track_inventory": true,
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Obtener una variante

get/variants/{variant}

Scope: catalog:read

Parámetros

Ruta

  • variantintegerobligatorio

    ID de la variante.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"

application/json

Devuelve Variant

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/variants/{variant}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "product_id": 0,
  "sku": "string",
  "name": {
    "key": "string"
  },
  "position": 0,
  "is_active": true,
  "barcodes": [
    {
      "value": "string",
      "type": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "sold_by": "each",
  "unit": "pcs",
  "quantity_decimals": 0,
  "price": 0,
  "compare_at_price": 0,
  "list_price": 0,
  "list_price_currency": "string",
  "currency": "string",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "cost_price_micro": 0,
  "cost_per_quantity": "string",
  "track_inventory": true,
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Modificar una variante de producto

patch/variants/{variant}

Scope: catalog:write

Parámetros

Ruta

  • variantintegerobligatorio

    ID de la variante.

Query

  • consentobject

    Consentimientos a las consecuencias del cambio, por tipo: consent[<consent_kind>]=<consent_token> de una respuesta 409 consent_required. Conservá los consentimientos ya dados cuando se pide el tipo siguiente.

    Campos · 4
    • measure_changestring

      La variante cambia cómo se vende (por unidad o por medida): se convierten su stock, precios y límites.

      Largo mínimo:
      64
      Largo máximo:
      64
    • piece_mode_offstring

      Los packs de la variante se archivan cuando deja de venderse en packs.

      Largo mínimo:
      64
      Largo máximo:
      64
    • stock_sourcestring

      El stock propio de la variante pasa a su variante base, y desde ahora se vende del stock de la base.

      Largo mínimo:
      64
      Largo máximo:
      64
    • program_menustring

      El plato sale de los menús de los planes de comidas por suscripción.

      Largo mínimo:
      64
      Largo máximo:
      64

Encabezado

  • Idempotency-Keystring

    Clave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.

    Largo mínimo:
    1
    Largo máximo:
    255
    Ejemplo:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringobligatorio

    ETag del registro de la última lectura, por ejemplo "7". El cambio se aplica solo si nadie cambió el registro desde entonces; si no, 412. Sin él, 428.

    Ejemplo:
    "7"

Cuerpo de la solicitud application/json

  • external_idstring o null

    ID externo: el ID del registro en tu sistema; null si la aplicación no lo fijó. Cada aplicación ve solo sus propios ID.

  • skustring o null

    Código de artículo (SKU); null si no está definido.

    Largo máximo:
    64
  • namemapa de string o null o null

    Nombre de la variante por idioma, por ejemplo {"es": "Grande"}.

    Largo máximo:
    255
  • priceinteger

    Precio por price_per_quantity unidades, entero en unidades mínimas de currency.

    Mínimo:
    0
    Máximo:
    10000000000
  • track_inventoryboolean

    La tienda lleva el stock de la variante; false — se vende sin contar stock.

  • is_activeboolean

    false retira la variante de la venta.

  • positioninteger

    Posición entre las variantes del producto: la menor va primero.

    Mínimo:
    0
    Máximo:
    2147483647
  • list_priceinteger

    Precio tal como lo fijó el dueño, en unidades mínimas de list_price_currency; null — el precio se fijó en la moneda de la tienda (price). En esa variante price lo calcula el sistema con la cotización de la lista y no se acepta en la entrada.

    Mínimo:
    0
    Máximo:
    10000000000
  • list_price_currencystring o null

    Moneda del precio fijado (lista de la tienda en otra moneda); null — precio en la moneda de la tienda currency. En la entrada: la moneda de la lista de la tienda o currency.

    Valores:
    ARSUSDBRLCLPCOPMXNPENRUBnull
  • compare_at_priceinteger o null

    Precio antes del descuento, se muestra tachado; null si no hay descuento.

    Máximo:
    10000000000
  • weight_gramsinteger o null

    Peso para el envío en gramos; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • length_mminteger o null

    Largo del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • width_mminteger o null

    Ancho del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • height_mminteger o null

    Alto del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • sale_starts_atstring (date-time) o null

    Cuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.

  • sale_ends_atstring (date-time) o null

    Cuándo termina la oferta; null — sin fin.

  • sold_bystring

    Cómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.

    Valores:
    eachweightvolume
  • price_per_quantitystring o null

    Por cuántas unidades es el precio, como cadena decimal: una unidad, o 1000 para el precio por kilo de una variante por peso. null si una variante por peso o volumen no lo tiene definido.

    Largo máximo:
    32
  • measure_stepstring o null

    Paso de la cantidad en un ítem de una variante por peso o volumen, en su unidad; null si no está definido.

    Largo máximo:
    32
  • min_measure_qtystring o null

    Cantidad mínima en un ítem de una variante por peso o volumen; null si no está definida.

    Largo máximo:
    32
  • max_measure_qtystring o null

    Cantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.

    Largo máximo:
    32
  • net_contentobject

    Contenido neto de una unidad: paquete de 500 g, botella de 1000 ml. Un pack de varias unidades de otra variante lo toma de ella, una unidad envasada, de su propia medida; solo se puede escribir en una variante común por unidad. null en variantes por peso o volumen y en unidades sin contenido neto.

    Campos · 2
    • quantitystring

      Medida como cadena decimal en unit: "500", "0.5".

      Largo máximo:
      32
    • unitstring

      Unidad de la medida: g — gramos; ml — mililitros.

      Valores:
      gml
  • barcodesarray de object o null

    Códigos de barras de la variante.

    Máximo de elementos:
    20
    Campos · 3
    • typestringobligatorio

      Simbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.

      Valores:
      ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
    • valuestringobligatorio

      El código de barras.

    • is_primaryboolean o null

      El código de barras principal de la variante: lo imprimen las etiquetas y los tickets.

  • option_valuesarray de object

    Valores de opción de la variante: un valor de cada opción del producto.

    Máximo de elementos:
    10
    Campos · 2
    • option_idintegerobligatorio

      ID de la opción en options del producto.

    • value_idintegerobligatorio

      ID del valor en values de esa opción.

  • stock_source_variant_idinteger o null

    En un pack de varias unidades de otra variante: esa variante. El pack se vende de su stock y no tiene niveles de stock propios. null en una variante común.

  • stock_source_quantitystring o null

    Cuánto de la variante base consume una unidad del pack, como cadena decimal en la unidad de la variante base; null en una variante común.

    Largo máximo:
    32

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"

application/json

Devuelve Variant

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

412El registro cambió después de leerlo: la versión de If-Match no es la actual

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

428La solicitud necesita If-Match con el ETag del registro

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl -X PATCH "https://api.saleya.app/v1/variants/{variant}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "external_id": "string",
  "sku": "string",
  "name": {
    "key": "string"
  },
  "price": 0,
  "track_inventory": true,
  "is_active": true,
  "position": 0,
  "list_price": 0,
  "list_price_currency": "ARS",
  "compare_at_price": 0,
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "sold_by": "each",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "barcodes": [
    {
      "type": "ean13",
      "value": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string"
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "product_id": 0,
  "sku": "string",
  "name": {
    "key": "string"
  },
  "position": 0,
  "is_active": true,
  "barcodes": [
    {
      "value": "string",
      "type": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "sold_by": "each",
  "unit": "pcs",
  "quantity_decimals": 0,
  "price": 0,
  "compare_at_price": 0,
  "list_price": 0,
  "list_price_currency": "string",
  "currency": "string",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "cost_price_micro": 0,
  "cost_per_quantity": "string",
  "track_inventory": true,
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Archivar una variante de producto

delete/variants/{variant}

Scope: catalog:write

Parámetros

Ruta

  • variantintegerobligatorio

    ID de la variante.

Query

  • consentobject

    Consentimientos a las consecuencias del cambio, por tipo: consent[<consent_kind>]=<consent_token> de una respuesta 409 consent_required. Conservá los consentimientos ya dados cuando se pide el tipo siguiente.

    Campos · 4
    • recipe_ingredientstring

      El producto es ingrediente de recetas vigentes y sale de ellas.

      Largo mínimo:
      64
      Largo máximo:
      64
    • production_draftstring

      Se cancelan los borradores de actas de producción con el producto.

      Largo mínimo:
      64
      Largo máximo:
      64
    • program_menustring

      El plato sale de los menús de los planes de comidas por suscripción.

      Largo mínimo:
      64
      Largo máximo:
      64
    • stock_dependentsstring

      Los packs que se venden del stock de esta variante pasan a ser variantes comunes con stock cero.

      Largo mínimo:
      64
      Largo máximo:
      64

Encabezado

  • Idempotency-Keystring

    Clave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.

    Largo mínimo:
    1
    Largo máximo:
    255
    Ejemplo:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringobligatorio

    ETag del registro de la última lectura, por ejemplo "7". El cambio se aplica solo si nadie cambió el registro desde entonces; si no, 412. Sin él, 428.

    Ejemplo:
    "7"

Respuestas

204Éxito

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true

Sin cuerpo

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

412El registro cambió después de leerlo: la versión de If-Match no es la actual

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

428La solicitud necesita If-Match con el ETag del registro

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl -X DELETE "https://api.saleya.app/v1/variants/{variant}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'

Obtener una variante por su ID externo

get/variants/by-external-id/{external_id}

Scope: catalog:read

Parámetros

Ruta

  • external_idstringobligatorio

    ID externo: el ID del registro en tu sistema.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"

application/json

Devuelve Variant

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/variants/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "product_id": 0,
  "sku": "string",
  "name": {
    "key": "string"
  },
  "position": 0,
  "is_active": true,
  "barcodes": [
    {
      "value": "string",
      "type": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "sold_by": "each",
  "unit": "pcs",
  "quantity_decimals": 0,
  "price": 0,
  "compare_at_price": 0,
  "list_price": 0,
  "list_price_currency": "string",
  "currency": "string",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "cost_price_micro": 0,
  "cost_per_quantity": "string",
  "track_inventory": true,
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Crear o modificar una variante por su ID en la app

patch/variants/by-external-id/{external_id}

Scope: catalog:write

Parámetros

Ruta

  • external_idstringobligatorio

    ID externo: el ID del registro en tu sistema.

Query

  • consentobject

    Consentimientos a las consecuencias del cambio, por tipo: consent[<consent_kind>]=<consent_token> de una respuesta 409 consent_required. Conservá los consentimientos ya dados cuando se pide el tipo siguiente.

    Campos · 4
    • measure_changestring

      La variante cambia cómo se vende (por unidad o por medida): se convierten su stock, precios y límites.

      Largo mínimo:
      64
      Largo máximo:
      64
    • piece_mode_offstring

      Los packs de la variante se archivan cuando deja de venderse en packs.

      Largo mínimo:
      64
      Largo máximo:
      64
    • stock_sourcestring

      El stock propio de la variante pasa a su variante base, y desde ahora se vende del stock de la base.

      Largo mínimo:
      64
      Largo máximo:
      64
    • program_menustring

      El plato sale de los menús de los planes de comidas por suscripción.

      Largo mínimo:
      64
      Largo máximo:
      64

Encabezado

  • Idempotency-Keystring

    Clave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.

    Largo mínimo:
    1
    Largo máximo:
    255
    Ejemplo:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstring

    ETag del registro de la última lectura. Es obligatorio si ya existe un registro con este ID externo (si no, 428) y no tiene que estar si no existe.

    Ejemplo:
    "7"
  • If-None-Matchstring

    * — solo crear: si ya existe un registro con este ID externo, la solicitud recibe 412.

    Valores:
    *

Cuerpo de la solicitud application/json

  • product_idinteger

    ID del producto.

  • skustring o null

    Código de artículo (SKU); null si no está definido.

    Largo máximo:
    64
  • namemapa de string o null o null

    Nombre de la variante por idioma, por ejemplo {"es": "Grande"}.

    Largo máximo:
    255
  • priceinteger

    Precio por price_per_quantity unidades, entero en unidades mínimas de currency.

    Mínimo:
    0
    Máximo:
    10000000000
  • track_inventoryboolean

    La tienda lleva el stock de la variante; false — se vende sin contar stock.

  • is_activeboolean

    false retira la variante de la venta.

  • positioninteger

    Posición entre las variantes del producto: la menor va primero.

    Mínimo:
    0
    Máximo:
    2147483647
  • list_priceinteger

    Precio tal como lo fijó el dueño, en unidades mínimas de list_price_currency; null — el precio se fijó en la moneda de la tienda (price). En esa variante price lo calcula el sistema con la cotización de la lista y no se acepta en la entrada.

    Mínimo:
    0
    Máximo:
    10000000000
  • list_price_currencystring o null

    Moneda del precio fijado (lista de la tienda en otra moneda); null — precio en la moneda de la tienda currency. En la entrada: la moneda de la lista de la tienda o currency.

    Valores:
    ARSUSDBRLCLPCOPMXNPENRUBnull
  • compare_at_priceinteger o null

    Precio antes del descuento, se muestra tachado; null si no hay descuento.

    Máximo:
    10000000000
  • weight_gramsinteger o null

    Peso para el envío en gramos; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • length_mminteger o null

    Largo del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • width_mminteger o null

    Ancho del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • height_mminteger o null

    Alto del paquete en milímetros; null si no está definido.

    Mínimo:
    0
    Máximo:
    2147483647
  • sale_starts_atstring (date-time) o null

    Cuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.

  • sale_ends_atstring (date-time) o null

    Cuándo termina la oferta; null — sin fin.

  • sold_bystring

    Cómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.

    Valores:
    eachweightvolume
  • price_per_quantitystring o null

    Por cuántas unidades es el precio, como cadena decimal: una unidad, o 1000 para el precio por kilo de una variante por peso. null si una variante por peso o volumen no lo tiene definido.

    Largo máximo:
    32
  • measure_stepstring o null

    Paso de la cantidad en un ítem de una variante por peso o volumen, en su unidad; null si no está definido.

    Largo máximo:
    32
  • min_measure_qtystring o null

    Cantidad mínima en un ítem de una variante por peso o volumen; null si no está definida.

    Largo máximo:
    32
  • max_measure_qtystring o null

    Cantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.

    Largo máximo:
    32
  • net_contentobject

    Contenido neto de una unidad: paquete de 500 g, botella de 1000 ml. Un pack de varias unidades de otra variante lo toma de ella, una unidad envasada, de su propia medida; solo se puede escribir en una variante común por unidad. null en variantes por peso o volumen y en unidades sin contenido neto.

    Campos · 2
    • quantitystring

      Medida como cadena decimal en unit: "500", "0.5".

      Largo máximo:
      32
    • unitstring

      Unidad de la medida: g — gramos; ml — mililitros.

      Valores:
      gml
  • barcodesarray de object o null

    Códigos de barras de la variante.

    Máximo de elementos:
    20
    Campos · 3
    • typestringobligatorio

      Simbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.

      Valores:
      ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
    • valuestringobligatorio

      El código de barras.

    • is_primaryboolean o null

      El código de barras principal de la variante: lo imprimen las etiquetas y los tickets.

  • option_valuesarray de object

    Valores de opción de la variante: un valor de cada opción del producto.

    Máximo de elementos:
    10
    Campos · 2
    • option_idintegerobligatorio

      ID de la opción en options del producto.

    • value_idintegerobligatorio

      ID del valor en values de esa opción.

  • stock_source_variant_idinteger o null

    En un pack de varias unidades de otra variante: esa variante. El pack se vende de su stock y no tiene niveles de stock propios. null en una variante común.

  • stock_source_quantitystring o null

    Cuánto de la variante base consume una unidad del pack, como cadena decimal en la unidad de la variante base; null en una variante común.

    Largo máximo:
    32
  • sibling_namemapa de string o null

    Nombre por idioma de la única variante del producto, que esta solicitud convierte en una de varias: la única variante no tiene nombre propio, una de varias debe tenerlo.

    Largo máximo:
    255

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"

application/json

Devuelve Variant

201Creado

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"
  • Locationstring (uri)obligatorio

    Dirección del registro creado; en una solicitud aceptada (202), la dirección donde seguir su resultado.

application/json

Devuelve Variant

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

412El registro cambió después de leerlo: la versión de If-Match no es la actual

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

428La solicitud necesita If-Match con el ETag del registro

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl -X PATCH "https://api.saleya.app/v1/variants/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "product_id": 0,
  "sku": "string",
  "name": {
    "key": "string"
  },
  "price": 0,
  "track_inventory": true,
  "is_active": true,
  "position": 0,
  "list_price": 0,
  "list_price_currency": "ARS",
  "compare_at_price": 0,
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "sold_by": "each",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "barcodes": [
    {
      "type": "ean13",
      "value": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "sibling_name": {
    "key": "string"
  }
}
Ejemplo de respuesta · 200
{
  "id": 0,
  "external_id": "string",
  "version": 0,
  "product_id": 0,
  "sku": "string",
  "name": {
    "key": "string"
  },
  "position": 0,
  "is_active": true,
  "barcodes": [
    {
      "value": "string",
      "type": "string",
      "is_primary": true
    }
  ],
  "option_values": [
    {
      "option_id": 0,
      "value_id": 0
    }
  ],
  "sold_by": "each",
  "unit": "pcs",
  "quantity_decimals": 0,
  "price": 0,
  "compare_at_price": 0,
  "list_price": 0,
  "list_price_currency": "string",
  "currency": "string",
  "price_per_quantity": "string",
  "measure_step": "string",
  "min_measure_qty": "string",
  "max_measure_qty": "string",
  "net_content": {
    "quantity": "string",
    "unit": "g"
  },
  "sale_starts_at": "2026-01-15T12:00:00Z",
  "sale_ends_at": "2026-01-15T12:00:00Z",
  "cost_price_micro": 0,
  "cost_per_quantity": "string",
  "track_inventory": true,
  "stock_source_variant_id": 0,
  "stock_source_quantity": "string",
  "weight_grams": 0,
  "length_mm": 0,
  "width_mm": 0,
  "height_mm": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z",
  "deleted_at": "2026-01-15T12:00:00Z"
}

Obtener la receta de una variante: componentes y rendimiento del preelaborado

get/variants/{variant}/recipe

Scope: catalog:read

Parámetros

Ruta

  • variantintegerobligatorio

    ID de la variante.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"

application/json

Devuelve VariantRecipe

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/variants/{variant}/recipe" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "variant_id": 0,
  "product_id": 0,
  "version": 0,
  "components": [
    {
      "variant_id": 0,
      "quantity": "string",
      "measure_mode": "fixed"
    }
  ],
  "yield_quantity": "string",
  "option_recipes": [
    {
      "option_id": 0,
      "components": [
        {
          "variant_id": 0,
          "quantity": "string"
        }
      ]
    }
  ]
}

Reemplazar la receta de una variante: componentes y rendimiento del preelaborado

put/variants/{variant}/recipe

Scope: catalog:write

Parámetros

Ruta

  • variantintegerobligatorio

    ID de la variante.

Encabezado

  • Idempotency-Keystring

    Clave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.

    Largo mínimo:
    1
    Largo máximo:
    255
    Ejemplo:
    8e03978e-40d5-43e8-bc93-6894a57f9324
  • If-Matchstringobligatorio

    ETag del registro de la última lectura, por ejemplo "7". El cambio se aplica solo si nadie cambió el registro desde entonces; si no, 412. Sin él, 428.

    Ejemplo:
    "7"

Cuerpo de la solicitud application/json

  • componentsarray de objectobligatorio

    Componentes de la receta en orden: insumos y preelaborados con su cantidad. La lista completa reemplaza la receta; una lista vacía la vacía.

    Máximo de elementos:
    100
    Campos · 3
    • variant_idintegerobligatorio

      ID de la variante componente: un insumo o un preelaborado de la tienda.

    • quantitystring o nullobligatorio

      Cantidad del componente por porción de un plato o por tanda de un preelaborado, como texto decimal en la unidad del componente (stock_unit de su producto); null — a gusto: el componente figura pero no se descuenta.

      Largo máximo:
      32
    • measure_modestring

      Cómo mide la producción el componente: fixed — la cantidad planificada; captured — se pesa al producir; proportional — se escala según un componente pesado. Solo lo lee la producción de preelaborados.

      Valores:
      fixedcapturedproportionalby_output
  • yield_quantitystring o null

    Rendimiento de una tanda de un preelaborado, como texto decimal en la unidad del preelaborado. Obligatorio en un preelaborado; null en un plato. Con puntos de control de rendimiento en los pasos de producción, los pasos fijan el rendimiento.

    Largo máximo:
    32
  • option_recipesarray de object

    Cantidades de las opciones por plato (recipe_per_variant) en esta variante: un bloque por cada opción así de los grupos del producto. Componentes vacíos — sin cantidad, y la opción no se ofrece en esta variante. Al escribir, un bloque fija la cantidad de la opción completa y los componentes vacíos la quitan; las opciones que faltan en la lista y un cuerpo sin el campo quedan como están.

    Máximo de elementos:
    50
    Sin repetidos
    Campos · 2
    • option_idintegerobligatorio

      ID de una opción por plato de los grupos de modificadores del producto.

    • componentsarray de objectobligatorio

      Qué consume la opción cuando se toma con esta variante: insumos y preelaborados con su cantidad.

      Máximo de elementos:
      100
      Campos · 2
      • variant_idintegerobligatorio

        ID de la variante del producto.

      • quantitystring o nullobligatorio

        Cantidad del componente por un uso de la opción, como texto decimal en la unidad del componente; null — a gusto.

        Largo máximo:
        32

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

    true cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.

    Valores:
    true
  • ETagstringobligatorio

    Versión del registro. Mandala en If-Match para cambiar el registro.

    Ejemplo:
    "7"

application/json

Devuelve VariantRecipe

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

412El registro cambió después de leerlo: la versión de If-Match no es la actual

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

428La solicitud necesita If-Match con el ETag del registro

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl -X PUT "https://api.saleya.app/v1/variants/{variant}/recipe" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "components": [
    {
      "variant_id": 0,
      "quantity": "string",
      "measure_mode": "fixed"
    }
  ],
  "yield_quantity": "string",
  "option_recipes": [
    {
      "option_id": 0,
      "components": [
        {
          "variant_id": 0,
          "quantity": "string"
        }
      ]
    }
  ]
}
Ejemplo de respuesta · 200
{
  "variant_id": 0,
  "product_id": 0,
  "version": 0,
  "components": [
    {
      "variant_id": 0,
      "quantity": "string",
      "measure_mode": "fixed"
    }
  ],
  "yield_quantity": "string",
  "option_recipes": [
    {
      "option_id": 0,
      "components": [
        {
          "variant_id": 0,
          "quantity": "string"
        }
      ]
    }
  ]
}