# Gestión de Clientes

La **Gestión de Clientes** de QRwey! permite a los **Integradores** gestionar de forma
autónoma su configuración de facturación y timbrar CFDIs directamente a través del API.

> Un **Integrador** es quien tiene la relación comercial con QRwey!: crea grupos, da de alta
emisores (RFCs ante el SAT) y registra los comercios bajo cada emisor. A cada comercio le
emite una `X-API-Key` que el comercio usa desde su backend para los endpoints de
generación y resolución de QR.


A diferencia de los endpoints de operación de QR (consumidos por los **Comercios** con
`X-API-Key`), los endpoints de la Gestión de Clientes utilizan autenticación mediante
**Bearer token** (OAuth 2.0) y están dirigidos a los Integradores.

## Capacidades

Con la Gestión de Clientes puedes:

- Crear y administrar **grupos** para organizar tus emisores
- Registrar y sincronizar **emisores** (RFCs) con el SAT
- Configurar **comercios** con sus llaves CSD para facturar
- Mantener el **catálogo de productos** de cada comercio
- **Timbrar CFDIs 4.0** directamente: facturas de ingreso, notas de crédito y complementos de pago
- Consultar **transacciones** y **reportes de consumo**
- Administrar **planes de facturación**


## Autenticación

Todos los endpoints de la Gestión de Clientes requieren un Bearer token válido:

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

El token se obtiene mediante el flujo OAuth 2.0 de client credentials configurado
en tu cuenta de QRwey!. Consulta el paso a paso en
[Obtener un token de acceso (Integradores)](/guides/authentication#obtener-un-token-de-acceso-integradores).

> ⚠️ No uses API Keys para estos endpoints. Solo se acepta **Bearer token**.


## Estructura de recursos

Los recursos de la Gestión de Clientes siguen una jerarquía lógica:

```
Integrador (tu cuenta)
  └── Grupo
       └── Emisor (RFC)
            └── Comercio
                 ├── Llaves CSD (invoice-mode)
                 ├── API Key (consumida por el Comercio en los endpoints de QR)
                 └── Transacciones
```

- Un **grupo** agrupa uno o más emisores
- Un **emisor** representa un RFC registrado ante el SAT
- Un **comercio** es un punto de venta asociado a un emisor, con sus propias llaves CSD


## Endpoints disponibles

### Gestión de recursos

| Recurso | Guia |
|  --- | --- |
| Grupos | [Gestión de grupos](/guides/groups) |
| Emisores | [Gestión de emisores](/guides/issuers) |
| Comercios | [Gestión de comercios](/guides/merchants) |
| Productos | [Catálogo de productos del comercio](/guides/merchant-products) |
| Transacciones | [Gestión de transacciones](/guides/transactions) |
| Reportes | [Reportes del cliente](/guides/customer-reports) |


### Facturación

| Operación | Guia |
|  --- | --- |
| Factura de ingreso (tipo I) | [Timbrar CFDI 4.0](/guides/stamp-cfdi) |
| Nota de crédito (tipo E) | [Notas de crédito](/guides/credit-notes) |
| Complemento de pago (tipo P) | [Complementos de pago](/guides/payment-complements) |
| Consulta de facturas | [Consulta de facturas](/guides/invoice-list) |
| Detalle de CFDI | [Detalle de CFDI](/guides/cfdi-detail) |
| Cancelar CFDI | [Cancelar CFDI 4.0](/guides/cancel-cfdi) |
| Consultar estatus de CFDI | [Consultar estatus](/guides/cfdi-status) |


### Catálogos y planes

| Recurso | Guia |
|  --- | --- |
| Catálogos SAT | [Catálogos SAT](/guides/sat-catalogs) |
| Planes de facturación | [Planes de facturación](/guides/budget-plans) |


## Base URL

**DEV:**

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

**PROD:**

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

## Paginación

Los endpoints que devuelven listas soportan paginación mediante query params:

| Parámetro | Descripción |
|  --- | --- |
| `page` | Número de página (inicia en 0) |
| `size` | Elementos por página (default 20) |
| `sort` | Campo y dirección de ordenamiento (ej. `createdAt,desc`) |


## Errores comunes

| Código | Motivo |
|  --- | --- |
| 401 | Token inválido o expirado |
| 403 | No tienes permisos sobre el recurso solicitado |
| 404 | Recurso no encontrado o no pertenece a tu cuenta |
| 409 | Conflicto, el recurso ya existe |
| 422 | Error de reglas de negocio |


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

## ¿Qué sigue?

- Organiza tus emisores: [Gestión de grupos](/guides/groups)
- Registra un RFC: [Gestión de emisores](/guides/issuers)
- Configura un punto de venta: [Gestión de comercios](/guides/merchants)
- Timbra tu primer CFDI: [Timbrar CFDI 4.0](/guides/stamp-cfdi)