Ejemplo: productos

Ejemplo de listado, creación y actualización de productos con el SDK de TypeScript de La Pyme

Los métodos de productos viven en lapyme.products. Los nombres de campos del SDK son camelCase. El SDK convierte esos campos al contrato público snake_case antes de enviar la request.

Listar productos

import { Lapyme } from "lapyme";

const lapyme = new Lapyme({
  bearerAuth: process.env["LAPYME_API_KEY"] ?? "",
});

const products = await lapyme.products.list({
  limit: 20,
  query: "remera",
  productType: "product",
  isActive: true,
});

for (const product of products.result.data) {
  console.log(product.id, product.name, product.imageUrl);
}

imageUrl siempre está presente como string | null. Para productos con variantes, la imagen propia de la variante tiene prioridad. Si no tiene una, se devuelve la imagen general del producto. La URL es una referencia externa sin garantías de disponibilidad: La Pyme no descarga, copia ni aloja la imagen.

Crear un producto

Los importes monetarios se envían en centavos. Reutilizá el mismo idempotencyKey si tenés que reintentar la misma creación.

import { Lapyme } from "lapyme";

const lapyme = new Lapyme({
  bearerAuth: process.env["LAPYME_API_KEY"] ?? "",
});

const product = await lapyme.products.create({
  idempotencyKey: crypto.randomUUID(),
  body: {
    name: "Remera básica",
    sku: "REM-BASICA-M",
    productType: "product",
    imageUrl: "https://cdn.example.com/products/remera-basica.jpg",
    price: 1250000,
    cost: 700000,
    currency: "ARS",
  },
});

console.log(
  product.result.data.product.id,
  product.result.data.product.imageUrl,
);

Actualizar parcialmente un combo

PUT /api/v1/products/{product_id} acepta solo sku para renombrar un combo existente. Incluí Idempotency-Key y reutilizala al reintentar la misma solicitud. No necesitás enviar product_type ni components.

Las claves omitidas se conservan, incluidos composición, cantidades, modo de precio, precio manual y ajuste. Un cambio de SKU no recalcula el precio. Si enviás components, reemplaza la composición completa. Los campos pricing_mode, price o price_adjustment_percentage solicitan un cambio de precio. No podés convertir un producto común en combo con esta operación. MCP save_product también acepta el id existente y solo el nuevo sku.

Campos personalizados al crear y actualizar

Los campos personalizados de productos están incluidos en todos los planes de la oferta actual. Algunas organizaciones con contratos anteriores conservan condiciones distintas. Primero consultá GET /api/v1/products/metafield-definitions: la respuesta publica claves estables, tipos, validaciones y opciones configuradas, con el UUID de cada definición. Las definiciones y opciones deben existir antes de crear el producto.

const definitions = await fetch(
  "https://api.lapyme.com.ar/api/v1/products/metafield-definitions",
  { headers: { Authorization: `Bearer ${process.env.LAPYME_API_KEY}` } },
).then((response) => response.json());

const genesis = await lapyme.products.create({
  idempotencyKey: crypto.randomUUID(),
  body: {
    name: "Genesis",
    sku: "GENESIS",
    price: 1250000,
    metafields: [{ key: "MARCA", value: "vicus" }],
  },
});

console.log(definitions.data.definitions);
console.log(genesis.result.data.product.metafields);
// [{ key: "marca", value: "Vicus" }]

La clave se compara sin distinguir mayúsculas y minúsculas. Los valores select también se comparan así y la respuesta devuelve la opción con su escritura configurada. Los valores pertenecen al grupo: todas las variantes comparten los mismos campos. El listado de productos no los incluye. Consultá el detalle para leerlos.

Para cambiar o borrar valores después de crear, usá únicamente PATCH /api/v1/products/{product_id}/metafields. Un string asigna el valor, null lo borra y las claves omitidas no cambian. Un string vacío es inválido. Un campo obligatorio no se puede borrar.

