# Gestión de emisores

Un **emisor** representa un RFC registrado ante el SAT que puede emitir comprobantes
fiscales a través de QRwey!.

Cada emisor está asociado a un **grupo** y puede tener uno o más **comercios** configurados
para facturar.

## Crear emisor

### Endpoint

```
POST /v1/qrs/issuers
```

**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 |
|  --- | --- |
| `groupId` | ID del grupo al que pertenece el emisor (requerido) |
| `alias` | Nombre corto o alias del emisor (requerido) |
| `taxId` | RFC del emisor (requerido) |
| `idCif` | Identificador de la Constancia de Situación Fiscal (requerido) |
| `businessName` | Razón social del emisor (requerido) |
| `email` | Correo electrónico del emisor (requerido) |
| `zip` | Código postal del domicilio fiscal (requerido) |
| `taxRegimeCode` | Clave del régimen fiscal SAT, ej. `601` (requerido) |


### Ejemplo de request (DEV)

```bash
curl -X POST "https://api-dev.qrwey.com/v1/qrs/issuers" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "grp_4aca0361cfcd41c097663db44008fbb9",
    "alias": "Estación Reforma",
    "taxId": "FUNK671228PH6",
    "idCif": "CIF123456789",
    "businessName": "KARLA FUENTE NOLASCO",
    "email": "facturacion@estacion-reforma.com",
    "zip": "06600",
    "taxRegimeCode": "601"
  }'
```

### Respuesta

```json
{
  "invoiceDataId": "inv_data_4aca0361cfcd41c097663db44008fbb9",
  "groupId": "grp_4aca0361cfcd41c097663db44008fbb9",
  "alias": "Estación Reforma",
  "taxId": "FUNK671228PH6",
  "idCif": "CIF123456789",
  "businessName": "KARLA FUENTE NOLASCO",
  "email": "facturacion@estacion-reforma.com",
  "zip": "06600",
  "taxRegime": {
    "code": "601",
    "description": "General de Ley Personas Morales"
  },
  "invoiceLogoUrl": "https://cdn.qrwey.com/logos/inv_data_4aca0361.png",
  "status": "ACTIVE"
}
```

## Actualizar emisor

### Endpoint

```
PUT /v1/qrs/issuers/{issuerId}
```

> ⚠️ Este endpoint usa `multipart/form-data` para permitir la carga del logotipo del emisor.


### Headers requeridos

```http
Authorization: Bearer {{access_token}}
Content-Type: multipart/form-data
```

### Campos del formulario

| Campo | Descripción |
|  --- | --- |
| `groupId` | ID del grupo al que pertenece (requerido) |
| `alias` | Nombre corto del emisor (requerido) |
| `email` | Correo electrónico (requerido) |
| `taxRegimeCode` | Clave del régimen fiscal SAT (requerido) |
| `status` | Estado del emisor: `ACTIVE` o `INACTIVE` (opcional) |
| `logo` | Archivo de imagen con el logotipo del emisor (opcional) |


### Ejemplo de request (DEV)

```bash
curl -X PUT "https://api-dev.qrwey.com/v1/qrs/issuers/inv_data_4aca0361cfcd41c097663db44008fbb9" \
  -H "Authorization: Bearer {{access_token}}" \
  -F "groupId=grp_4aca0361cfcd41c097663db44008fbb9" \
  -F "alias=Estación Reforma Actualizada" \
  -F "email=nuevo-correo@estacion-reforma.com" \
  -F "taxRegimeCode=601" \
  -F "logo=@/path/to/logo.png"
```

## Sincronizar emisor con el SAT

Sincroniza los datos del emisor con su **Constancia de Situación Fiscal (CSF)** del SAT.
Esto actualiza automáticamente la razón social, régimen fiscal y domicilio fiscal.

### Endpoint

```
POST /v1/qrs/issuers/{issuerId}/synchronize
```

### Headers requeridos

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

### Ejemplo de request (DEV)

```bash
curl -X POST "https://api-dev.qrwey.com/v1/qrs/issuers/inv_data_4aca0361cfcd41c097663db44008fbb9/synchronize" \
  -H "Authorization: Bearer {{access_token}}"
```

> ⚠️ La sincronización depende de la disponibilidad del servicio de CSF del SAT. Si el servicio no está disponible, la operación puede fallar.


## Listar emisores

### Endpoint

```
GET /v1/qrs/issuers
```

### Headers requeridos

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

### Query params

| Parámetro | Descripción |
|  --- | --- |
| `groupId` | Filtra emisores por grupo (opcional). Si se omite, devuelve todos los emisores del customer |
| `filter` | Texto para filtrar por nombre o RFC (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/issuers?groupId=grp_4aca0361cfcd41c097663db44008fbb9&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

## Obtener emisor por ID

### Endpoint

```
GET /v1/qrs/issuers/{issuerId}
```

### Headers requeridos

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

### Ejemplo de request (DEV)

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

## Errores comunes

| Código | Motivo |
|  --- | --- |
| 400 | Campos requeridos faltantes o invalidos |
| 401 | Token inválido o expirado |
| 404 | Emisor o grupo no encontrado, o no pertenece a tu cuenta |
| 409 | Ya existe un emisor con el mismo RFC en el grupo |


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

## Buenas prácticas

- Usa un alias descriptivo que facilite identificar al emisor
- Sincroniza periódicamente con el SAT para mantener los datos actualizados
- Verifica que el RFC y régimen fiscal coincidan con la Constancia de Situación Fiscal
- Un emisor puede tener múltiples comercios, pero cada comercio necesita sus propias llaves CSD


## ¿Qué sigue?

- Configura un comercio para el emisor: [Gestión de comercios](/guides/merchants)
- Timbra un CFDI: [Timbrar CFDI 4.0](/guides/stamp-cfdi)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)