Catálogos DIAN

Casi todos los códigos que van en una factura —tipo de identificación, tributo, medio de pago, unidad de medida— salen de una tabla de la DIAN. Aquí están transcritas, y cada una tiene su endpoint por si prefieres cargarlas en tiempo de ejecución para armar tus selectores.

Todas cuelgan de /v1/catalogs/.

El API no comprueba estos códigos

Salvo cuatro campos, el contrato acepta cualquier cadena no vacía donde va un código de catálogo. Mandar identification_type: "99" o taxes[].code: "77" pasa la validación sin una queja, el documento se encola y se firma — y el rechazo llega después, desde la DIAN, cuando ya gastaste un consecutivo y una unidad de tu cupo.

Tres se validan en el contrato de entrada: customer.person_type (1 o 2), customer.tax_regime (48 o 49) y payment.form_code (1 o 2). Cualquier otro valor en ellos devuelve 400 al instante.

El cuarto es discrepancy_code, el de las notas. Se comprueba contra la tabla 13.2.4 si es nota crédito (sólo 1–6) o contra la 13.2.5 si es nota débito (sólo 1–4), y un código fuera de la lista devuelve 422 con code: "VALIDATION". Este se rechaza antes de consumir consecutivo o cupo, así que reintentar con el código correcto no te cuesta nada.

Para todo lo demás: valida tú contra estas tablas antes de enviar. Un error de validación es barato; un rechazo de la DIAN, no.

Cómo se consultan

Los once catálogos fijos responden un array plano, sin envoltorio:

[
  { "code": "13", "name": "Cédula de ciudadanía" },
  { "code": "31", "name": "NIT" }
]

No piden autenticación. Es la excepción en todo el API: el controlador de catálogos no lleva guarda de credenciales, así que puedes cablear tus listas desplegables antes de tener client_id y client_secret. Lo único que aplica es el límite general de 300 peticiones por minuto y por IP.

Cópialas, no las consultes en cada venta

Estas tablas cambian cuando la DIAN publica una versión nueva del anexo técnico, o sea casi nunca. Traerlas al arrancar tu aplicación y guardarlas en memoria es suficiente; pedirlas en cada factura solo te acerca al límite de peticiones.

Tipos de identificación

GET/v1/catalogs/identification-types

Tabla DIAN 6.2.1. Es el valor de customer.identification_type.

Código	Nombre
11	Registro civil
12	Tarjeta de identidad
13	Cédula de ciudadanía
21	Tarjeta de extranjería
22	Cédula de extranjería
31	NIT
41	Pasaporte
42	Documento de identificación extranjero
47	PEP
48	PPT
50	NIT de otro país
91	NUIP

Con 31 acompaña el dígito de verificación en customer.dv: un carácter, ni más ni menos.

Tipos de organización

GET/v1/catalogs/person-types

Es el valor de customer.person_type.

Código	Nombre
1	Persona jurídica
2	Persona natural

Este sí se valida. Un valor distinto de 1 o 2 devuelve 400 sin llegar a la DIAN.

Regímenes

GET/v1/catalogs/tax-regimes

Tabla 6.2.4. Es el valor de customer.tax_regime, opcional.

Código	Nombre
48	Responsable de IVA
49	No responsable de IVA

También se valida contra la lista: solo 48 o 49.

Responsabilidades fiscales

GET/v1/catalogs/fiscal-responsibilities

Tabla 6.2.7. Es el contenido de customer.responsibilities, un array de códigos.

Código	Nombre
O-13	Gran contribuyente
O-15	Autorretenedor
O-23	Agente de retención IVA
O-47	Régimen simple de tributación
R-99-PN	No aplica - Otros

R-99-PN es el que lleva un adquiriente que no tiene ninguna responsabilidad especial, que en un POS es la mayoría.

Tributos

GET/v1/catalogs/tax-types

Tabla 6.2.2. Es el valor de items[].taxes[].code.

Código	Nombre
01	IVA
02	IC
03	ICA
04	INC
05	ReteIVA
06	ReteFuente
07	ReteICA
20	FtoHorticultura
21	Timbre
22	INC Bolsas
23	INCarbono
24	INCombustibles
25	Sobretasa Combustibles
26	Sordicom
30	IC Datos
32	ICL
33	INPP
34	IBUA
35	ICUI
36	ADV
ZZ	Otro

