SAT Catalogs

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

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

curl -X GET "https://api.timbrix.mx/sat/regimenes-fiscales?tipoPersona=moral"

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

Example Response

[
  {
    "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

curl -X GET "https://api.timbrix.mx/sat/usos-cfdi?tipoPersona=ambas&regimen=601"

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

Example Response

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

Response Shape

Both endpoints above 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

GET /sat/claves-prod-serv

Searches the SAT product/service key catalog (c_ClaveProdServ, ~52,500 entries) by partial text. Because this catalog is too large to return in full, results are matched server-side against the q term and ranked by relevance — use this endpoint to power a type-ahead search when a user creates or imports a product, rather than trying to load the whole catalog client-side.

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Partial text search term, matched against the código or descripción.
`limit`	integer	No	Max results to return, `1`–`50`. Defaults to `20`.

Example Request

curl -X GET "https://api.timbrix.mx/sat/claves-prod-serv?q=ukelele&limit=5"

const result = await timbrix.sat.searchClavesProdServ({
  q: "ukelele",
  limit: 5,
})
console.log(result.data, result.total)

Example Response

{
  "data": [
    {
      "codigo": "60131324",
      "descripcion": "Ukeleles",
      "incluyeIvaTrasladado": false,
      "incluyeIepsTrasladado": false
    }
  ],
  "total": 1
}

Field	Type	Description
`data`	array	Matching keys, limited by `limit`
`data[].codigo`	string	SAT product/service key
`data[].descripcion`	string	Description of the key
`data[].incluyeIvaTrasladado`	boolean	Whether the key includes transferred IVA by definition
`data[].incluyeIepsTrasladado`	boolean	Whether the key includes transferred IEPS by definition
`total`	integer	Total matches before `limit` is applied

GET /sat/claves-unidad

Searches the SAT unit-of-measure catalog (c_ClaveUnidad, ~2,400 entries) by partial text. Same search behavior as claves-prod-serv, matched against the código, nombre, or descripción.

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Partial text search term, matched against código, nombre, or descripción.
`limit`	integer	No	Max results to return, `1`–`100`. Defaults to `20`.

Example Request

curl -X GET "https://api.timbrix.mx/sat/claves-unidad?q=pieza&limit=5"

const result = await timbrix.sat.searchClavesUnidad({ q: "pieza", limit: 5 })
console.log(result.data, result.total)

Example Response

{
  "data": [
    {
      "codigo": "H87",
      "nombre": "Pieza",
      "descripcion": "Pieza",
      "simbolo": "H87"
    }
  ],
  "total": 1
}

Field	Type	Description
`data`	array	Matching units, limited by `limit`
`data[].codigo`	string	SAT unit of measure key
`data[].nombre`	string	Unit name
`data[].descripcion`	string	Unit description
`data[].simbolo`	string \| null	Unit symbol, if applicable
`total`	integer	Total matches before `limit` is applied

Common Errors

400 Bad Request

Invalid value for tipoPersona (must be "fisica", "moral", or "ambas") on /sat/regimenes-fiscales or /sat/usos-cfdi.

{
  "statusCode": 400,
  "message": "tipoPersona must be one of: fisica, moral, ambas",
  "error": "BAD_REQUEST"
}

limit out of range (must be between the endpoint’s allowed minimum and maximum) on /sat/claves-prod-serv or /sat/claves-unidad.

{
  "statusCode": 400,
  "message": ["limit must not be greater than 50"],
  "error": "Bad Request"
}

API documentation

Organizations

Members

Invites

Auth

OAuth

Customers

Invoices

Products

Users

Webhooks

API Keys

SAT Catalogs

GET /sat/regimenes-fiscales

Query Parameters

Example Request

Example Response

GET /sat/usos-cfdi

Query Parameters

Example Request

Example Response

Response Shape

GET /sat/claves-prod-serv

Query Parameters

Example Request

Example Response

GET /sat/claves-unidad

Query Parameters

Example Request

Example Response

Common Errors

400 Bad Request

​GET /sat/regimenes-fiscales

​Query Parameters

​Example Request

​Example Response

​GET /sat/usos-cfdi

​Query Parameters

​Example Request

​Example Response

​Response Shape

​GET /sat/claves-prod-serv

​Query Parameters

​Example Request

​Example Response

​GET /sat/claves-unidad

​Query Parameters

​Example Request

​Example Response

​Common Errors

​400 Bad Request

GET /sat/regimenes-fiscales

Query Parameters

Example Request

Example Response

GET /sat/usos-cfdi

Query Parameters

Example Request

Example Response

Response Shape

GET /sat/claves-prod-serv

Query Parameters

Example Request

Example Response

GET /sat/claves-unidad

Query Parameters

Example Request

Example Response

Common Errors

400 Bad Request