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.
Variantes
Objetos
Variant
idintegerobligatorioID del registro, único entre los registros de su tipo en la tienda.
external_idstring o nullobligatorioID externo: el ID del registro en tu sistema; null si la aplicación no lo fijó. Cada aplicación ve solo sus propios ID.
versionintegerobligatorioVersió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_idintegerobligatorioID del producto.
skustring o nullobligatorioCódigo de artículo (SKU); null si no está definido.
namemapa de stringobligatorioNombre de la variante por idioma, por ejemplo {"es": "Grande"}.
positionintegerobligatorioPosición entre las variantes del producto: la menor va primero.
is_activebooleanobligatoriofalse retira la variante de la venta.
barcodesarray de objectobligatorioCódigos de barras de la variante.
Campos · 3
valuestringobligatorioEl código de barras.
typestringobligatorioSimbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.
is_primarybooleanobligatorioEl código de barras principal de la variante: lo imprimen las etiquetas y los tickets.
option_valuesarray de objectobligatorioValores de opción de la variante: un valor de cada opción del producto.
Campos · 2
option_idintegerobligatorioID de la opción en options del producto.
value_idintegerobligatorioID del valor en values de esa opción.
sold_bystringobligatorioCómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.
- Valores:
eachweightvolume
unitstringobligatorioUnidad de todas las cantidades de la variante: pcs — unidades; g — gramos; ml — mililitros.
- Valores:
pcsgml
quantity_decimalsintegerobligatorioDecimales de las cantidades de la variante: 0 por unidad, 3 por peso y por volumen.
- Valores:
03
priceintegerobligatorioPrecio por price_per_quantity unidades, entero en unidades mínimas de currency.
compare_at_priceinteger o nullobligatorioPrecio antes del descuento, se muestra tachado; null si no hay descuento.
list_priceinteger o nullobligatorioPrecio 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 nullobligatorioMoneda 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.
currencystringobligatorioMoneda de los precios, código ISO 4217: la moneda de la tienda.
price_per_quantitystring o nullobligatorioPor 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 nullobligatorioPaso 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 nullobligatorioCantidad mínima en un ítem de una variante por peso o volumen; null si no está definida.
max_measure_qtystring o nullobligatorioCantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.
net_contentobject o nullobligatorioContenido 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
quantitystringobligatorioMedida como cadena decimal en unit: "500", "0.5".
unitstringobligatorioUnidad de la medida: g — gramos; ml — mililitros.
- Valores:
gml
sale_starts_atstring (date-time) o nullobligatorioCuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.
sale_ends_atstring (date-time) o nullobligatorioCuándo termina la oferta; null — sin fin.
cost_price_microinteger o nullCosto 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_quantitystringPor cuántas unidades es el costo, como cadena decimal: la unidad de compra, por ejemplo 1000 g. Solo con el scope costs:read.
track_inventorybooleanobligatorioLa tienda lleva el stock de la variante; false — se vende sin contar stock.
stock_source_variant_idinteger o nullobligatorioEn 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 nullobligatorioCuá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 nullobligatorioPeso para el envío en gramos; null si no está definido.
length_mminteger o nullobligatorioLargo del paquete en milímetros; null si no está definido.
width_mminteger o nullobligatorioAncho del paquete en milímetros; null si no está definido.
height_mminteger o nullobligatorioAlto del paquete en milímetros; null si no está definido.
created_atstring (date-time)obligatorioCuándo se creó el registro.
updated_atstring (date-time)obligatorioCuándo cambió el registro por última vez.
deleted_atstring (date-time) o nullobligatorioCuándo se archivó el registro; null en un registro vigente.
VariantRecipe
variant_idintegerobligatorioID de la variante a la que pertenece la receta: un plato, un preelaborado u otro ítem hecho de componentes.
product_idintegerobligatorioID del producto de la variante. La receta se versiona en su ficha: ETag e If-Match llevan la versión del producto.
versionintegerobligatorioVersió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 objectobligatorioComponentes 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_idintegerobligatorioID de la variante componente: un insumo o un preelaborado de la tienda.
quantitystring o nullobligatorioCantidad 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_modestringobligatorioCó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 nullobligatorioRendimiento 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 objectobligatorioCantidades 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_idintegerobligatorioID de una opción por plato de los grupos de modificadores del producto.
componentsarray de objectobligatorioQué consume la opción cuando se toma con esta variante: insumos y preelaborados con su cantidad.
Campos · 2
variant_idintegerobligatorioID de la variante del producto.
quantitystring o nullobligatorioCantidad 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
limitintegerTamaño de página: hasta 250 registros; 50 por defecto.
- Mínimo:
- 1
- Máximo:
- 250
cursorstringCursor 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_deletedbooleantrue — 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_idintegerSolo los registros de este producto.
- Mínimo:
- 1
skustringSolo la variante con este SKU.
- Largo máximo:
- 64
barcodestringSolo las variantes con este código de barras.
- Largo máximo:
- 512
Respuestas
200Éxito
application/json
Registros de la página.
deletedarray de objectobligatorioRegistros 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
idintegerobligatorioID del registro borrado.
deleted_atstring (date-time)obligatorioCuándo se borró el registro.
next_cursorstring o nullobligatorioCursor de la página siguiente; null en la última.
has_morebooleanobligatoriotrue si hay una página siguiente.
sync_cursorstring o nullobligatorioEn 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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos 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
curl "https://api.saleya.app/v1/variants" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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-KeystringClave ú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_idintegerobligatorioID del producto.
external_idstring o nullID 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 nullCódigo de artículo (SKU); null si no está definido.
- Largo máximo:
- 64
namemapa de string o null o nullNombre de la variante por idioma, por ejemplo {"es": "Grande"}.
- Largo máximo:
- 255
priceintegerobligatorioPrecio por price_per_quantity unidades, entero en unidades mínimas de currency.
- Mínimo:
- 0
- Máximo:
- 10000000000
track_inventorybooleanLa tienda lleva el stock de la variante; false — se vende sin contar stock.
is_activebooleanfalse retira la variante de la venta.
positionintegerPosición entre las variantes del producto: la menor va primero.
- Mínimo:
- 0
- Máximo:
- 2147483647
list_priceintegerPrecio 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 nullMoneda 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 nullPrecio antes del descuento, se muestra tachado; null si no hay descuento.
- Máximo:
- 10000000000
weight_gramsinteger o nullPeso para el envío en gramos; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
length_mminteger o nullLargo del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
width_mminteger o nullAncho del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
height_mminteger o nullAlto del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
sale_starts_atstring (date-time) o nullCuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.
sale_ends_atstring (date-time) o nullCuándo termina la oferta; null — sin fin.
sold_bystringCómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.
- Valores:
eachweightvolume
price_per_quantitystring o nullPor 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 nullPaso 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 nullCantidad 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 nullCantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.
- Largo máximo:
- 32
net_contentobjectContenido 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
quantitystringMedida como cadena decimal en unit: "500", "0.5".
- Largo máximo:
- 32
unitstringUnidad de la medida: g — gramos; ml — mililitros.
- Valores:
gml
barcodesarray de object o nullCódigos de barras de la variante.
- Máximo de elementos:
- 20
Campos · 3
typestringobligatorioSimbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.
- Valores:
ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
valuestringobligatorioEl código de barras.
is_primaryboolean o nullEl código de barras principal de la variante: lo imprimen las etiquetas y los tickets.
option_valuesarray de objectValores de opción de la variante: un valor de cada opción del producto.
- Máximo de elementos:
- 10
Campos · 2
option_idintegerobligatorioID de la opción en options del producto.
value_idintegerobligatorioID del valor en values de esa opción.
stock_source_variant_idinteger o nullEn 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 nullCuá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 nullNombre 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-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
Locationstring (uri)obligatorioDirecció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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerSegundos 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
external_id_archivedEl registro con este ID externo está archivado - 409
external_id_in_useEl ID externo está en uso - 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
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
curl -X POST "https://api.saleya.app/v1/variants" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @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"
}
}{
"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
variantintegerobligatorioID de la variante.
Respuestas
200Éxito
Encabezados
ETagstringobligatorioVersió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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos 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
curl "https://api.saleya.app/v1/variants/{variant}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
variantintegerobligatorioID de la variante.
Query
consentobjectConsentimientos 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_changestringLa 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_offstringLos packs de la variante se archivan cuando deja de venderse en packs.
- Largo mínimo:
- 64
- Largo máximo:
- 64
stock_sourcestringEl 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_menustringEl plato sale de los menús de los planes de comidas por suscripción.
- Largo mínimo:
- 64
- Largo máximo:
- 64
Encabezado
Idempotency-KeystringClave ú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-MatchstringobligatorioETag 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 nullID 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 nullCódigo de artículo (SKU); null si no está definido.
- Largo máximo:
- 64
namemapa de string o null o nullNombre de la variante por idioma, por ejemplo {"es": "Grande"}.
- Largo máximo:
- 255
priceintegerPrecio por price_per_quantity unidades, entero en unidades mínimas de currency.
- Mínimo:
- 0
- Máximo:
- 10000000000
track_inventorybooleanLa tienda lleva el stock de la variante; false — se vende sin contar stock.
is_activebooleanfalse retira la variante de la venta.
positionintegerPosición entre las variantes del producto: la menor va primero.
- Mínimo:
- 0
- Máximo:
- 2147483647
list_priceintegerPrecio 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 nullMoneda 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 nullPrecio antes del descuento, se muestra tachado; null si no hay descuento.
- Máximo:
- 10000000000
weight_gramsinteger o nullPeso para el envío en gramos; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
length_mminteger o nullLargo del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
width_mminteger o nullAncho del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
height_mminteger o nullAlto del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
sale_starts_atstring (date-time) o nullCuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.
sale_ends_atstring (date-time) o nullCuándo termina la oferta; null — sin fin.
sold_bystringCómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.
- Valores:
eachweightvolume
price_per_quantitystring o nullPor 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 nullPaso 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 nullCantidad 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 nullCantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.
- Largo máximo:
- 32
net_contentobjectContenido 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
quantitystringMedida como cadena decimal en unit: "500", "0.5".
- Largo máximo:
- 32
unitstringUnidad de la medida: g — gramos; ml — mililitros.
- Valores:
gml
barcodesarray de object o nullCódigos de barras de la variante.
- Máximo de elementos:
- 20
Campos · 3
typestringobligatorioSimbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.
- Valores:
ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
valuestringobligatorioEl código de barras.
is_primaryboolean o nullEl código de barras principal de la variante: lo imprimen las etiquetas y los tickets.
option_valuesarray de objectValores de opción de la variante: un valor de cada opción del producto.
- Máximo de elementos:
- 10
Campos · 2
option_idintegerobligatorioID de la opción en options del producto.
value_idintegerobligatorioID del valor en values de esa opción.
stock_source_variant_idinteger o nullEn 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 nullCuá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-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersió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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerSegundos 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
consent_requiredHace falta consentir las consecuencias - 409
external_id_archivedEl registro con este ID externo está archivado - 409
external_id_in_useEl ID externo está en uso - 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 412
precondition_failedEl registro cambió - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida - 428
precondition_requiredFalta If-Match
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
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{
"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"
}{
"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
variantintegerobligatorioID de la variante.
Query
consentobjectConsentimientos 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_ingredientstringEl producto es ingrediente de recetas vigentes y sale de ellas.
- Largo mínimo:
- 64
- Largo máximo:
- 64
production_draftstringSe cancelan los borradores de actas de producción con el producto.
- Largo mínimo:
- 64
- Largo máximo:
- 64
program_menustringEl plato sale de los menús de los planes de comidas por suscripción.
- Largo mínimo:
- 64
- Largo máximo:
- 64
stock_dependentsstringLos 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-KeystringClave ú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-MatchstringobligatorioETag 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-Replayedstringtrue 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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerSegundos 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
consent_requiredHace falta consentir las consecuencias - 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 409
in_use_conflictRegistro en uso - 412
precondition_failedEl registro cambió - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida - 422
last_variant_of_productÚltima variante del producto - 428
precondition_requiredFalta If-Match
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
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_idstringobligatorioID externo: el ID del registro en tu sistema.
Respuestas
200Éxito
Encabezados
ETagstringobligatorioVersió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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos 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
curl "https://api.saleya.app/v1/variants/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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_idstringobligatorioID externo: el ID del registro en tu sistema.
Query
consentobjectConsentimientos 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_changestringLa 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_offstringLos packs de la variante se archivan cuando deja de venderse en packs.
- Largo mínimo:
- 64
- Largo máximo:
- 64
stock_sourcestringEl 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_menustringEl plato sale de los menús de los planes de comidas por suscripción.
- Largo mínimo:
- 64
- Largo máximo:
- 64
Encabezado
Idempotency-KeystringClave ú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-MatchstringETag 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_idintegerID del producto.
skustring o nullCódigo de artículo (SKU); null si no está definido.
- Largo máximo:
- 64
namemapa de string o null o nullNombre de la variante por idioma, por ejemplo {"es": "Grande"}.
- Largo máximo:
- 255
priceintegerPrecio por price_per_quantity unidades, entero en unidades mínimas de currency.
- Mínimo:
- 0
- Máximo:
- 10000000000
track_inventorybooleanLa tienda lleva el stock de la variante; false — se vende sin contar stock.
is_activebooleanfalse retira la variante de la venta.
positionintegerPosición entre las variantes del producto: la menor va primero.
- Mínimo:
- 0
- Máximo:
- 2147483647
list_priceintegerPrecio 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 nullMoneda 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 nullPrecio antes del descuento, se muestra tachado; null si no hay descuento.
- Máximo:
- 10000000000
weight_gramsinteger o nullPeso para el envío en gramos; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
length_mminteger o nullLargo del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
width_mminteger o nullAncho del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
height_mminteger o nullAlto del paquete en milímetros; null si no está definido.
- Mínimo:
- 0
- Máximo:
- 2147483647
sale_starts_atstring (date-time) o nullCuándo empieza la oferta: compare_at_price se muestra desde ese momento; null — sin inicio.
sale_ends_atstring (date-time) o nullCuándo termina la oferta; null — sin fin.
sold_bystringCómo se vende la variante: each — por unidad; weight — por peso; volume — por volumen.
- Valores:
eachweightvolume
price_per_quantitystring o nullPor 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 nullPaso 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 nullCantidad 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 nullCantidad máxima en un ítem de una variante por peso o volumen; null si no está definida.
- Largo máximo:
- 32
net_contentobjectContenido 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
quantitystringMedida como cadena decimal en unit: "500", "0.5".
- Largo máximo:
- 32
unitstringUnidad de la medida: g — gramos; ml — mililitros.
- Valores:
gml
barcodesarray de object o nullCódigos de barras de la variante.
- Máximo de elementos:
- 20
Campos · 3
typestringobligatorioSimbología: ean13, ean8, upca, upce, code128, code39, gtin, itf, qr, datamatrix u other.
- Valores:
ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
valuestringobligatorioEl código de barras.
is_primaryboolean o nullEl código de barras principal de la variante: lo imprimen las etiquetas y los tickets.
option_valuesarray de objectValores de opción de la variante: un valor de cada opción del producto.
- Máximo de elementos:
- 10
Campos · 2
option_idintegerobligatorioID de la opción en options del producto.
value_idintegerobligatorioID del valor en values de esa opción.
stock_source_variant_idinteger o nullEn 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 nullCuá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 nullNombre 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-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
application/json
Devuelve Variant
201Creado
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
Locationstring (uri)obligatorioDirecció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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerSegundos 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
consent_requiredHace falta consentir las consecuencias - 409
external_id_archivedEl registro con este ID externo está archivado - 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 412
precondition_failedEl registro cambió - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida - 428
precondition_requiredFalta If-Match
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
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{
"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"
}
}{
"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
variantintegerobligatorioID de la variante.
Respuestas
200Éxito
Encabezados
ETagstringobligatorioVersió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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos 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
curl "https://api.saleya.app/v1/variants/{variant}/recipe" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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
variantintegerobligatorioID de la variante.
Encabezado
Idempotency-KeystringClave ú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-MatchstringobligatorioETag 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 objectobligatorioComponentes 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_idintegerobligatorioID de la variante componente: un insumo o un preelaborado de la tienda.
quantitystring o nullobligatorioCantidad 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_modestringCó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 nullRendimiento 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 objectCantidades 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_idintegerobligatorioID de una opción por plato de los grupos de modificadores del producto.
componentsarray de objectobligatorioQué consume la opción cuando se toma con esta variante: insumos y preelaborados con su cantidad.
- Máximo de elementos:
- 100
Campos · 2
variant_idintegerobligatorioID de la variante del producto.
quantitystring o nullobligatorioCantidad 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-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
ETagstringobligatorioVersió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-AuthenticatestringobligatorioEsquema 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-AuthenticatestringEsquema 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-AfterintegerSegundos 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-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 412
precondition_failedEl registro cambió - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida - 428
precondition_requiredFalta If-Match
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
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{
"components": [
{
"variant_id": 0,
"quantity": "string",
"measure_mode": "fixed"
}
],
"yield_quantity": "string",
"option_recipes": [
{
"option_id": 0,
"components": [
{
"variant_id": 0,
"quantity": "string"
}
]
}
]
}{
"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"
}
]
}
]
}