Consultar un Catálogo

Obtén las entradas de un catálogo específico del SAT. Soporta búsqueda por texto y paginación para catálogos grandes como c_ClaveProdServ o c_CodigoPostal.

Endpoint

GET https://api.lummy.io/v1/catalogs/{catalogName}

Entorno	URL
Producción	`https://api.lummy.io/v1/catalogs/{catalogName}`
Sandbox	`https://sandbox.lummy.io/v1/catalogs/{catalogName}`

Request

Path Parameters

Parámetros de ruta

{

"catalogName": stringrequerido

↳Nombre técnico del catálogo del SAT a consultar. Debe coincidir exactamente con uno de los nombres devueltos por el endpoint GET /catalogs. Los catálogos siguen la nomenclatura oficial del SAT (prefijo c_ seguido del nombre).

↳Valores permitidos: "c_FormaPago""c_MetodoPago""c_Moneda""c_UsoCFDI""c_RegimenFiscal""c_ClaveProdServ""c_ClaveUnidad""c_CodigoPostal"

↳Ejemplo: "c_FormaPago"

}

Query Parameters

Parámetros de consulta

{

"search": string,opcional

↳Texto para filtrar las entradas del catálogo. La búsqueda se realiza en todos los campos de cada entrada (clave, descripción, etc.). No distingue entre mayúsculas y minúsculas.

↳Ejemplo: "software"

"limit": number,opcional

↳Número máximo de entradas a devolver. Útil para catálogos grandes como c_ClaveProdServ (~50,000 entradas) o c_CodigoPostal (~80,000 entradas). Si no se especifica, devuelve todas las entradas.

↳Rango: 1 - 1000 · Valor por defecto: "todas las entradas"

↳Ejemplo: 50

"offset": numberopcional

↳Número de entradas a saltar desde el inicio. Usar junto con limit para implementar paginación. La primera página tiene offset=0.

↳Valor mínimo: 0 · Valor por defecto: 0

↳Ejemplo: 100

}

Headers

Headers requeridos

{

"Authorization": string,requerido

↳Token JWT de autenticación. Debe incluir el prefijo "Bearer " seguido del token.

↳Ejemplo: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

"x-organization-id": stringrequerido

↳Identificador único de la organización.

↳Formato: UUID v4

↳Ejemplo: "550e8400-e29b-41d4-a716-446655440000"

}

Response

200 OK

Entradas del catálogo obtenidas exitosamente.

Response Body

{

"catalogName": string,requerido

↳Nombre del catálogo consultado.

↳Ejemplo: "c_FormaPago"

"entries": [requerido

↳Lista de entradas del catálogo. La estructura de cada entrada varía según el catálogo consultado. Cada entrada contiene al menos una clave (código) y una descripción.

"[item]": objectopcional

↳Entrada del catálogo con estructura variable según el tipo de catálogo.

"total": number,requerido

↳Número total de entradas en el catálogo (sin considerar paginación). Útil para calcular el número de páginas cuando se usa limit/offset.

↳Ejemplo: 23

"limit": number,opcional

↳Límite aplicado a la consulta (si se especificó).

↳Ejemplo: 50

"offset": numberopcional

↳Offset aplicado a la consulta (si se especificó).

↳Ejemplo: 0

}

Ejemplo de respuesta (c_FormaPago):

{
  "catalogName": "c_FormaPago",
  "entries": [
    { "c_FormaPago": "01", "c_Descripcion": "Efectivo" },
    { "c_FormaPago": "02", "c_Descripcion": "Cheque nominativo" },
    { "c_FormaPago": "03", "c_Descripcion": "Transferencia electrónica de fondos" },
    { "c_FormaPago": "04", "c_Descripcion": "Tarjeta de crédito" }
  ],
  "total": 23
}

404 Not Found

El catálogo especificado no existe.

{
  "statusCode": 404,
  "message": "Catálogo 'c_CatalogoInvalido' no encontrado"
}

Ejemplos de Código

cURL
Node.js
Python

# Obtener formas de pago
curl -X GET "https://api.lummy.io/catalogs/c_FormaPago" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${ORG_ID}"

# Buscar productos de software con paginación
curl -X GET "https://api.lummy.io/catalogs/c_ClaveProdServ?search=software&limit=50&offset=0" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${ORG_ID}"

# Buscar códigos postales de Monterrey
curl -X GET "https://api.lummy.io/catalogs/c_CodigoPostal?search=Monterrey&limit=100" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${ORG_ID}"

// Obtener formas de pago
const formasPago = await fetch(
  'https://api.lummy.io/catalogs/c_FormaPago',
  {
    headers: {
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
      'x-organization-id': ORG_ID,
    },
  }
).then(r => r.json());

console.log(`Total: ${formasPago.total} formas de pago`);

// Buscar productos con paginación
const productos = await fetch(
  'https://api.lummy.io/catalogs/c_ClaveProdServ?search=software&limit=50',
  {
    headers: {
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
      'x-organization-id': ORG_ID,
    },
  }
).then(r => r.json());

console.log(`Encontrados: ${productos.total} productos de software`);

import requests

# Obtener formas de pago
formas_pago = requests.get(
    'https://api.lummy.io/catalogs/c_FormaPago',
    headers={
        'Authorization': f'Bearer {ACCESS_TOKEN}',
        'x-organization-id': ORG_ID,
    }
).json()

print(f"Total: {formas_pago['total']} formas de pago")

# Buscar productos con paginación
productos = requests.get(
    'https://api.lummy.io/catalogs/c_ClaveProdServ',
    params={'search': 'software', 'limit': 50},
    headers={
        'Authorization': f'Bearer {ACCESS_TOKEN}',
        'x-organization-id': ORG_ID,
    }
).json()

print(f"Encontrados: {productos['total']} productos de software")

Estructura de Entradas por Catálogo

Cada catálogo tiene una estructura diferente. Aquí los más comunes:

c_FormaPago

{
  "c_FormaPago": "03",
  "c_Descripcion": "Transferencia electrónica de fondos",
  "c_BancarizadoObligatorio": "Sí"
}

c_RegimenFiscal

{
  "c_RegimenFiscal": "612",
  "c_Descripcion": "Personas Físicas con Actividades Empresariales y Profesionales",
  "c_Fisica": "Sí",
  "c_Moral": "No"
}

c_CodigoPostal

{
  "c_CodigoPostal": "06600",
  "c_Estado": "CMX",
  "c_Municipio": "015"
}

Tamaño de Catálogos

Catálogo	Entradas Aproximadas	Recomendación
`c_FormaPago`	~25	Sin paginación
`c_MetodoPago`	2	Sin paginación
`c_UsoCFDI`	~25	Sin paginación
`c_RegimenFiscal`	~20	Sin paginación
`c_ClaveProdServ`	~50,000	Usar paginación
`c_ClaveUnidad`	~2,000	Usar paginación
`c_CodigoPostal`	~80,000	Usar paginación
`c_Colonia`	~100,000	Usar paginación

Catálogos Grandes

Para catálogos con más de 1,000 entradas, siempre use paginación con los parámetros limit y offset para evitar timeouts y reducir el consumo de memoria.

Endpoint​

Request​

Path Parameters​

Query Parameters​

Headers​

Response​

200 OK​

404 Not Found​

Ejemplos de Código​

Estructura de Entradas por Catálogo​

c_FormaPago​

c_RegimenFiscal​

c_CodigoPostal​

Tamaño de Catálogos​

Siguientes Pasos​