# Catálogos SAT

Los **catálogos del SAT** proporcionan las claves oficiales necesarias para construir
CFDIs validos. Estos endpoints permiten consultar formas de pago, claves de unidad
y claves de producto/servicio directamente desde el API.

## Formas de pago

Obtiene el catálogo completo de formas de pago del SAT.

### Endpoint

```
GET /v1/qrs/sat-catalogs/payment-forms
```

**Host (DEV):**

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

**Host (PROD):**

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

### Headers requeridos

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

### Ejemplo de request (DEV)

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

### Respuesta

```json
[
  {
    "code": "01",
    "description": "Efectivo"
  },
  {
    "code": "03",
    "description": "Transferencia electrónica de fondos"
  },
  {
    "code": "04",
    "description": "Tarjeta de crédito"
  }
]
```

## Claves de unidad

Obtiene el catálogo paginado de claves de unidad del SAT con soporte de búsqueda.

### Endpoint

```
GET /v1/qrs/sat-catalogs/unit-keys
```

### Headers requeridos

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

### Query params

| Parámetro | Descripción |
|  --- | --- |
| `filter` | Texto para filtrar por clave o descripción (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/sat-catalogs/unit-keys?filter=litro&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "content": [
    {
      "code": "LTR",
      "description": "Litro"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 10
}
```

## Productos y servicios

Obtiene el catálogo paginado de claves de producto/servicio del SAT con soporte de búsqueda.

### Endpoint

```
GET /v1/qrs/sat-catalogs/product-services
```

### Headers requeridos

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

### Query params

| Parámetro | Descripción |
|  --- | --- |
| `filter` | Texto para filtrar por clave o descripción (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/sat-catalogs/product-services?filter=gasolina&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "content": [
    {
      "code": "15101515",
      "description": "Gasolina"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 10
}
```

## Permisos de operación EDS

Obtiene el catálogo de permisos de operación de estaciones de servicio del SAT.

### Endpoint

```
GET /v1/qrs/sat-catalogs/eds-operating-permits
```

### Headers requeridos

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

### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/sat-catalogs/eds-operating-permits" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
[
  {
    "type": "PER01",
    "description": "Expendio en estaciones de servicio de petrolíferos",
    "nomenclature": "PL/(N Consecutivo)/EXP/ES/(Año)",
    "regex": "PL/[0-9]{3,20}/EXP/ES/[0-9]{4}"
  },
  {
    "type": "PER03",
    "description": "Distribución por otros medios distintos a ducto",
    "nomenclature": "PL/(N Consecutivo)/DIS/OM/(Año)",
    "regex": "PL/[0-9]{3,20}/DIS/OM/[0-9]{4}"
  }
]
```

## Motivos de cancelación

Obtiene el catálogo de motivos de cancelación de CFDI del SAT.

### Endpoint

```
GET /v1/qrs/sat-catalogs/cancellation-reasons
```

### Headers requeridos

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

### Ejemplo de request (DEV)

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

### Respuesta

```json
[
  {
    "code": "01",
    "description": "Comprobantes emitidos con errores con relación"
  },
  {
    "code": "02",
    "description": "Comprobantes emitidos con errores sin relación"
  },
  {
    "code": "03",
    "description": "No se llevó a cabo la operación"
  },
  {
    "code": "04",
    "description": "Operación nominativa relacionada en la factura global"
  }
]
```

## Errores comunes

| Código | Motivo |
|  --- | --- |
| 401 | Token inválido o expirado |


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

## Buenas prácticas

- Usa el parámetro `filter` para buscar claves específicas en lugar de recorrer todo el catálogo
- Cachea los resultados de formas de pago ya que cambian con poca frecuencia
- Para claves de unidad y producto/servicio, usa paginación para manejar el gran volumen de registros


## ¿Qué sigue?

- Timbra un CFDI con las claves correctas: [Timbrar CFDI 4.0](/guides/stamp-cfdi)
- Consulta planes de facturación: [Planes de facturación](/guides/budget-plans)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)