await fetch(
  `https://api.lapyme.com.ar/api/v1/products/${genesis.result.data.product.id}/metafields`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.LAPYME_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      entries: [
        { key: "marca", value: "Otra" },
        { key: "temporada", value: null },
      ],
    }),
  },
);

PUT /api/v1/products/{product_id} no acepta metafields. Las etiquetas siguen teniendo su endpoint separado.

Crear un producto con variantes

Enviá entre una y tres opciones y hasta 250 variantes. Cada optionValues debe incluir exactamente un valor para cada nombre declarado en options. Los SKU y las combinaciones deben ser únicos dentro de la request y de la organización.

const shoe = await lapyme.products.create({
  idempotencyKey: crypto.randomUUID(),
  body: {
    name: "Zapatilla clásica",
    productType: "product",
    options: ["Material", "Color", "Talle"],
    variants: [
      {
        optionValues: {
          Material: "Cuero",
          Color: "Negro",
          Talle: "40",
        },
        sku: "ZAP-CUE-NEG-40",
        cost: 700000,
        price: 1250000,
        currency: "ARS",
        warehouseStocks: [
          {
            warehouseId: "550e8400-e29b-41d4-a716-446655440101",
            quantity: 5,
          },
        ],
      },
      {
        optionValues: {
          Material: "Lona",
          Color: "Blanco",
          Talle: "41",
        },
        sku: "ZAP-LON-BLA-41",
        cost: 650000,
        price: 1150000,
        currency: "ARS",
      },
    ],
  },
});

console.log(shoe.result.data.product.variantGroupId);

La respuesta mantiene el contrato de creación existente y devuelve en data.product la primera variante creada. Usá variantGroupId para identificar el producto que agrupa toda la matriz.

Crear y actualizar un combo

Un combo se crea con su composición completa en la misma request. Cada productId es el ID de una variante componente de la misma organización y quantity debe ser mayor que cero. No podés repetir componentes ni usar otro combo como componente.

const combo = await lapyme.products.create({
  idempotencyKey: crypto.randomUUID(),
  body: {
    productType: "combo",
    name: "Combo desayuno",
    sku: "COMBO-DESAYUNO",
    pricingMode: "automatic",
    priceAdjustmentPercentage: -10,
    components: [
      {
        productId: "550e8400-e29b-41d4-a716-446655440101",
        quantity: 2,
      },
      {
        productId: "550e8400-e29b-41d4-a716-446655440102",
        quantity: 1,
      },
    ],
  },
});

console.log(combo.result.data.product.components);

La Pyme crea el producto, el precio y los componentes de forma atómica. En modo manual, también enviá price en centavos. En modo automatic, el costo y el precio se calculan con los componentes y el ajuste opcional.

Para actualizar un combo existente, enviá productType: "combo" y la forma completa del combo a lapyme.products.update, incluida una lista no vacía de components. La lista nueva reemplaza toda la composición en una sola operación. No podés convertir un producto común en combo con una actualización. Creá un combo nuevo. El detalle y las respuestas de creación y actualización devuelven la composición guardada.

Actualizar precio

import { Lapyme } from "lapyme";

const lapyme = new Lapyme({
  bearerAuth: process.env["LAPYME_API_KEY"] ?? "",
});

const updated = await lapyme.products.update({
  productId: "9c692e8b-0f9a-4f7c-8b99-061a2eb188ae",
  body: {
    price: 1390000,
  },
});

console.log(updated.result.data.product.price);

Ajuste masivo

Usá lapyme.productBulkAdjustments.create para cambios masivos de precios o costos. Es una operación de escritura: mandá idempotencyKey.

import { Lapyme } from "lapyme";

const lapyme = new Lapyme({
  bearerAuth: process.env["LAPYME_API_KEY"] ?? "",
});