En una tienda normal se usan tres: 01 para el IVA, 04 para el impuesto al consumo y 03 para el ICA.

Formas de pago

GET/v1/catalogs/payment-forms

Es el valor de payment.form_code.

Código	Nombre
1	Contado
2	Crédito

Este también se valida. Y no es lo mismo que el medio de pago: la forma dice cuándo se paga, el medio dice con qué.

Medios de pago

GET/v1/catalogs/payment-means

Tabla 6.3.4.2. Es el valor de payment.means_code.

Código	Nombre
1	Instrumento no definido
10	Efectivo
20	Cheque
31	Transferencia débito
42	Consignación bancaria
45	Transferencia crédito bancario
47	Transferencia débito bancaria
48	Tarjeta crédito
49	Tarjeta débito
71	Bonos
72	Vales
ZZZ	Otro

No es la tabla completa de la DIAN

Estos doce son el subconjunto que se usa en punto de venta. La tabla 6.3.4.2 de la caja de herramientas trae bastantes más. Si necesitas uno que no está aquí, el API lo va a aceptar igual —no valida contra el catálogo— pero avísanos para incluirlo en el endpoint, porque tu selector no lo va a mostrar.

Una venta en efectivo es form_code: "1" con means_code: "10". Una datáfono con tarjeta débito, form_code: "1" con means_code: "49".

Unidades de medida

GET/v1/catalogs/unit-measures

UN/ECE recomendación 20. Es el valor de items[].unit_measure.

Código	Nombre
94	Unidad
EA	Unidad (each)
KGM	Kilogramo
GRM	Gramo
LTR	Litro
MLT	Mililitro
MTR	Metro
CMT	Centímetro
MTK	Metro cuadrado
HUR	Hora
DAY	Día
BX	Caja
PK	Paquete

Si omites unit_measure, el servidor pone 94. Para un POS que vende cosas contadas, es lo correcto y puedes no mandarlo nunca.

También es un subconjunto: la recomendación 20 completa tiene cientos de códigos.

Tipos de operación

GET/v1/catalogs/operation-types

Tabla 6.1.5.

Código	Nombre
10	Estándar
20	Nota crédito/débito que referencia una factura electrónica
22	Nota crédito/débito sin referencia a facturas

Este no lo mandas tú, y el catálogo se queda corto

El tipo de operación lo asigna el API según el documento que emites; no es un campo del cuerpo. Y hay una discrepancia real que conviene conocer: para la nota débito el API emite 30, un código que no aparece en este catálogo. Si armas un selector con este endpoint no vas a encontrar el valor que el propio API usa. No es un problema para tu integración —tú no envías el campo—, pero sí para cualquier pantalla que traduzca códigos a nombres.

Conceptos de nota crédito

GET/v1/catalogs/credit-note-concepts

Tabla 13.2.4. Es el valor de discrepancy_code en una nota crédito, y es una lista cerrada: POST /v1/credit-notes con un código que no esté en esta tabla devuelve 422 con code: "VALIDATION" y el mensaje discrepancy_code X no existe. Válidos: 1, 2, 3, 4, 5, 6.

Código	Nombre
1	Devolución parcial de los bienes y/o no aceptación parcial del servicio
2	Anulación de factura electrónica
3	Rebaja o descuento parcial o total
4	Ajuste de precio
5	Descuento comercial por pronto pago
6	Descuento comercial por volumen de ventas

El código 3 lleva dos espacios, y son a propósito

La descripción del concepto 3 tiene doble espacio entre «Rebaja» y «o». No es una errata de esta página ni del código: está así en el Excel oficial de la caja de herramientas, y la regla DIAN CBF04 compara la descripción del documento contra esa cadena, carácter por carácter. «Arreglarlo» hace que la DIAN rechace la nota.

Tal cual sale del endpoint:

{ "code": "3", "name": "Rebaja  o descuento parcial o total" }

Por esto mismo el API descarta el campo discrepancy_description si lo mandas: la descripción siempre la saca de esta tabla usando el código.

Conceptos de nota débito

GET/v1/catalogs/debit-note-concepts

