Productos

Fichas de producto: nombres, descripciones, categorías, opciones y fotos. Las variantes tienen sus endpoints; el producto se escribe junto con ellas.

Cargando el índice de búsqueda…

Productos

Objetos

Product

  • idintegerobligatorio

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

  • external_idstring o nullobligatorio

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

  • versionintegerobligatorio

    Versión del registro: crece con cada cambio. Para cambiar el registro, envíela como ETag en If-Match.

  • typestringobligatorio

    Tipo 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 nullobligatorio

    Unidad 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
    • unitstringobligatorio

      Unidad 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 nullobligatorio

      Nombre del envase de compra, por ejemplo kg o caja; null — el ítem se compra en su unidad base.

    • purchase_quantitystringobligatorio

      Cuá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 stringobligatorio

    Nombre por idioma: un objeto con los idiomas completados, por ejemplo {"es": "Café", "en": "Coffee"}.

  • short_descriptionmapa de stringobligatorio

    Descripción breve por idioma, texto plano para las listas de productos.

  • descriptionmapa de stringobligatorio

    Descripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.

  • slugstringobligatorio

    Dirección del producto en la tienda online, única en la tienda.

  • brand_idinteger o nullobligatorio

    ID de la marca del producto; null si no está definida.

  • tax_class_idinteger o nullobligatorio

    ID 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 integerobligatorio

    ID de las categorías del producto, en orden ascendente.

  • primary_category_idinteger o nullobligatorio

    La categoría principal entre category_ids; null si no se eligió una principal.

  • optionsarray de objectobligatorio

    Opciones en las que difieren las variantes, como talle o color, en orden.

    Campos · 5
    • idintegerobligatorio

      ID de la opción.

    • keystringobligatorio

      Clave técnica de la opción, única en el producto, por ejemplo size.

    • namemapa de stringobligatorio

      Nombre de la opción por idioma.

    • positionintegerobligatorio

      Posición de la opción: la menor va primero.

    • valuesarray de objectobligatorio

      Valores de la opción en orden.

      Campos · 4
      • idintegerobligatorio

        ID del valor. Las variantes lo nombran en option_values.

      • valuemapa de stringobligatorio

        El valor por idioma, por ejemplo {"es": "Rojo", "en": "Red"}.

      • swatch_colorstring o nullobligatorio

        Color de la muestra, código hexadecimal como #C0392B; null si el valor no tiene muestra.

      • positionintegerobligatorio

        Posición del valor: la menor va primero.

  • modifier_groupsarray de objectobligatorio

    Los 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_idintegerobligatorio

      ID del grupo de modificadores (/v1/modifier-groups).

    • selection_ruleobject o nullobligatorio

      Regla de elección en este producto en lugar de la regla del grupo; null — la regla del grupo.

      Campos · 2
      • min_selectintegerobligatorio

        Cuántas opciones hay que elegir en este producto.

      • max_selectinteger o nullobligatorio

        Cuántas opciones se pueden elegir en este producto; null — sin límite.

  • mediaarray de objectobligatorio

    Fotos y videos de la galería en orden: los mismos objetos que en /v1/products/{product}/media.

    Campos · 7
    • idintegerobligatorio

      ID del archivo en la biblioteca de medios. Un archivo está en la galería de un producto como máximo una vez.

    • kindstringobligatorio

      image — foto; video — video.

      Valores:
      imagevideo
    • urlstringobligatorio

      Dirección pública del archivo.

    • mimestringobligatorio

      Tipo MIME del archivo, por ejemplo image/webp.

    • altmapa de stringobligatorio

      Texto alternativo por idioma, para lectores de pantalla y buscadores.

    • positionintegerobligatorio

      Lugar en la galería, desde cero.

    • is_primarybooleanobligatorio

      La foto principal: la tienda online la muestra primero.

  • is_activebooleanobligatorio

    false retira el producto de la venta y lo oculta de la tienda online.

  • published_atstring (date-time) o nullobligatorio

    Cuándo aparece el producto en la tienda online; null — de inmediato.

  • unpublished_atstring (date-time) o nullobligatorio

    Cuándo sale el producto de la tienda online; null — se queda.

  • sale_schedulearray de object o nullobligatorio

    Cuá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 integerobligatorio

      Días de la franja, ISO: 1 es lunes, 7 es domingo.

    • fromstringobligatorio

      Inicio de la franja, «HH:MM» según el reloj del comercio.

    • tostringobligatorio

      Fin 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)obligatorio

    Cuándo se creó el registro.

  • updated_atstring (date-time)obligatorio

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

  • deleted_atstring (date-time) o nullobligatorio

    Cuándo se archivó el 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

  • limitinteger

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

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

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

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

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

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

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

