# 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

```http
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)

```bash
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

```json
[
  {
    "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

```http
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)

```bash
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

```json
{
  "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

```http
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)

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

### Respuesta

```json
{
  "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

```http
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)

```bash
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

```json
{
  "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](/guides/error-handling)

## 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](/guides/sat-catalogs)
- 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](/guides/merchants)
- Consulta transacciones: [Gestión de transacciones](/guides/transactions)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)