# Gestión de grupos

Un **grupo** es una unidad organizativa que te permite agrupar uno o más **emisores** (RFCs)
dentro de tu cuenta de QRwey!.

Los grupos son útiles para:

- Separar emisores por razón social, sucursal o línea de negocio
- Organizar la estructura de facturación de tu empresa


## Crear grupo

### Endpoint

```
POST /v1/qrs/groups
```

**Host (DEV):**

```
https://api-dev.qrwey.com
```

**Host (PROD):**

```
https://api.qrwey.com
```

### Headers requeridos

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

### Request body

| Campo | Descripción |
|  --- | --- |
| `name` | Nombre del grupo (requerido) |
| `description` | Descripción opcional del grupo |


### Campos de la respuesta

| Campo | Descripción |
|  --- | --- |
| `groupId` | Identificador único del grupo |
| `name` | Nombre del grupo |
| `description` | Descripción del grupo |
| `status` | Estado del grupo: `ACTIVE` o `INACTIVE` |
| `assignationsCount` | Número de emisores asignados al grupo |


### Ejemplo de request (DEV)

```bash
curl -X POST "https://api-dev.qrwey.com/v1/qrs/groups" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gasolineras Norte",
    "description": "Grupo de estaciones de servicio en la zona norte"
  }'
```

### Respuesta

```json
{
  "groupId": "grp_4aca0361cfcd41c097663db44008fbb9",
  "name": "Gasolineras Norte",
  "description": "Grupo de estaciones de servicio en la zona norte",
  "status": "ACTIVE",
  "assignationsCount": 3
}
```

## Actualizar grupo

### Endpoint

```
PUT /v1/qrs/groups/{groupId}
```

### Headers requeridos

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

### Request body

| Campo | Descripción |
|  --- | --- |
| `name` | Nuevo nombre del grupo (requerido) |
| `description` | Nueva descripción del grupo |


### Ejemplo de request (DEV)

```bash
curl -X PUT "https://api-dev.qrwey.com/v1/qrs/groups/grp_4aca0361cfcd41c097663db44008fbb9" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gasolineras Norte Actualizado",
    "description": "Grupo de estaciones actualizado"
  }'
```

## Listar grupos

### Endpoint

```
GET /v1/qrs/groups
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Query params

| Parámetro | Descripción |
|  --- | --- |
| `filter` | Texto para filtrar grupos por nombre (default: vacío) |
| `page` | Número de página (default: 0) |
| `size` | Elementos por página (default: 20) |


### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/groups?filter=norte&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "content": [
    {
      "groupId": "grp_4aca0361cfcd41c097663db44008fbb9",
      "name": "Gasolineras Norte",
      "description": "Grupo de estaciones de servicio en la zona norte",
      "status": "ACTIVE",
      "assignationsCount": 3
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 10
}
```

## Obtener grupo por ID

### Endpoint

```
GET /v1/qrs/groups/{groupId}
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Ejemplo de request (DEV)

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

## Errores comunes

| Código | Motivo |
|  --- | --- |
| 400 | El campo `name` es requerido o está vacío |
| 401 | Token inválido o expirado |
| 404 | Grupo no encontrado o no pertenece a tu cuenta |


Consulta: [Manejo de errores](/guides/error-handling)

## Buenas prácticas

- Usa nombres descriptivos que identifiquen claramente la agrupación de emisores
- Cada grupo debe representar una unidad lógica de negocio
- Consulta los grupos existentes antes de crear uno nuevo para evitar duplicados


## ¿Qué sigue?

- Registra un emisor en tu grupo: [Gestión de emisores](/guides/issuers)
- Configura un comercio: [Gestión de comercios](/guides/merchants)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)