const adjustment = await lapyme.productBulkAdjustments.create({
  idempotencyKey: crypto.randomUUID(),
  body: {
    target: "price",
    operationType: "increase",
    adjustmentType: "percentage",
    adjustmentValue: 10,
    selection: {
      type: "specific",
      ids: ["9c692e8b-0f9a-4f7c-8b99-061a2eb188ae"],
    },
  },
});

console.log(adjustment.result.data.productBulkAdjustment.updated);

La forma exacta de selection y los campos disponibles para ajustes masivos están en la referencia de POST /api/v1/products/bulk-adjustments.

Guardar la estructura de variantes

PUT /api/v1/products/{product_id}/variants guarda los cambios de opciones y variantes en una sola transacción. product_id puede ser cualquier variante vigente del grupo. Incluí Idempotency-Key y reutilizala solo para reintentar el mismo cuerpo.

Las variantes omitidas se conservan. Una variante con id acepta cambios parciales; una nueva requiere option_values, sku, cost y price. Enviá hasta 32 variantes modificadas o retiradas por solicitud. La respuesta incluye todas las variantes vigentes con id, sku y option_values, y removed indica deleted o archived según sus referencias.

Si enviás options, incluí la lista completa y ordenada, con hasta tres opciones. Usá previous_name para renombrar sin cambiar los IDs ni los vínculos de las variantes. Una opción existente omitida debe figurar en remove_options; de lo contrario, la solicitud falla. Para agregar una opción, completá su valor en todas las variantes que conservás. Un producto simple se convierte en un grupo en la misma transacción cuando declarás sus opciones y completás la combinación de su variante existente.

option_values y rename_option_values usan los nombres finales de las opciones. Cada combinación debe tener exactamente un valor por opción y ser única. Los valores existen mientras alguna variante los usa: para dejar de usar uno, cambiá sus combinaciones o retirá sus variantes con remove_variants. Quitar una opción nunca retira variantes. Un componente de un combo activo no se puede retirar.

{
  "options": [{ "name": "Color", "previous_name": "Colour" }],
  "remove_options": ["Talle"],
  "rename_option_values": [{ "option": "Color", "from": "Rojo", "to": "Bordó" }],
  "variants": [
    { "id": "550e8400-e29b-41d4-a716-446655440101", "price": 1500000 },
    { "option_values": { "Color": "Azul" }, "sku": "REM-AZUL", "cost": 600000, "price": 1500000 }
  ],
  "remove_variants": ["550e8400-e29b-41d4-a716-446655440102"]
}

En MCP usá save_product con id y los campos options, variants, removeOptions, renameOptionValues o removeVariants. Los nombres son camelCase, incluido variants[].optionValues. Enviá otros campos generales del producto en una llamada separada. image_url conserva su comportamiento de enlace externo.

Filtrar y ordenar el catálogo

GET /api/v1/products acepta tag repetido con UUIDs de etiquetas o __untagged__ para productos sin etiqueta. Si combinás ambos, incluye los productos de cualquiera de esos grupos.

Usá metafield=marca:Vicus para filtrar por la clave publicada de un campo personalizado. Podés repetir el parámetro: los valores de una misma clave se combinan con OR; las claves distintas se combinan con AND. Los campos y las etiquetas pertenecen al grupo y alcanzan a todas sus variantes.

sort acepta product, category o sku; direction acepta asc o desc. El orden predeterminado es product ascendente. Conservá esos parámetros y los filtros al enviar el next_cursor de la página anterior. MCP list_products acepta los mismos filtros.

Cambiar el identificador del producto

La creación y la actualización de productos comunes aceptan handle. El servidor lo normaliza antes de guardar. En grupos con variantes, el identificador pertenece al grupo. MCP save_product también publica el campo.

Eliminar o archivar una variante

