Catálogos

Catálogos del SAT

Consulta las claves oficiales —uso de CFDI, forma de pago, régimen, unidades— en vez de codificarlas a mano.

Las claves del SAT cambian. Codificarlas en tu integración significa que un día un CFDI se rechaza y nadie sabe por qué. Estos endpoints sirven el catálogo que Facty tiene sincronizado, que es exactamente el que valida al timbrar.

No requieren organización en la URL, solo una API key válida — cualquier scope sirve.

Catálogo general

GET /api/authenticated/catalogs/sat?type={Tipo}&q={búsqueda}

Parámetro	Descripción
`type`	Requerido. Nombre del catálogo (ver la tabla). Distingue mayúsculas.
`q`	Opcional. Filtra por clave o por nombre, sin distinguir mayúsculas.

curl -s "$FACTY_HOST/api/authenticated/catalogs/sat?type=FormaPago" \
  -H "X-API-Key: $FACTY_KEY" | jq

{
  "items": [
    { "key": "01", "name": "Efectivo", "meta": null },
    { "key": "02", "name": "Cheque nominativo", "meta": null },
    { "key": "03", "name": "Transferencia electrónica de fondos", "meta": null },
    { "key": "99", "name": "Por definir", "meta": null }
  ]
}

Un type que no existe devuelve 422.

Tipos disponibles

CFDI 4.0 base

`type`	Catálogo del SAT
`RegimenFiscal`	c_RegimenFiscal
`UsoCfdi`	c_UsoCFDI
`FormaPago`	c_FormaPago
`MetodoPago`	c_MetodoPago (PUE / PPD)
`Moneda`	c_Moneda
`ClaveUnidad`	c_ClaveUnidad
`TasaOCuota`	c_TasaOCuota
`ObjetoImp`	c_ObjetoImp
`TipoRelacion`	c_TipoRelacion
`Exportacion`	c_Exportacion
`Periodicidad`	c_Periodicidad (factura global)
`Meses`	c_Meses (factura global)

Nómina

`type`	Catálogo del SAT
`TipoNomina`	c_TipoNomina (O ordinaria / E extraordinaria)
`TipoContrato`	c_TipoContrato
`TipoRegimen`	c_TipoRegimen
`TipoJornada`	c_TipoJornada
`PeriodicidadPago`	c_PeriodicidadPago
`TipoPercepcion`	c_TipoPercepcion
`TipoDeduccion`	c_TipoDeduccion
`TipoIncapacidad`	c_TipoIncapacidad
`TipoHoras`	c_TipoHoras
`RiesgoPuesto`	c_RiesgoPuesto
`EntidadFederativa`	c_Estado
`OrigenRecurso`	c_OrigenRecurso
`Banco`	c_Banco

Carta Porte

Estado, TipoPermiso, ConfigAutotransporte, SubtipoRemolque, MaterialPeligroso, ClaveProdServCP, ClaveUnidadPeso, TipoFigura, TipoUbicacion, CveTransporte, TipoEstacion, Estaciones, TipoEmbarcacion, TipoCarga, TipoContenedorMaritimo, CodigoTransportista, TipoDeServicio, TipoDeTrafico, TipoCarro, TipoContenedorFerroviario, DerechoDePaso.

Clave de producto y servicio

c_ClaveProdServ tiene unas 52,000 entradas: no se descarga, se busca.

GET /api/authenticated/catalogs/clave-prod-serv?q={texto}&limit={1-50}

q debe tener al menos 2 caracteres. Si pasas una clave completa de 8 dígitos, la devuelve como única coincidencia.

curl -s "$FACTY_HOST/api/authenticated/catalogs/clave-prod-serv?q=consultoria&limit=10" \
  -H "X-API-Key: $FACTY_KEY" | jq

Clave de unidad

GET /api/authenticated/catalogs/clave-unidad?q={texto}&limit={1-50}

Busca tanto en la clave (E48) como en el nombre ("Unidad de servicio"). Default 20 resultados.

Claves que vas a usar todo el tiempo

Forma de pago (c_FormaPago)

Clave	Significado
`01`	Efectivo
`02`	Cheque nominativo
`03`	Transferencia electrónica de fondos
`04`	Tarjeta de crédito
`28`	Tarjeta de débito
`99`	Por definir — obligatoria cuando el método es PPD

Método de pago (c_MetodoPago)

Clave	Significado
`PUE`	Pago en una sola exhibición. Ya cobraste.
`PPD`	Pago en parcialidades o diferido. Cada cobro posterior exige un complemento de pago.

Uso del CFDI (c_UsoCFDI), los más comunes

Clave	Significado
`G01`	Adquisición de mercancías
`G03`	Gastos en general
`I08`	Otra maquinaria y equipo
`S01`	Sin efectos fiscales (público en general, traslados)
`CP01`	Pagos — lo pone Facty solo, en los complementos de pago

El uso del CFDI tiene que ser compatible con el régimen fiscal del receptor: el SAT rechaza, por ejemplo, un G03 para un receptor con régimen 616. Si dejas que el usuario lo elija, aliméntale la lista desde ?type=UsoCfdi.