Skip to content
Last updated

Catálogo de productos del comercio

Cada comercio puede mantener un catálogo de productos reutilizable. Estos productos se identifican por su sku y guardan las claves del SAT (producto/servicio y unidad) junto con el precio unitario, de modo que puedan referenciarse al generar transacciones y facturas.

Todas las operaciones de este recurso pertenecen a la Gestión de Clientes y se autentican con Authorization: Bearer {{access_token}}.

Crear productos

Registra uno o más productos en el catálogo de un comercio. El cuerpo es una lista, por lo que puedes crear varios productos en una sola petición.

Endpoint

POST /v1/qrs/merchants/{merchantId}/products

Host (DEV):

https://api-dev.qrwey.com

Host (PROD):

https://api.qrwey.com

Headers requeridos

Authorization: Bearer {{access_token}}
Content-Type: application/json

Path params

ParámetroDescripción
merchantIdID del comercio (requerido)

Campos de CreateMerchantProductRequest

CampoDescripción
skuIdentificador único de producto (SKU) para control interno del comercio (requerido)
satProductServiceCodeClave de Producto/Servicio según el catálogo del SAT (requerido)
descriptionDescripción del producto o servicio (requerido)
satUnitCodeClave de Unidad según el catálogo del SAT (requerido)
unitPricePrecio unitario del producto. Debe ser mayor a cero (requerido)

Ejemplo de request (DEV)

curl -X POST "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/products" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "sku": "GAS87",
      "satProductServiceCode": "15101515",
      "description": "Gasolina Magna",
      "satUnitCode": "LTR",
      "unitPrice": 20.325
    }
  ]'

Respuesta

[
  {
    "merchantProductId": "prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b",
    "merchantId": "mer_4aca0361cfcd41c097663db44008fbb9",
    "sku": "GAS87",
    "satProductServiceCode": "15101515",
    "satProductServiceDescription": "Gasolina",
    "description": "Gasolina Magna",
    "satUnitCode": "LTR",
    "satUnitDescription": "Litro",
    "unitPrice": 20.325,
    "status": "ACTIVE"
  }
]

Listar productos

Devuelve una lista paginada de los productos del catálogo de un comercio, con filtro opcional por SKU o descripción.

Endpoint

GET /v1/qrs/merchants/{merchantId}/products

Headers requeridos

Authorization: Bearer {{access_token}}

Path params

ParámetroDescripción
merchantIdID del comercio (requerido)

Query params

ParámetroDescripción
searchTexto para filtrar por SKU o descripción del producto (opcional)
pageNúmero de página (default: 0)
sizeElementos por página (default: 20)
sortCampo y dirección de ordenamiento (ej. createdAt,desc)

Ejemplo de request (DEV)

curl -X GET "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/products?search=GAS&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"

Respuesta

{
  "content": [
    {
      "merchantProductId": "prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b",
      "merchantId": "mer_4aca0361cfcd41c097663db44008fbb9",
      "sku": "GAS87",
      "satProductServiceCode": "15101515",
      "satProductServiceDescription": "Gasolina",
      "description": "Gasolina Magna",
      "satUnitCode": "LTR",
      "satUnitDescription": "Litro",
      "unitPrice": 20.325,
      "status": "ACTIVE"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 10
}

Campos de MerchantProductResponse

CampoDescripción
merchantProductIdIdentificador único del producto en el catálogo
merchantIdID del comercio dueño del producto
skuIdentificador interno del producto (SKU)
satProductServiceCodeClave de Producto/Servicio del SAT
satProductServiceDescriptionDescripción de la clave de Producto/Servicio del SAT
descriptionDescripción del producto o servicio
satUnitCodeClave de Unidad del SAT
satUnitDescriptionDescripción de la clave de Unidad del SAT
unitPricePrecio unitario del producto
statusEstatus del producto: ACTIVE, INACTIVE

Obtener producto por ID

Endpoint

GET /v1/qrs/merchants/{merchantId}/products/{merchantProductId}

Headers requeridos

Authorization: Bearer {{access_token}}

Path params

ParámetroDescripción
merchantIdID del comercio (requerido)
merchantProductIdID del producto del comercio (requerido)

Ejemplo de request (DEV)

curl -X GET "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/products/prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b" \
  -H "Authorization: Bearer {{access_token}}"

Respuesta

{
  "merchantProductId": "prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b",
  "merchantId": "mer_4aca0361cfcd41c097663db44008fbb9",
  "sku": "GAS87",
  "satProductServiceCode": "15101515",
  "satProductServiceDescription": "Gasolina",
  "description": "Gasolina Magna",
  "satUnitCode": "LTR",
  "satUnitDescription": "Litro",
  "unitPrice": 20.325,
  "status": "ACTIVE"
}

Actualizar producto

Actualiza los datos de un producto existente, incluyendo su estatus. El campo merchantProductId debe enviarse también en el cuerpo de la petición.

Endpoint

PUT /v1/qrs/merchants/{merchantId}/products/{merchantProductId}

Headers requeridos

Authorization: Bearer {{access_token}}
Content-Type: application/json

Path params

ParámetroDescripción
merchantIdID del comercio (requerido)
merchantProductIdID del producto del comercio (requerido)

Campos de UpdateMerchantProductRequest

CampoDescripción
merchantProductIdID del producto que se actualiza (requerido)
skuIdentificador interno del producto (SKU) (requerido)
satProductServiceCodeClave de Producto/Servicio del SAT (requerido)
descriptionDescripción del producto o servicio (requerido)
satUnitCodeClave de Unidad del SAT (requerido)
unitPricePrecio unitario del producto. Debe ser mayor a cero (requerido)
statusEstatus del producto: ACTIVE, INACTIVE (requerido)

Ejemplo de request (DEV)

curl -X PUT "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/products/prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantProductId": "prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b",
    "sku": "GAS87",
    "satProductServiceCode": "15101515",
    "description": "Gasolina Magna",
    "satUnitCode": "LTR",
    "unitPrice": 21.100,
    "status": "ACTIVE"
  }'

Respuesta

{
  "merchantProductId": "prod_9f3b2a17c4e84d6f8a1b2c3d4e5f6a7b",
  "merchantId": "mer_4aca0361cfcd41c097663db44008fbb9",
  "sku": "GAS87",
  "satProductServiceCode": "15101515",
  "satProductServiceDescription": "Gasolina",
  "description": "Gasolina Magna",
  "satUnitCode": "LTR",
  "satUnitDescription": "Litro",
  "unitPrice": 21.100,
  "status": "ACTIVE"
}

Errores comunes

CódigoMotivo
400Parámetros inválidos (SKU o claves del SAT faltantes, unitPrice menor o igual a cero)
401Token inválido o expirado
404Producto o comercio no encontrado, o no pertenece a tu cuenta

Consulta: Manejo de errores

Buenas prácticas

  • Mantén el sku consistente con tu sistema interno para conciliar inventario y facturación
  • Usa claves del SAT válidas; consúltalas en Catálogos del SAT
  • Marca como INACTIVE los productos que dejes de vender en lugar de eliminarlos, para conservar su historial

¿Qué sigue?