Respuestas

200Éxito

application/json

  • dataarray de Productobligatorio

    Registros de la página.

  • deletedarray de objectobligatorio

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

    Campos · 2
    • idintegerobligatorio

      ID del registro borrado.

    • deleted_atstring (date-time)obligatorio

      Cuándo se borró el registro.

  • next_cursorstring o nullobligatorio

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

  • has_morebooleanobligatorio

    true si hay una página siguiente.

  • sync_cursorstring o nullobligatorio

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

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
curl "https://api.saleya.app/v1/products" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "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-Keystring

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

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

Cuerpo de la solicitud application/json

  • namemapa de string o nullobligatorio

    Nombre 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 null

    Descripción breve por idioma, texto plano para las listas de productos.

    Largo máximo:
    500
  • descriptionmapa de string o null o null

    Descripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.

    Largo máximo:
    50000
  • slugstring

    Dirección del producto en la tienda online, única en la tienda.

    Largo máximo:
    160
  • brand_idinteger o null

    ID de la marca del producto; null si no está definida.

  • tax_class_idinteger o null

    ID 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 integer

    ID de las categorías del producto, en orden ascendente.

  • primary_category_idinteger o null

    La categoría principal entre category_ids; null si no se eligió una principal.

  • is_activeboolean

    false retira el producto de la venta y lo oculta de la tienda online.

  • published_atstring (date-time) o null

    Cuándo aparece el producto en la tienda online; null — de inmediato.

  • unpublished_atstring (date-time) o null

    Cuándo sale el producto de la tienda online; null — se queda.

  • sale_schedulearray de object o null

    Cuá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 integerobligatorio

      Dí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
    • fromstringobligatorio

      Inicio de la franja, «HH:MM» según el reloj del comercio.

      Patrón:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringobligatorio

      Fin 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$
  • typestring

    Tipo 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 null

    Unidad 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
    • unitstring

      Unidad 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 null

      Nombre 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 null

      Cuá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 null

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

  • variantsarray de objectobligatorio

    Lí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 null

      ID externo de la variante, su ID en tu sistema: la clave con la que se encuentra la línea.

    • skustring o null

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

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

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

      Largo máximo:
      255
    • priceintegerobligatorio

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

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

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

    • is_activeboolean

      false retira la variante de la venta.

    • positioninteger

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

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

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

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

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

      Valores:
      ARSUSDBRLCLPCOPMXNPENRUBnull
    • compare_at_priceinteger o null

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

      Máximo:
      10000000000
    • weight_gramsinteger o null

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

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

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

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

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

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

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

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

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

    • sale_ends_atstring (date-time) o null

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

    • sold_bystring

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

      Valores:
      eachweightvolume
    • price_per_quantitystring o null

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

      Largo máximo:
      32
    • measure_stepstring o null

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

      Largo máximo:
      32
    • min_measure_qtystring o null

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

      Largo máximo:
      32
    • max_measure_qtystring o null

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

      Largo máximo:
      32
    • net_contentobject

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

      Campos · 2
      • quantitystring

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

        Largo máximo:
        32
      • unitstring

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

        Valores:
        gml
    • barcodesarray de object o null

      Códigos de barras de la variante.

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

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

        Valores:
        ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
      • valuestringobligatorio

        El código de barras.

      • is_primaryboolean o null

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

Respuestas

201Creado

Encabezados

  • Idempotent-Replayedstring

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

    Valores:
    true
  • ETagstringobligatorio

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

    Ejemplo:
    "7"
  • Locationstring (uri)obligatorio

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

application/json