Tabla 13.2.5. Es el valor de discrepancy_code en una nota débito, y es una lista cerrada: POST /v1/debit-notes con un código que no esté en esta tabla devuelve 422 con code: "VALIDATION" y el mensaje discrepancy_code X no existe. Válidos: 1, 2, 3, 4. Ojo con reutilizar código entre notas: el 4 vale aquí, pero el 5 y el 6, que sí existen para nota crédito, no.

Código	Nombre
1	Intereses
2	Gastos por cobrar
3	Cambio del valor
4	Otros

Departamentos

GET/v1/catalogs/departments

Los 33 departamentos con su código DANE de dos dígitos. Sin parámetros.

Código	Nombre		Código	Nombre
05	Antioquia		66	Risaralda
08	Atlántico		68	Santander
11	Bogotá		70	Sucre
13	Bolívar		73	Tolima
15	Boyacá		76	Valle del Cauca
17	Caldas		81	Arauca
18	Caquetá		85	Casanare
19	Cauca		86	Putumayo
20	Cesar		88	San Andrés y Providencia
23	Córdoba		91	Amazonas
25	Cundinamarca		94	Guainía
27	Chocó		95	Guaviare
41	Huila		97	Vaupés
44	La Guajira		99	Vichada
47	Magdalena
50	Meta
52	Nariño
54	Norte de Santander
63	Quindío

Este catálogo no va en ningún campo del documento: está para que puedas ofrecer un selector de departamento y, con él, filtrar los municipios. Lo que viaja en la factura es el municipio.

Municipios

GET/v1/catalogs/municipalities

Los 1.122 municipios con su código DANE de cinco dígitos. Es el valor de customer.municipality_code, que el contrato exige de exactamente cinco caracteres.

Parámetro	Tipo	Obligatorio	Descripción
department	string	No	Filtra por el prefijo de dos dígitos del código DANE. No comprueba que el departamento exista: uno inventado devuelve [].
q	string	No	Busca por código (prefijo) o por nombre (subcadena). Ignora mayúsculas y tildes: bogota, Bogotá y BOGOTA dan lo mismo.

curl "https://sandbox.facturacion.misofk.com/v1/catalogs/municipalities?department=05&q=med"

[
  { "code": "05001", "name": "Medellín" },
  { "code": "05604", "name": "Remedios" }
]

Remedios sale porque q busca subcadena dentro del nombre, no prefijo: «remedios» contiene «med».

Sin q te llegan los 1.122

El recorte a 50 resultados solo se aplica cuando mandas q. Sin q, la respuesta trae el listado completo —o el departamento entero si filtras por department—, y no hay limit, offset ni cursor con qué reducirla.

Descarga la lista una vez y búscala en tu aplicación, o manda siempre q. Lo que no conviene es pedir los 1.122 municipios cada vez que un cajero abre el formulario del cliente.

Dos constantes que no tienen endpoint

No se consultan por HTTP, pero las vas a necesitar.

Constante	Valor	Para qué
NIT del consumidor final	222222222222	Va en customer.identification cuando la venta no tiene cliente identificado.
Perfil de ejecución	1 producción, 2 habilitación	Lo escribe el API en el UBL según el ambiente del emisor. No lo envías.

Para una venta a consumidor final, el cliente mínimo es identification_type: "13", identification: "222222222222", person_type: "2" y el nombre que corresponda.

Y si el código que necesito no está

Tienes dos opciones, y una es mala:

Mandarlo igual. El API lo acepta en los catálogos que no tienen lista cerrada —tipo de identificación, tributos, medios de pago, unidades de medida, responsabilidades, municipios—. La DIAN decide después, y si dice que no, ya perdiste el consecutivo y la unidad de cupo, y tienes que recoger el error por webhook o consultando el documento.

Esto no vale para los cuatro campos que el API sí comprueba. person_type, tax_regime y payment.form_code devuelven 400 al instante, como dice el aviso del principio; y un discrepancy_code que no esté en las tablas 13.2.4 / 13.2.5 devuelve 422 con la lista de códigos válidos. En esos cuatro no se crea el documento, no se encola nada y no se gasta ni el consecutivo ni la unidad de cupo.

Escríbenos. Estas tablas son subconjuntos declarados de las de la DIAN, y ampliarlas es cambiar un archivo. Es más rápido que descubrir por qué la DIAN rechazó tu documento.