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ámetro	Descripción
`merchantId`	ID del comercio (requerido)

Campos de CreateMerchantProductRequest

Campo	Descripción
`sku`	Identificador único de producto (SKU) para control interno del comercio (requerido)
`satProductServiceCode`	Clave de Producto/Servicio según el catálogo del SAT (requerido)
`description`	Descripción del producto o servicio (requerido)
`satUnitCode`	Clave de Unidad según el catálogo del SAT (requerido)
`unitPrice`	Precio 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ámetro	Descripción
`merchantId`	ID del comercio (requerido)

Query params

Parámetro	Descripción
`search`	Texto para filtrar por SKU o descripción del producto (opcional)
`page`	Número de página (default: 0)
`size`	Elementos por página (default: 20)
`sort`	Campo 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

Campo	Descripción
`merchantProductId`	Identificador único del producto en el catálogo
`merchantId`	ID del comercio dueño del producto
`sku`	Identificador interno del producto (SKU)
`satProductServiceCode`	Clave de Producto/Servicio del SAT
`satProductServiceDescription`	Descripción de la clave de Producto/Servicio del SAT
`description`	Descripción del producto o servicio
`satUnitCode`	Clave de Unidad del SAT
`satUnitDescription`	Descripción de la clave de Unidad del SAT
`unitPrice`	Precio unitario del producto
`status`	Estatus 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ámetro	Descripción
`merchantId`	ID del comercio (requerido)
`merchantProductId`	ID 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ámetro	Descripción
`merchantId`	ID del comercio (requerido)
`merchantProductId`	ID del producto del comercio (requerido)

Campos de UpdateMerchantProductRequest

Campo	Descripción
`merchantProductId`	ID del producto que se actualiza (requerido)
`sku`	Identificador interno del producto (SKU) (requerido)
`satProductServiceCode`	Clave de Producto/Servicio del SAT (requerido)
`description`	Descripción del producto o servicio (requerido)
`satUnitCode`	Clave de Unidad del SAT (requerido)
`unitPrice`	Precio unitario del producto. Debe ser mayor a cero (requerido)
`status`	Estatus 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ódigo	Motivo
400	Parámetros inválidos (SKU o claves del SAT faltantes, `unitPrice` menor o igual a cero)
401	Token inválido o expirado
404	Producto 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?

Administra los comercios: Gestión de comercios
Consulta transacciones: Gestión de transacciones
Vuelve al índice: Gestión de Clientes

Catálogo de productos del comercio

Crear productos

Endpoint

Headers requeridos

Path params

Campos de CreateMerchantProductRequest

Ejemplo de request (DEV)

Respuesta

Listar productos

Endpoint

Headers requeridos

Path params

Query params

Ejemplo de request (DEV)

Respuesta

Campos de MerchantProductResponse

Obtener producto por ID

Endpoint

Headers requeridos

Path params

Ejemplo de request (DEV)

Respuesta

Actualizar producto

Endpoint

Headers requeridos

Path params

Campos de UpdateMerchantProductRequest

Ejemplo de request (DEV)

Respuesta

Errores comunes

Buenas prácticas

¿Qué sigue?

Was this helpful?