Productos
Fichas de producto: nombres, descripciones, categorías, opciones y fotos. Las variantes tienen sus endpoints; el producto se escribe junto con ellas.
Productos
Objetos
Product
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 del registro: crece con cada cambio. Para cambiar el registro, envíela como ETag en If-Match.
typestringobligatorioTipo de producto: goods — mercadería para la venta; dish — plato que se prepara al pedido; ingredient — materia prima para recetas; prep — semielaborado de preparación propia; manufactured — producción propia de la tienda; meal_program — plan de comidas por suscripción; bundle — combo de otros productos; gift_card — tarjeta de regalo; service — servicio con turno.
- Valores:
goodsdishingredientprepmanufacturedmeal_programbundlegift_cardserviceservice_package
stock_unitobject o nullobligatorioUnidad de stock de un ítem con stock por medida (insumo, preelaborado, producto fabricado): en ella se llevan el stock, las recetas y el rendimiento. null en mercadería y platos: su unidad es el eje de venta de la variante.
Campos · 3
unitstringobligatorioUnidad base: g — gramos, ml — mililitros, pcs — unidades. Las cantidades de las variantes del producto son textos decimales en esta unidad.
- Valores:
gmlpcs
purchase_unitstring o nullobligatorioNombre del envase de compra, por ejemplo kg o caja; null — el ítem se compra en su unidad base.
purchase_quantitystringobligatorioCuántas unidades base hay en un envase de compra, como texto decimal: por ejemplo, 1000 para un kilo de un ítem que se lleva en gramos.
namemapa de stringobligatorioNombre por idioma: un objeto con los idiomas completados, por ejemplo {"es": "Café", "en": "Coffee"}.
short_descriptionmapa de stringobligatorioDescripción breve por idioma, texto plano para las listas de productos.
descriptionmapa de stringobligatorioDescripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.
slugstringobligatorioDirección del producto en la tienda online, única en la tienda.
brand_idinteger o nullobligatorioID de la marca del producto; null si no está definida.
tax_class_idinteger o nullobligatorioID de la clase de impuesto del producto (/v1/tax-classes); null — la clase predeterminada de la tienda. Una venta conserva la alícuota de su ítem: un cambio de clase afecta solo a las ventas futuras.
category_idsarray de integerobligatorioID de las categorías del producto, en orden ascendente.
primary_category_idinteger o nullobligatorioLa categoría principal entre category_ids; null si no se eligió una principal.
optionsarray de objectobligatorioOpciones en las que difieren las variantes, como talle o color, en orden.
Campos · 5
idintegerobligatorioID de la opción.
keystringobligatorioClave técnica de la opción, única en el producto, por ejemplo size.
namemapa de stringobligatorioNombre de la opción por idioma.
positionintegerobligatorioPosición de la opción: la menor va primero.
valuesarray de objectobligatorioValores de la opción en orden.
Campos · 4
idintegerobligatorioID del valor. Las variantes lo nombran en option_values.
valuemapa de stringobligatorioEl valor por idioma, por ejemplo {"es": "Rojo", "en": "Red"}.
swatch_colorstring o nullobligatorioColor de la muestra, código hexadecimal como #C0392B; null si el valor no tiene muestra.
positionintegerobligatorioPosición del valor: la menor va primero.
modifier_groupsarray de objectobligatorioLos grupos de modificadores del producto en orden de exhibición con la regla de elección en este producto. Los recargos de opciones por variante — GET /v1/products/{product}/modifier-groups; PUT en la misma ruta reemplaza los grupos.
Campos · 2
group_idintegerobligatorioID del grupo de modificadores (/v1/modifier-groups).
selection_ruleobject o nullobligatorioRegla de elección en este producto en lugar de la regla del grupo; null — la regla del grupo.
Campos · 2
min_selectintegerobligatorioCuántas opciones hay que elegir en este producto.
max_selectinteger o nullobligatorioCuántas opciones se pueden elegir en este producto; null — sin límite.
mediaarray de objectobligatorioFotos y videos de la galería en orden: los mismos objetos que en /v1/products/{product}/media.
Campos · 7
idintegerobligatorioID del archivo en la biblioteca de medios. Un archivo está en la galería de un producto como máximo una vez.
kindstringobligatorioimage — foto; video — video.
- Valores:
imagevideo
urlstringobligatorioDirección pública del archivo.
mimestringobligatorioTipo MIME del archivo, por ejemplo image/webp.
altmapa de stringobligatorioTexto alternativo por idioma, para lectores de pantalla y buscadores.
positionintegerobligatorioLugar en la galería, desde cero.
is_primarybooleanobligatorioLa foto principal: la tienda online la muestra primero.
is_activebooleanobligatoriofalse retira el producto de la venta y lo oculta de la tienda online.
published_atstring (date-time) o nullobligatorioCuándo aparece el producto en la tienda online; null — de inmediato.
unpublished_atstring (date-time) o nullobligatorioCuándo sale el producto de la tienda online; null — se queda.
sale_schedulearray de object o nullobligatorioCuándo se puede pedir el producto — franjas de la semana en la zona horaria del comercio; null — siempre. Fuera de la franja el producto sigue visible y se puede agregar al carrito, y el checkout compara el horario con el momento de entrega del pedido.
Campos · 3
daysarray de integerobligatorioDías de la franja, ISO: 1 es lunes, 7 es domingo.
fromstringobligatorioInicio de la franja, «HH:MM» según el reloj del comercio.
tostringobligatorioFin de la franja, «HH:MM», sin incluir ese momento; «24:00» — hasta el final del día. Un fin anterior al inicio hace que la franja pase la medianoche; pertenece a su día de inicio.
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 producto con sus variantes; null en un producto vigente.
Endpoints
Listar los productos: categorías, opciones y fotos, sin variantes
get/products
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.
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/products" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"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"
}Crear un producto con sus variantes
post/products
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
namemapa de string o nullobligatorioNombre por idioma: un objeto con los idiomas completados, por ejemplo {"es": "Café", "en": "Coffee"}.
- Largo máximo:
- 255
short_descriptionmapa de string o null o nullDescripción breve por idioma, texto plano para las listas de productos.
- Largo máximo:
- 500
descriptionmapa de string o null o nullDescripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.
- Largo máximo:
- 50000
slugstringDirección del producto en la tienda online, única en la tienda.
- Largo máximo:
- 160
brand_idinteger o nullID de la marca del producto; null si no está definida.
tax_class_idinteger o nullID de la clase de impuesto del producto (/v1/tax-classes); null — la clase predeterminada de la tienda. Una venta conserva la alícuota de su ítem: un cambio de clase afecta solo a las ventas futuras.
category_idsarray de integerID de las categorías del producto, en orden ascendente.
primary_category_idinteger o nullLa categoría principal entre category_ids; null si no se eligió una principal.
is_activebooleanfalse retira el producto de la venta y lo oculta de la tienda online.
published_atstring (date-time) o nullCuándo aparece el producto en la tienda online; null — de inmediato.
unpublished_atstring (date-time) o nullCuándo sale el producto de la tienda online; null — se queda.
sale_schedulearray de object o nullCuándo se puede pedir el producto — franjas de la semana en la zona horaria del comercio; null — siempre. Fuera de la franja el producto sigue visible y se puede agregar al carrito, y el checkout compara el horario con el momento de entrega del pedido.
- Máximo de elementos:
- 14
Campos · 3
daysarray de integerobligatorioDías de la franja, ISO: 1 es lunes, 7 es domingo.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 7
- Mínimo:
- 1
- Máximo:
- 7
fromstringobligatorioInicio de la franja, «HH:MM» según el reloj del comercio.
- Patrón:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
tostringobligatorioFin de la franja, «HH:MM», sin incluir ese momento; «24:00» — hasta el final del día. Un fin anterior al inicio hace que la franja pase la medianoche; pertenece a su día de inicio.
- Patrón:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
typestringTipo de producto: goods — mercadería para la venta; dish — plato que se prepara al pedido; ingredient — materia prima para recetas; prep — semielaborado de preparación propia; manufactured — producción propia de la tienda; meal_program — plan de comidas por suscripción; bundle — combo de otros productos; gift_card — tarjeta de regalo; service — servicio con turno.
- Valores:
goodsdishingredientprep
stock_unitobject o nullUnidad de stock de un ítem con stock por medida (insumo, preelaborado, producto fabricado): en ella se llevan el stock, las recetas y el rendimiento. null en mercadería y platos: su unidad es el eje de venta de la variante.
Campos · 3
unitstringUnidad base: g — gramos, ml — mililitros, pcs — unidades. Las cantidades de las variantes del producto son textos decimales en esta unidad.
- Valores:
gmlpcs
purchase_unitstring o nullNombre del envase de compra, por ejemplo kg o caja; null — el ítem se compra en su unidad base.
- Largo máximo:
- 16
purchase_quantitystring o nullCuántas unidades base hay en un envase de compra, como texto decimal: por ejemplo, 1000 para un kilo de un ítem que se lleva en gramos.
- Largo máximo:
- 32
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.
variantsarray de objectobligatorioLíneas de variantes escritas junto con la ficha. Una línea se encuentra por su external_id: la variante del producto con ese ID se cambia con los campos enviados; si no hay, se crea una; las variantes no mencionadas quedan como están. Crear un producto exige al menos una línea con precio.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 200
Campos · 23
external_idstring o nullID externo de la variante, su ID en tu sistema: la clave con la que se encuentra la línea.
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.
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 Product
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 - 409
plan_limit_reachedSe alcanzó el límite del plan - 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/products" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
1
],
"from": "string",
"to": "string"
}
],
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"external_id": "string",
"variants": [
{
"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
}
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Obtener un producto
get/products/{product}
Scope: catalog:read
Parámetros
Ruta
productintegerobligatorioID del producto.
Respuestas
200Éxito
Encabezados
ETagstringobligatorioVersión del registro. Mandala en If-Match para cambiar el registro.
- Ejemplo:
"7"
application/json
Devuelve Product
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/products/{product}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Modificar la ficha de un producto: campos, categorías, ID externo
patch/products/{product}
Scope: catalog:write
Parámetros
Ruta
productintegerobligatorioID del producto.
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
namemapa de string o nullNombre por idioma: un objeto con los idiomas completados, por ejemplo {"es": "Café", "en": "Coffee"}.
- Largo máximo:
- 255
short_descriptionmapa de string o null o nullDescripción breve por idioma, texto plano para las listas de productos.
- Largo máximo:
- 500
descriptionmapa de string o null o nullDescripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.
- Largo máximo:
- 50000
slugstringDirección del producto en la tienda online, única en la tienda.
- Largo máximo:
- 160
brand_idinteger o nullID de la marca del producto; null si no está definida.
tax_class_idinteger o nullID de la clase de impuesto del producto (/v1/tax-classes); null — la clase predeterminada de la tienda. Una venta conserva la alícuota de su ítem: un cambio de clase afecta solo a las ventas futuras.
category_idsarray de integerID de las categorías del producto, en orden ascendente.
primary_category_idinteger o nullLa categoría principal entre category_ids; null si no se eligió una principal.
is_activebooleanfalse retira el producto de la venta y lo oculta de la tienda online.
published_atstring (date-time) o nullCuándo aparece el producto en la tienda online; null — de inmediato.
unpublished_atstring (date-time) o nullCuándo sale el producto de la tienda online; null — se queda.
sale_schedulearray de object o nullCuándo se puede pedir el producto — franjas de la semana en la zona horaria del comercio; null — siempre. Fuera de la franja el producto sigue visible y se puede agregar al carrito, y el checkout compara el horario con el momento de entrega del pedido.
- Máximo de elementos:
- 14
Campos · 3
daysarray de integerobligatorioDías de la franja, ISO: 1 es lunes, 7 es domingo.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 7
- Mínimo:
- 1
- Máximo:
- 7
fromstringobligatorioInicio de la franja, «HH:MM» según el reloj del comercio.
- Patrón:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
tostringobligatorioFin de la franja, «HH:MM», sin incluir ese momento; «24:00» — hasta el final del día. Un fin anterior al inicio hace que la franja pase la medianoche; pertenece a su día de inicio.
- Patrón:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
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.
variantsarray de objectLíneas de variantes escritas junto con la ficha. Una línea se encuentra por su external_id: la variante del producto con ese ID se cambia con los campos enviados; si no hay, se crea una; las variantes no mencionadas quedan como están. Crear un producto exige al menos una línea con precio.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 200
Campos · 24
external_idstring o nullID externo de la variante, su ID en tu sistema: la clave con la que se encuentra la línea.
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.
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 Product
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/products/{product}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
1
],
"from": "string",
"to": "string"
}
],
"external_id": "string",
"variants": [
{
"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
}
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Archivar un producto con sus variantes
delete/products/{product}
Scope: catalog:write
Parámetros
Ruta
productintegerobligatorioID del producto.
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
live_subscriptionsstringEl plan con suscripciones vigentes sale de la venta.
- 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 - 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/products/{product}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Obtener un producto por su ID externo
get/products/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 Product
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/products/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Crear o modificar un producto con sus variantes por su ID en la app
patch/products/by-external-id/{external_id}
Scope: catalog:write
Parámetros
Ruta
external_idstringobligatorioID externo: el ID del registro en tu sistema.
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
namemapa de string o nullNombre por idioma: un objeto con los idiomas completados, por ejemplo {"es": "Café", "en": "Coffee"}.
- Largo máximo:
- 255
short_descriptionmapa de string o null o nullDescripción breve por idioma, texto plano para las listas de productos.
- Largo máximo:
- 500
descriptionmapa de string o null o nullDescripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.
- Largo máximo:
- 50000
slugstringDirección del producto en la tienda online, única en la tienda.
- Largo máximo:
- 160
brand_idinteger o nullID de la marca del producto; null si no está definida.
tax_class_idinteger o nullID de la clase de impuesto del producto (/v1/tax-classes); null — la clase predeterminada de la tienda. Una venta conserva la alícuota de su ítem: un cambio de clase afecta solo a las ventas futuras.
category_idsarray de integerID de las categorías del producto, en orden ascendente.
primary_category_idinteger o nullLa categoría principal entre category_ids; null si no se eligió una principal.
is_activebooleanfalse retira el producto de la venta y lo oculta de la tienda online.
published_atstring (date-time) o nullCuándo aparece el producto en la tienda online; null — de inmediato.
unpublished_atstring (date-time) o nullCuándo sale el producto de la tienda online; null — se queda.
sale_schedulearray de object o nullCuándo se puede pedir el producto — franjas de la semana en la zona horaria del comercio; null — siempre. Fuera de la franja el producto sigue visible y se puede agregar al carrito, y el checkout compara el horario con el momento de entrega del pedido.
- Máximo de elementos:
- 14
Campos · 3
daysarray de integerobligatorioDías de la franja, ISO: 1 es lunes, 7 es domingo.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 7
- Mínimo:
- 1
- Máximo:
- 7
fromstringobligatorioInicio de la franja, «HH:MM» según el reloj del comercio.
- Patrón:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
tostringobligatorioFin de la franja, «HH:MM», sin incluir ese momento; «24:00» — hasta el final del día. Un fin anterior al inicio hace que la franja pase la medianoche; pertenece a su día de inicio.
- Patrón:
^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
typestringTipo de producto: goods — mercadería para la venta; dish — plato que se prepara al pedido; ingredient — materia prima para recetas; prep — semielaborado de preparación propia; manufactured — producción propia de la tienda; meal_program — plan de comidas por suscripción; bundle — combo de otros productos; gift_card — tarjeta de regalo; service — servicio con turno.
- Valores:
goodsdishingredientprep
stock_unitobject o nullUnidad de stock de un ítem con stock por medida (insumo, preelaborado, producto fabricado): en ella se llevan el stock, las recetas y el rendimiento. null en mercadería y platos: su unidad es el eje de venta de la variante.
Campos · 3
unitstringUnidad base: g — gramos, ml — mililitros, pcs — unidades. Las cantidades de las variantes del producto son textos decimales en esta unidad.
- Valores:
gmlpcs
purchase_unitstring o nullNombre del envase de compra, por ejemplo kg o caja; null — el ítem se compra en su unidad base.
- Largo máximo:
- 16
purchase_quantitystring o nullCuántas unidades base hay en un envase de compra, como texto decimal: por ejemplo, 1000 para un kilo de un ítem que se lleva en gramos.
- Largo máximo:
- 32
variantsarray de objectLíneas de variantes escritas junto con la ficha. Una línea se encuentra por su external_id: la variante del producto con ese ID se cambia con los campos enviados; si no hay, se crea una; las variantes no mencionadas quedan como están. Crear un producto exige al menos una línea con precio.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 200
Campos · 24
external_idstring o nullID externo de la variante, su ID en tu sistema: la clave con la que se encuentra la línea.
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.
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 Product
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 Product
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
external_id_in_useEl ID externo está en uso - 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 409
plan_limit_reachedSe alcanzó el límite del plan - 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/products/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
1
],
"from": "string",
"to": "string"
}
],
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"variants": [
{
"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
}
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}Reemplazar las opciones del producto y distribuir sus variantes
put/products/{product}/options
Scope: catalog:write
Parámetros
Ruta
productintegerobligatorioID del producto.
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 · 1
variant_axesstringLas variantes con la misma combinación se fusionan, y las indicadas para archivar se archivan junto con sus dependencias.
- 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
optionsarray de objectobligatorioOpciones en las que difieren las variantes, como talle o color, en orden.
- Máximo de elementos:
- 10
Campos · 4
keystringobligatorioClave técnica de la opción, única en el producto, por ejemplo size.
- Largo máximo:
- 32
- Patrón:
^[a-z][a-z0-9_]*$
namemapa de string o nullobligatorioNombre de la opción por idioma.
- Largo máximo:
- 120
valuesarray de objectobligatorioValores de la opción en orden.
- Mínimo de elementos:
- 1
- Máximo de elementos:
- 50
Campos · 3
valuemapa de string o nullobligatorioEl valor por idioma, por ejemplo {"es": "Rojo", "en": "Red"}.
- Largo máximo:
- 120
swatch_colorstring o nullColor de la muestra, código hexadecimal como #C0392B; null si el valor no tiene muestra.
- Largo máximo:
- 16
- Patrón:
^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
idinteger o nullID del valor. Las variantes lo nombran en option_values.
idinteger o nullID de la opción.
variantsarray de objectobligatorioDistribución de cada variante vigente del producto: una combinación de valores o el archivo. Una variante que falta en la distribución se rechaza: pudo agregarse después de que leíste el producto.
- Máximo de elementos:
- 200
Campos · 3
idintegerobligatorioID de la variante.
archivebooleantrue — archivar la variante en lugar de darle valores.
value_indexesarray de integerValores de la variante: para cada opción, el índice del valor en options[i].values de esta solicitud, así se nombran también los valores nuevos sin id.
- Máximo de elementos:
- 10
- Mínimo:
- 0
- Máximo:
- 49
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 Product
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 - 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/products/{product}/options" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"options": [
{
"key": "string",
"name": {
"key": "string"
},
"values": [
{
"value": {
"key": "string"
},
"swatch_color": "string",
"id": 0
}
],
"id": 0
}
],
"variants": [
{
"id": 0,
"archive": true,
"value_indexes": [
0
]
}
]
}{
"id": 0,
"external_id": "string",
"version": 0,
"type": "goods",
"stock_unit": {
"unit": "g",
"purchase_unit": "string",
"purchase_quantity": "string"
},
"name": {
"key": "string"
},
"short_description": {
"key": "string"
},
"description": {
"key": "string"
},
"slug": "string",
"brand_id": 0,
"tax_class_id": 0,
"category_ids": [
0
],
"primary_category_id": 0,
"options": [
{
"id": 0,
"key": "string",
"name": {
"key": "string"
},
"position": 0,
"values": [
{
"id": 0,
"value": {
"key": "string"
},
"swatch_color": "string",
"position": 0
}
]
}
],
"modifier_groups": [
{
"group_id": 0,
"selection_rule": {
"min_select": 0,
"max_select": 0
}
}
],
"media": [
{
"id": 0,
"kind": "image",
"url": "string",
"mime": "string",
"alt": {
"key": "string"
},
"position": 0,
"is_primary": true
}
],
"is_active": true,
"published_at": "2026-01-15T12:00:00Z",
"unpublished_at": "2026-01-15T12:00:00Z",
"sale_schedule": [
{
"days": [
0
],
"from": "string",
"to": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"deleted_at": "2026-01-15T12:00:00Z"
}