Guía de mapeo POS

Tienes un sistema POS o ERP con su propio modelo de datos. Emitia habla en términos DIAN. Esta guía es el diccionario entre los dos mundos.

Cada tabla muestra: campo en tu sistema → campo Emitia → código DIAN → ejemplo.

Unidad de medida del producto

Campo Emitia: lines[].unit_code
Catálogo DIAN: Unidad de medida (UN/ECE Rec 20)

Tu campo POS	Código Emitia	Significado
Unidad / pieza	`94`	Unidad (más común para servicios y productos unitarios)
Kilogramo	`KGM`	Kilogramo
Metro	`MTR`	Metro lineal
Litro	`LTR`	Litro
Hora	`HUR`	Hora de servicio
Día	`DAY`	Día
Número de artículos	`NAR`	Número de artículos (para ítems contables)

Ejemplo en el request:

{
  "lines": [
    {
      "description": "Servicio de consultoría",
      "quantity": "1.00",
      "unit_code": "94",
      "unit_price": "100000.00"
    }
  ]
}

Forma de pago

Campo Emitia: payment_means.code
Catálogo DIAN: Medio de pago (UN/ECE 4461)

Tu campo POS	Código Emitia	Significado
Efectivo	`10`	Efectivo
Tarjeta crédito	`47`	Tarjeta de crédito
Tarjeta débito	`48`	Tarjeta de débito
Transferencia crédito	`30`	Transferencia bancaria (crédito)
Transferencia débito	`31`	Transferencia bancaria (débito)
Cheque	`20`	Cheque
Consignación bancaria	`42`	Consignación bancaria
Billetera digital / PSE	`71`	Billetera electrónica
Bono / voucher	`49`	Bono o voucher

Además del código, debes indicar el tipo de pago:

Tipo de pago	Valor	Cuándo usar
Contado	`1`	Pago al momento de la venta
Crédito	`2`	Pago a plazo (requiere `due_date`)

Ejemplo:

{
  "payment_means": {
    "code": "47",
    "type": "2",
    "due_date": "2026-02-15"
  }
}

Tipo de identificación del cliente

Campo Emitia: identification.type (en el recurso customers)
Catálogo DIAN: Tipo de documento de identidad

Tipo de cliente	Código Emitia	Documento
Empresa colombiana	`31`	NIT (Número de Identificación Tributaria)
Persona natural	`13`	Cédula de ciudadanía
Extranjero residente	`22`	Cédula de extranjería
Extranjero no residente	`21`	Tarjeta de extranjería
Pasaporte	`41`	Pasaporte
Menor de edad	`12`	Tarjeta de identidad
Registro civil	`11`	Registro civil
Empresa extranjera	`50`	NIT de otro país

El tipo de organización (jurídica/natural) va aparte, en organization_type ("1" jurídica, "2" natural) — no es un campo type del cliente.

Ejemplo para empresa (NIT con dígito de verificación):

{
  "identification": {
    "type": "31",
    "number": "900111222",
    "check_digit": "1"
  },
  "legal_name": "Acme SAS",
  "organization_type": "1"
}

Ejemplo para persona natural (cédula sin dígito de verificación):

{
  "identification": {
    "type": "13",
    "number": "1020304050"
  },
  "legal_name": "Juan Pérez",
  "organization_type": "2"
}

Tipo de operación

Campo Emitia: operation_type
Catálogo DIAN: Tipo de operación (CustomizationID en el UBL)

Tipo de venta en tu POS	Código Emitia	Significado DIAN
Venta estándar	`10`	Operación estándar (la más común)
Servicios AIU	`09`	Administración, Impuesto y Utilidad
Exportación	`11`	Venta a no residentes / exportación

La gran mayoría de facturas nacionales usan 10 (estándar).

Ejemplo:

{
  "operation_type": "10"
}

Impuesto (tributo)

Campo Emitia: lines[].taxes[].code
Catálogo DIAN: Tributos

Impuesto en tu POS	Código Emitia	Nombre completo	Tasa típica
IVA	`01`	Impuesto al Valor Agregado	0%, 5%, 19%
INC	`04`	Impuesto Nacional al Consumo	8%, 16%
ICA	`03`	Impuesto de Industria y Comercio	Variable por municipio
IC	`02`	Impuesto al Carbono	Variable
Sin impuesto	`ZZ`	No aplica	—

Ejemplo de línea con IVA al 19%:

{
  "lines": [
    {
      "description": "Laptop Dell XPS",
      "quantity": "1.00",
      "unit_code": "94",
      "unit_price": "3000000.00",
      "taxes": [
        {
          "code": "01",
          "rate": "19.00",
          "base": "3000000.00",
          "value": "570000.00"
        }
      ]
    }
  ]
}

Ejemplo de línea sin impuesto (exenta o excluida):

{
  "taxes": [
    {
      "code": "ZZ",
      "rate": "0.00",
      "base": "0.00",
      "value": "0.00"
    }
  ]
}

Resumen: el JSON de factura mínima

Con los valores anteriores, una factura de venta estándar con IVA 19% a una empresa colombiana queda así:

{
  "customer_id": "cust_01HX...",
  "currency": "COP",
  "operation_type": "10",
  "payment_means": { "code": "10", "type": "1" },
  "lines": [
    {
      "description": "Servicio de consultoría",
      "quantity": "1.00",
      "unit_code": "94",
      "unit_price": "100000.00",
      "line_extension_amount": "100000.00",
      "taxes": [
        { "code": "01", "rate": "19.00", "base": "100000.00", "value": "19000.00" }
      ]
    }
  ]
}

Total: 100.000 + 19.000 = 119.000 COP.

Consulta programática de catálogos

En vez de hardcodear los códigos en tu aplicación, puedes consultarlos en runtime:

# Medios de pago
GET /v1/catalogs/medios-pago

# Tipos de identificación
GET /v1/catalogs/tipo-identificacion

# Unidades de medida
GET /v1/catalogs/unidad-medida

# Tributos
GET /v1/catalogs/tributos

# Tipos de operación
GET /v1/catalogs/tipo-operacion

Todos los catálogos tienen caché agresiva (24h). Consulta la Referencia API interactiva para el schema completo de la respuesta.

Próximos pasos

Inicio rápido — emite tu primera factura de prueba
Conceptos: Idempotencia — por qué es obligatoria en POST
Conceptos: Ambientes — pasar de sandbox a habilitación