DELETE /api/v1/products/{product_id} requiere el scope products:write y Idempotency-Key. No lleva cuerpo. Actúa solo sobre la variante vendible indicada. Si no tiene referencias, devuelve data.status: "deleted". Si tiene referencias, la archiva y devuelve data.status: "archived" y data.references. Los componentes de combos activos no se pueden retirar: la respuesta es 400 con el detalle ACTIVE_COMBO_COMPONENT.

Reutilizá la misma clave para reintentar: devuelve el resultado guardado, incluso después de eliminar la fila. Una clave nueva para una variante que ya se eliminó devuelve 404. MCP delete_product realiza la misma operación y requiere products:read y products:write para resolver el producto antes de retirarlo.

Administrar definiciones de campos personalizados

Podés crear, actualizar y eliminar definiciones por API y MCP. Los campos personalizados deben estar incluidos en el contrato de la organización.

Recurso	Colección	Permiso de escritura
Productos	/api/v1/products/metafield-definitions	products:write
Variantes	/api/v1/products/variant-metafield-definitions	products:write
Clientes y contactos	/api/v1/customers/metafield-definitions	admin
Ventas	/api/v1/sales/metafield-definitions	admin

Usá POST en la colección para crear una definición, PUT en {colección}/{definition_id} para actualizarla y DELETE en ese mismo destino para eliminarla. Todas las escrituras requieren Idempotency-Key: reutilizá la misma clave y el mismo cuerpo para reintentar una operación. La respuesta incluye idempotent_replay.

Para crear, enviá name, field_type (text, number, date, select o boolean), y opcionalmente description y validations. La clave se genera desde el nombre; la respuesta devuelve definition.id y definition.key.

Las validaciones dependen del tipo: text acepta required, min_length y max_length; number acepta required, min y max; date acepta required; select acepta required y requiere una lista options sin repetidos; boolean usa un objeto vacío o required: false. Si actualizás validations, enviá el objeto completo. Los valores que ya estaban guardados no se modifican al editar una definición.

En una actualización, enviá solo name, description o validations. Los campos omitidos se conservan. Para vaciar la descripción, enviá null. La clave y el tipo no cambian. Las definiciones del sistema no se pueden editar ni eliminar.

Eliminar una definición también elimina todos sus valores guardados. La respuesta incluye deleted.id, deleted.deleted y deleted.deleted_value_count. Solo se elimina la definición que identificás con su UUID; omitirla de una solicitud no la elimina.

En MCP, usá save_metafield_definition con resourceType (product, variant, contact o sale): sin id crea una definición y con id la actualiza. Usá delete_metafield_definition con resourceType e id para eliminarla. La herramienta list_metafield_definitions devuelve los UUID de las definiciones de productos, o de variantes con resourceType: "variant". Las listas por API de clientes y ventas también permiten consultar sus UUID.

Campos personalizados de variantes

Un campo de variantes guarda un valor distinto en cada variante: por ejemplo, dos talles del mismo producto pueden tener pesos distintos. Los campos de productos y de variantes son definiciones separadas y no se heredan: el valor de un campo de producto no completa un campo de variante. Una clave existe como campo de productos o como campo de variantes, nunca como ambos.

Consultá las definiciones en GET /api/v1/products/variant-metafield-definitions. Para escribir valores, enviá metafields en cada variante de PUT /api/v1/products/{product_id}/variants:

{
  "variants": [
    {
      "id": "7c1f…",
      "metafields": [{ "key": "peso_gramos", "value": "250" }]
    },
    {
      "id": "9a2e…",
      "metafields": [{ "key": "peso_gramos", "value": null }]
    }
  ]
}

value: null borra el valor de esa variante. Si cada variante enviada tiene solo id y metafields, la matriz no cambia; así también podés cargar los campos de la única variante de un producto sin opciones. La respuesta devuelve los metafields actuales de cada variante del producto. Una clave de un campo de productos, o una definición de otra organización, se rechaza sin guardar ningún cambio de la matriz. GET /api/v1/products/{product_id} devuelve los campos de la variante en variant_metafields y los del producto en metafields.