Devuelve Product

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
curl -X POST "https://api.saleya.app/v1/products" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — 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
        }
      ]
    }
  ]
}
Ejemplo de respuesta · 201
{
  "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

  • productintegerobligatorio

    ID del producto.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

    Versió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-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

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

Ejemplo de solicitud
curl "https://api.saleya.app/v1/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "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

  • productintegerobligatorio

    ID del producto.

Encabezado

  • Idempotency-Keystring

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

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

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

    Ejemplo:
    "7"

Cuerpo de la solicitud application/json

  • namemapa de string o null

    Nombre 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 null

    Descripción breve por idioma, texto plano para las listas de productos.

    Largo máximo:
    500
  • descriptionmapa de string o null o null

    Descripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.

    Largo máximo:
    50000
  • slugstring

    Dirección del producto en la tienda online, única en la tienda.

    Largo máximo:
    160
  • brand_idinteger o null

    ID de la marca del producto; null si no está definida.

  • tax_class_idinteger o null

    ID 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 integer

    ID de las categorías del producto, en orden ascendente.

  • primary_category_idinteger o null

    La categoría principal entre category_ids; null si no se eligió una principal.

  • is_activeboolean

    false retira el producto de la venta y lo oculta de la tienda online.

  • published_atstring (date-time) o null

    Cuándo aparece el producto en la tienda online; null — de inmediato.

  • unpublished_atstring (date-time) o null

    Cuándo sale el producto de la tienda online; null — se queda.

  • sale_schedulearray de object o null

    Cuá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 integerobligatorio

      Dí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
    • fromstringobligatorio

      Inicio de la franja, «HH:MM» según el reloj del comercio.

      Patrón:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringobligatorio

      Fin 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 null

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

  • variantsarray de object

    Lí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 null

      ID externo de la variante, su ID en tu sistema: la clave con la que se encuentra la línea.

    • skustring o null

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

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

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

      Largo máximo:
      255
    • priceinteger

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

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

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

    • is_activeboolean

      false retira la variante de la venta.

    • positioninteger

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

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

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

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

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

      Valores:
      ARSUSDBRLCLPCOPMXNPENRUBnull
    • compare_at_priceinteger o null

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

      Máximo:
      10000000000
    • weight_gramsinteger o null

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

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

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

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

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

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

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

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

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

    • sale_ends_atstring (date-time) o null

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

    • sold_bystring

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

      Valores:
      eachweightvolume
    • price_per_quantitystring o null

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

      Largo máximo:
      32
    • measure_stepstring o null

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

      Largo máximo:
      32
    • min_measure_qtystring o null

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

      Largo máximo:
      32
    • max_measure_qtystring o null

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

      Largo máximo:
      32
    • net_contentobject

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

      Campos · 2
      • quantitystring

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

        Largo máximo:
        32
      • unitstring

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

        Valores:
        gml
    • barcodesarray de object o null

      Códigos de barras de la variante.

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

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

        Valores:
        ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
      • valuestringobligatorio

        El código de barras.

      • is_primaryboolean o null

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

    • option_valuesarray de object

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

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

        ID de la opción en options del producto.

      • value_idintegerobligatorio

        ID del valor en values de esa opción.

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

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

    Valores:
    true
  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve Product

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

application/problem+json

Devuelve Problem

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

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

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

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
curl -X PATCH "https://api.saleya.app/v1/products/{product}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — 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
        }
      ]
    }
  ]
}
Ejemplo de respuesta · 200
{
  "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

  • productintegerobligatorio

    ID del producto.

Query

  • consentobject

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

    Campos · 4
    • recipe_ingredientstring

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

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

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

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

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

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

      El plan con suscripciones vigentes sale de la venta.

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

Encabezado

  • Idempotency-Keystring

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

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

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

    Ejemplo:
    "7"

Respuestas

204Éxito

Encabezados

  • Idempotent-Replayedstring

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

    Valores:
    true

Sin cuerpo

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

application/problem+json

Devuelve Problem

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

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

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

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
curl -X DELETE "https://api.saleya.app/v1/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_idstringobligatorio

    ID externo: el ID del registro en tu sistema.

Respuestas

200Éxito

Encabezados

  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve Product

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

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

Ejemplo de solicitud
curl "https://api.saleya.app/v1/products/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "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_idstringobligatorio

    ID externo: el ID del registro en tu sistema.

Encabezado

  • Idempotency-Keystring

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

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

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

    Ejemplo:
    "7"
  • If-None-Matchstring

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

    Valores:
    *

Cuerpo de la solicitud application/json

  • namemapa de string o null

    Nombre 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 null

    Descripción breve por idioma, texto plano para las listas de productos.

    Largo máximo:
    500
  • descriptionmapa de string o null o null

    Descripción por idioma en Markdown (GitHub Flavored): un objeto con los idiomas completados.

    Largo máximo:
    50000
  • slugstring

    Dirección del producto en la tienda online, única en la tienda.

    Largo máximo:
    160
  • brand_idinteger o null

    ID de la marca del producto; null si no está definida.

  • tax_class_idinteger o null

    ID 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 integer

    ID de las categorías del producto, en orden ascendente.

  • primary_category_idinteger o null

    La categoría principal entre category_ids; null si no se eligió una principal.

  • is_activeboolean

    false retira el producto de la venta y lo oculta de la tienda online.

  • published_atstring (date-time) o null

    Cuándo aparece el producto en la tienda online; null — de inmediato.

  • unpublished_atstring (date-time) o null

    Cuándo sale el producto de la tienda online; null — se queda.

  • sale_schedulearray de object o null

    Cuá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 integerobligatorio

      Dí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
    • fromstringobligatorio

      Inicio de la franja, «HH:MM» según el reloj del comercio.

      Patrón:
      ^(?:[01]\d|2[0-3]):[0-5]\d$|^24:00$
    • tostringobligatorio

      Fin 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$
  • typestring

    Tipo 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 null

    Unidad 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
    • unitstring

      Unidad 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 null

      Nombre 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 null

      Cuá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 object

    Lí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 null

      ID externo de la variante, su ID en tu sistema: la clave con la que se encuentra la línea.

    • skustring o null

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

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

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

      Largo máximo:
      255
    • priceinteger

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

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

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

    • is_activeboolean

      false retira la variante de la venta.

    • positioninteger

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

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

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

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

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

      Valores:
      ARSUSDBRLCLPCOPMXNPENRUBnull
    • compare_at_priceinteger o null

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

      Máximo:
      10000000000
    • weight_gramsinteger o null

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

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

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

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

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

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

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

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

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

    • sale_ends_atstring (date-time) o null

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

    • sold_bystring

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

      Valores:
      eachweightvolume
    • price_per_quantitystring o null

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

      Largo máximo:
      32
    • measure_stepstring o null

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

      Largo máximo:
      32
    • min_measure_qtystring o null

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

      Largo máximo:
      32
    • max_measure_qtystring o null

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

      Largo máximo:
      32
    • net_contentobject

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

      Campos · 2
      • quantitystring

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

        Largo máximo:
        32
      • unitstring

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

        Valores:
        gml
    • barcodesarray de object o null

      Códigos de barras de la variante.

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

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

        Valores:
        ean13ean8upcaupcecode128code39gtinitfqrdatamatrixother
      • valuestringobligatorio

        El código de barras.

      • is_primaryboolean o null

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

    • option_valuesarray de object

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

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

        ID de la opción en options del producto.

      • value_idintegerobligatorio

        ID del valor en values de esa opción.

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

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

    Valores:
    true
  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve Product

201Creado

Encabezados

  • Idempotent-Replayedstring

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

    Valores:
    true
  • ETagstringobligatorio

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

    Ejemplo:
    "7"
  • Locationstring (uri)obligatorio

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

application/json

Devuelve Product

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

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

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
curl -X PATCH "https://api.saleya.app/v1/products/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — body.json
{
  "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
        }
      ]
    }
  ]
}
Ejemplo de respuesta · 200
{
  "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

  • productintegerobligatorio

    ID del producto.

Query

  • consentobject

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

    Campos · 1
    • variant_axesstring

      Las 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-Keystring

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

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

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

    Ejemplo:
    "7"

Cuerpo de la solicitud application/json

  • optionsarray de objectobligatorio

    Opciones en las que difieren las variantes, como talle o color, en orden.

    Máximo de elementos:
    10
    Campos · 4
    • keystringobligatorio

      Clave 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 nullobligatorio

      Nombre de la opción por idioma.

      Largo máximo:
      120
    • valuesarray de objectobligatorio

      Valores de la opción en orden.

      Mínimo de elementos:
      1
      Máximo de elementos:
      50
      Campos · 3
      • valuemapa de string o nullobligatorio

        El valor por idioma, por ejemplo {"es": "Rojo", "en": "Red"}.

        Largo máximo:
        120
      • swatch_colorstring o null

        Color 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 null

        ID del valor. Las variantes lo nombran en option_values.

    • idinteger o null

      ID de la opción.

  • variantsarray de objectobligatorio

    Distribució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
    • idintegerobligatorio

      ID de la variante.

    • archiveboolean

      true — archivar la variante en lugar de darle valores.

    • value_indexesarray de integer

      Valores 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-Replayedstring

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

    Valores:
    true
  • ETagstringobligatorio

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

    Ejemplo:
    "7"

application/json

Devuelve Product

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

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

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

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

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

application/problem+json

Devuelve ForbiddenProblem

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

application/problem+json

Devuelve Problem

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

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve ConflictProblem

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

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

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

application/problem+json

Devuelve Problem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

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

Ejemplo de solicitud
curl -X PUT "https://api.saleya.app/v1/products/{product}/options" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Cuerpo de la solicitud — 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
      ]
    }
  ]
}
Ejemplo de respuesta · 200
{
  "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"
}