Catálogos y códigos

Los códigos que admite cada campo, cuáles consulta la API por ti y cuáles tienes que conocer de la DIAN.

Una factura electrónica está llena de códigos: el tipo de documento del comprador, la unidad de medida, el tributo, el medio de pago. La DIAN publica listas enormes; Cufy solo admite el subconjunto que está implementado y probado.

Para no adivinar ni dejar códigos fijos en tu código, pregúntale a la API qué admite hoy.

Consultar un catálogo

curl https://api-sandbox.cufy.co/v1/catalogs/unit_codes \
  -H "X-API-Key: TU_API_KEY"

{
  "id": "unit_codes",
  "version": "cufy-2026-09-25-v9",
  "items": [
    { "code": "94", "label": "94", "active": true, "valid_from": "2026-09-24" }
  ],
  "next_cursor": null
}

Campo	Qué es
`code`	El valor que envías en la factura.
`label`	El nombre del código. Hoy repite el código: Cufy no traduce las denominaciones oficiales de la DIAN.
`active`	`true` si lo admite tu ambiente. Un código `false` está en el contrato pero no se puede usar todavía.
`valid_from`	Cuándo se publicó esta definición en Cufy. No es una fecha de vigencia tributaria.
`version`	Cambia cuando cambian los códigos. Si guardas catálogos en caché, compara esta versión.

GET /v1/catalogs/catalogs lista los catálogos disponibles, por si quieres recorrerlos todos. Los listados se paginan igual que el resto de la API (ver Paginación); el orden por código es estable.

Necesitas una API key con company:read, que toda cuenta del sandbox tiene. Las respuestas son privadas: no las publiques en una caché compartida.

Qué admite el sandbox

El sandbox funciona en el ambiente de habilitación, con el perfil co-sale-cop-v1. Esto es lo activo hoy:

Catálogo	Para qué	Valores activos
`document_types`	El campo `document_type`	`invoice`, `credit_note`, `debit_note`, y el documento equivalente POS: `pos_equivalent`, `pos_credit_note`, `pos_debit_note`
`profiles`	El campo `profile_id`	`co-sale-cop-v1` para facturas, `co-referenced-note-cop-v1` para notas, `co-pos-equivalent-cop-v1` para el tiquete POS y `co-pos-adjustment-cop-v1` para sus notas de ajuste
`currencies`	El campo `currency`	`COP`
`buyer_types`	`buyer.party_type`	`person`, `company`, `final_consumer` (consumidor final)
`identification_types`	`buyer.identification.type_code`	`13` (cédula de ciudadanía), `31` (NIT)
`tax_codes`	El tributo de cada impuesto	`01` (IVA) y `04` (impoconsumo, INC)
`tax_rates`	La tarifa de cada tributo	IVA: `0`, `5`, `19`. Impoconsumo: `8`
`payment_means`	`payment.means_code`	Los medios de pago de la DIAN que usa un negocio en Colombia: `10` efectivo, `20` cheque, `30`/`31`/`45`/`46`/`47` transferencias, `42` consignación, `48` tarjeta crédito, `49` tarjeta débito, `2`/`3` ACH, `93`/`94`/`95` giros, `71` bonos, `72` vales, `1` no definido, `ZZZ` acuerdo mutuo, entre otros. La lista completa
`payment_terms`	`payment.terms`	`cash`, `credit`
`unit_codes`	`lines[].unit_code`	`94` (unidad)
`product_schemes`	`lines[].product_identification.scheme_code`	`999` (código propio)
`adjustment_reasons`	`adjustments[].reason_code`	`00` no condicionado, `01` condicionado. Solo descuentos: la DIAN no categoriza cargos
`credit_note_reasons`	El motivo de una nota crédito	`1`, `2`
`debit_note_reasons`	El motivo de una nota débito	`3`

Una lista corta es una lista corta

Si tu caso necesita un código que no está activo —otra moneda, otra unidad de medida, otro medio de pago— la factura se rechaza con 422 FISCAL_VALIDATION_FAILED y detalle UNSUPPORTED_FISCAL_CASE. No es un error tuyo: es que Cufy todavía no lo admite. Escríbenos y lo priorizamos.

Códigos que la API no te da

Tres grupos de códigos no son catálogos de Cufy. Los tomas de la DIAN o del DANE y los envías tal cual.

Departamentos

buyer.address.department_code son dos dígitos del DANE y Cufy los valida contra la tabla oficial de la DIAN: 33 departamentos, incluido 11 para Bogotá. Un código que no esté en esa tabla se rechaza con BUYER_DEPARTMENT_INVALID.

Municipios

buyer.address.municipality_code son cinco dígitos y Cufy comprueba dos cosas: que sean cinco dígitos y que empiecen por el código del departamento que declaraste. 11001 (Bogotá) es válido junto a 11; 05001 (Medellín) junto a 05.

Cufy no comprueba que el municipio exista. Si te equivocas en los tres últimos dígitos, la factura pasa y la DIAN puede rechazarla después. Toma los códigos de la lista DANE, no los inventes.

Responsabilidades fiscales

buyer.tax_registration.responsibility_codes son los códigos del RUT del comprador, entre 1 y 30. Cufy los acepta como texto y los pasa a la DIAN sin comprobarlos contra una lista, porque cambian con la normativa.

Para una persona natural sin responsabilidades especiales: ["R-99-PN"].
Para una empresa: los que figuren en su RUT.

tax_scheme_codes, en cambio, sí está cerrado: ["01"] para personas y empresas, y ["ZZ"] para el consumidor final (222222222222, R-99-PN).

Lo que todavía no existe

No hay catálogo de municipios, de departamentos ni de responsabilidades fiscales servido por la API. Tampoco hay soporte para retenciones ni anticipos. Cuando lo haya, aparecerá en GET /v1/catalogs/catalogs.

La referencia completa de la operación está en GET /v1/catalogs/{catalog}.