> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbrix.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# SAT Catalogs

> Public endpoints to query SAT CFDI 4.0 catalog data — tax systems (regímenes fiscales) and CFDI uses (usos CFDI)

These endpoints require no authentication and return static catalog data from the SAT CFDI 4.0 spec. Use them to populate dropdowns, validate inputs client-side, or filter valid combinations before creating a customer.

## GET /sat/regimenes-fiscales

Returns all valid tax system codes (Régimen Fiscal) from the SAT catalog, optionally filtered by persona type.

### Query Parameters

| Parameter     | Type                                 | Required | Description                                                                |
| ------------- | ------------------------------------ | -------- | -------------------------------------------------------------------------- |
| `tipoPersona` | `"fisica"` \| `"moral"` \| `"ambas"` | No       | Filter by the type of taxpayer the régimen applies to. Omit to return all. |

### Example Request

```bash theme={null}
curl -X GET "https://api.timbrix.com/sat/regimenes-fiscales?tipoPersona=moral"
```

```typescript theme={null}
const regimenes = await timbrix.sat.regimenes({ tipoPersona: "moral" })
console.log(regimenes)
```

### Example Response

```json theme={null}
[
  {
    "codigo": "601",
    "descripcion": "General de Ley Personas Morales",
    "tipoPersona": "moral"
  },
  {
    "codigo": "603",
    "descripcion": "Personas Morales con Fines no Lucrativos",
    "tipoPersona": "moral"
  }
]
```

***

## GET /sat/usos-cfdi

Returns all valid CFDI use codes (Uso CFDI) from the SAT catalog, optionally filtered by persona type or régimen.

### Query Parameters

| Parameter     | Type                                 | Required | Description                                                                                 |
| ------------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------- |
| `tipoPersona` | `"fisica"` \| `"moral"` \| `"ambas"` | No       | Filter by the type of taxpayer the uso applies to. Omit to return all.                      |
| `regimen`     | string                               | No       | Filter by compatible régimen code (e.g. `"601"`). Returns only usos valid for that régimen. |

### Example Request

```bash theme={null}
curl -X GET "https://api.timbrix.com/sat/usos-cfdi?tipoPersona=ambas&regimen=601"
```

```typescript theme={null}
const usos = await timbrix.sat.usosCfdi({
  tipoPersona: "ambas",
  regimen: "601",
})
console.log(usos)
```

### Example Response

```json theme={null}
[
  {
    "codigo": "G01",
    "descripcion": "Adquisición de mercancias.",
    "tipoPersona": "ambas"
  },
  {
    "codigo": "G03",
    "descripcion": "Gastos en general.",
    "tipoPersona": "ambas"
  }
]
```

***

## Response Shape

Both endpoints return an array of objects with the same structure:

| Field         | Type                                 | Description                                     |
| ------------- | ------------------------------------ | ----------------------------------------------- |
| `codigo`      | string                               | SAT catalog code (e.g. `"601"`, `"G03"`)        |
| `descripcion` | string                               | Human-readable description from the SAT catalog |
| `tipoPersona` | `"fisica"` \| `"moral"` \| `"ambas"` | Taxpayer type(s) this code applies to           |

***

## Common Errors

### 400 Bad Request

Invalid value for `tipoPersona` (must be `"fisica"`, `"moral"`, or `"ambas"`).

```json theme={null}
{
  "statusCode": 400,
  "message": "tipoPersona must be one of: fisica, moral, ambas",
  "error": "BAD_REQUEST"
}
```