# Catálogos de retenciones y plataformas tecnológicas

> `GET https://api.cfdi.express/v1/catalogs/retenciones/{catalog}` — Un catálogo del SAT por llamada: tipo de servicio, subtipo, forma de pago del servicio, periodicidad, tipo de pago de la retención y entidad federativa.

URL de esta página: https://cfdi.express/docs/api/catalogo-retenciones
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)
Header `x-account-id`: indica la cuenta. Si no eres miembro, la respuesta es 403.

Desde la v1.43.0. Sirve las claves de [POST /v1/retenciones](https://cfdi.express/docs/api/timbrar-retencion). Cada llamada pide un catálogo: `tipo-servicio` (c_TipoDeServ), `subtipo-servicio` (c_SubTipoServ), `forma-pago-servicio` (c_FormaPagoServ), `periodicidad` (c_Periodicidad), `tipo-pago-retencion` (c_TipoPagoRet) o `entidad-federativa` (c_EntidadesFederativas).

### Parámetros de ruta

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `catalog` | string | sí | tipo-servicio, subtipo-servicio, forma-pago-servicio, periodicidad, tipo-pago-retencion o entidad-federativa. |

## Ejemplos

### cURL

```bash
curl https://api.cfdi.express/v1/catalogs/retenciones/tipo-servicio \
  -H "Authorization: Bearer sk_test_..."
```

## Respuesta

### 200 OK

```json
{
  "object": "list",
  "data": [
    { "clave": "05", "nombre": "Comercio de bienes" },
    { "clave": "06", "nombre": "Otro tipo de servicios" }
  ]
}
```

## Errores

| Status | code | Cuándo aparece |
|---|---|---|
| 401 | `unauthorized` | Falta el header Authorization o la llave es inválida. |
| 429 | `rate_limited` | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |

## Notas

- Cada entrada trae `clave` y `nombre`. El ejemplo muestra dos claves de `tipo-servicio`; la lista completa la devuelve el endpoint. Por MCP, `get_catalog` pide el mismo catálogo como `retenciones/tipo-servicio` (y `retenciones/forma-pago-servicio`, `retenciones/periodicidad`, `retenciones/subtipo-servicio`, `retenciones/tipo-pago-retencion`, `retenciones/entidad-federativa`).

## Relacionados

- [POST /v1/retenciones](https://cfdi.express/docs/api/timbrar-retencion) — Timbrar retención
- [GET /v1/catalogs/formas-pago](https://cfdi.express/docs/api/catalogo-formas-pago) — Formas de pago

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express