Guía Rápida para Desarrolladores

Ejemplos por Tipo de Documento DIAN

Explora casos de uso reales listos para copiar y pegar en tu código. Selecciona cualquier tipo de documento para ver el payload rápido (minimalista) o el payload completo con todos los metadatos DIAN, junto con ejemplos en cURL, JavaScript, Python y PHP.

Comercio / ServiciosPOST /v1/api/facturacion-es/factura

Factura Electrónica Estándar (Venta General)

Factura para venta de bienes o servicios a crédito o contado con cálculo automático de IVA (19%), retenciones en la fuente y ReteICA.

Reglas Clave de Integración:

Usa los shortcuts iva: 19 o inc: 8 en las líneas para que el motor auto-calcule subtotal, impuestos globales y total.
Si envías forma_pago: "credito", incluye fecha_vencimiento y dias_credito.
El cálculo de dígito de verificación (DV) del cliente se realiza automáticamente si envías NIT.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/facturacion-es/factura" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "cliente": {
    "nombre": "Papelería El Lápiz S.A.S",
    "numero_identificacion": "900111222",
    "correo": "admin@ellapiz.com",
    "direccion": "Cra 10 #20-30, Medellín"
  },
  "lineas": [
    {
      "descripcion": "Resma de papel carta",
      "cantidad": 10,
      "precio": 15000,
      "iva": 19
    },
    {
      "descripcion": "Caja de lapiceros x12",
      "cantidad": 5,
      "precio": 8000,
      "iva": 19
    }
  ],
  "forma_pago": "contado",
  "metodo_pago": "transferencia",
  "observaciones": "Entrega en bodega principal",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "id": 1042,
    "consecutivo": "SETP99000101",
    "cufe": "a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef012345678",
    "qr_url": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=a1b2c3...",
    "subtotal": 4750000,
    "total_impuestos": 902500,
    "total_retenciones": 235885,
    "total": 5652500,
    "estado_dian": "Aceptado"
  }
}

Sector Salud (Operación 11)POST /v1/api/facturacion-es/factura

Factura Sector Salud (RIPS / MinSalud)

Factura para Clínicas, IPS, EPS y Profesionales de la Salud. Integra código de prestador, paciente, modalidad de pago, código CUPS y copagos.

Reglas Clave de Integración:

Incluye tipo_operacion: "11" para activar las validaciones sectoriales de salud.
El bloque salud define el prestador, modalidad de contratación (01=Pago por evento, 02=Capitación, etc.) y cobertura.
Cada línea médica debe especificar el código CUPS y los datos del paciente beneficiario.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/facturacion-es/factura" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "tipo_operacion": "11",
  "cliente": {
    "nombre": "Entidad Promotora de Salud EPS Sanitas",
    "numero_identificacion": "800251440",
    "tipo_documento": "NIT",
    "correo": "facturacionelectronica@epssanitas.com",
    "municipio": "Bogotá, D.C."
  },
  "salud": {
    "codigo_prestador": "110010987601",
    "modalidad_pago": "01",
    "cobertura": "01",
    "numero_contrato": "CTR-EPS-2026-089"
  },
  "lineas": [
    {
      "codigo": "890201",
      "descripcion": "Consulta médica especializada en cardiología",
      "cantidad": 1,
      "precio": 180000,
      "iva": 0,
      "paciente": {
        "tipo_documento": "CC",
        "numero_documento": "1020304050",
        "primer_nombre": "Andrea",
        "primer_apellido": "Martínez"
      }
    }
  ],
  "copago_cuota_moderadora": 15000,
  "observaciones": "Atención ambulatoria especializada según orden médica No. 9812",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "consecutivo": "SETP99000125",
    "cufe": "f8e7d6c5b4a3...",
    "estado_dian": "Aceptado",
    "subtotal": 670000,
    "copago": 25000,
    "total": 645000
  }
}

Transporte (Operación 12)POST /v1/api/facturacion-es/factura

Factura Sector Transporte de Carga (RNDC)

Factura de transporte terrestre de carga regulado por el Ministerio de Transporte. Incluye Manifiesto RNDC, remesa, placas, origen, destino y flete.

Reglas Clave de Integración:

Usa tipo_operacion: "12" para transporte de carga terrestre.
El objeto transporte contiene remesa_numero, manifiesto_numero, vehiculo_placa, origen y destino con códigos DANE.
Los fletes de transporte terrestre de carga son exentos/excluidos de IVA (iva: 0) y llevan retención en la fuente del 1%.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/facturacion-es/factura" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "tipo_operacion": "12",
  "cliente": {
    "nombre": "Distribuciones y Logística Nacional S.A.",
    "numero_identificacion": "900778899",
    "tipo_documento": "NIT",
    "correo": "facturacion@dislogistica.com"
  },
  "transporte": {
    "remesa_numero": "REM-00129",
    "manifiesto_numero": "MAN-2026-98124",
    "vehiculo_placa": "WBE482",
    "origen": "11001",
    "destino": "76001"
  },
  "lineas": [
    {
      "codigo": "FLETE-BOG-CLO",
      "descripcion": "Servicio de transporte terrestre de carga Bogotá - Cali (18.5 Tons)",
      "cantidad": 1,
      "precio": 3800000,
      "iva": 0,
      "retefuente": 1
    }
  ],
  "forma_pago": "credito",
  "dias_credito": 30,
  "observaciones": "Transporte de mercancía seca según Remesa REM-00129",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "consecutivo": "SETP99000126",
    "cufe": "e7c2a4f9...",
    "estado_dian": "Aceptado",
    "total": 3800000
  }
}

Exportación (Tipo 02)POST /v1/api/facturacion-es/factura

Factura de Exportación (Multidivisa USD & Incoterms)

Factura para clientes internacionales en moneda extranjera (USD, EUR) con registro de TRM del día y términos Incoterms (CIF, FOB, EXW, etc.).

Reglas Clave de Integración:

Especifica tipo_documento: "02" o tipo: "exportacion".
Incluye moneda: "USD" y el objeto tasa_cambio con valor de la TRM oficial.
Define incoterms: "FOB" / "CIF" / "EXW" según las condiciones comerciales internacionales.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/facturacion-es/factura" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "tipo_documento": "02",
  "cliente": {
    "nombre": "Global Tech Services LLC",
    "numero_identificacion": "US987654321",
    "tipo_documento": "50",
    "correo": "billing@globaltech.com",
    "direccion": "800 Brickell Ave Suite 400, Miami FL 33131",
    "pais": "US",
    "municipio": "Miami"
  },
  "moneda": "USD",
  "tasa_cambio": {
    "moneda_origen": "COP",
    "moneda_destino": "USD",
    "tasa": 4150.5,
    "fecha": "2026-08-29"
  },
  "incoterms": "FOB",
  "lineas": [
    {
      "codigo": "EXP-DEV-001",
      "descripcion": "Software Engineering & Cloud Architecture Consulting Services (Export)",
      "cantidad": 40,
      "precio": 85,
      "unidad_medida": "HUR",
      "iva": 0
    }
  ],
  "forma_pago": "credito",
  "metodo_pago": "transferencia",
  "observaciones": "Exportación de servicios exenta de IVA según Art. 481 del Estatuto Tributario.",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "consecutivo": "EXP-0045",
    "cufe": "d9e8f7a6...",
    "moneda": "USD",
    "tasa_cambio": 4150.5,
    "total": 3400,
    "estado_dian": "Aceptado"
  }
}

Combustibles (EDS)POST /v1/api/facturacion-es/factura

Factura Combustibles e Hidrocarburos (EDS)

Facturación en Estaciones de Servicio (EDS) con Impuesto Nacional a Combustibles (Código 24), Sobretasa a la Gasolina/ACPM (Código 25) y Sordicom (Código 26).

Reglas Clave de Integración:

Usa unidad_medida: "GLL" (Galones) o "LTR" (Litros).
Pasa los impuestos específicos en el array impuestos: tipo: "combustibles" (24) y tipo: "sobretasa_combustibles" (25).
La gasolina y el ACPM no llevan IVA general, sino tributos fijos por galón despachado.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/facturacion-es/factura" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "cliente": {
    "nombre": "Transportes y Carga del Norte S.A.S.",
    "numero_identificacion": "900554433",
    "tipo_documento": "NIT",
    "correo": "compras@transportenorte.com.co"
  },
  "lineas": [
    {
      "codigo": "COMB-CORRIENTE",
      "descripcion": "Gasolina Motor Corriente Nacional Oxigenada",
      "cantidad": 65.5,
      "precio": 15450,
      "unidad_medida": "GLL",
      "impuestos": [
        {
          "tipo": "combustibles",
          "base": 1012000,
          "valor": 45000
        },
        {
          "tipo": "sobretasa_combustibles",
          "base": 1012000,
          "valor": 32000
        }
      ]
    }
  ],
  "forma_pago": "contado",
  "metodo_pago": "tarjeta_credito",
  "observaciones": "Venta en Surtidor Isla 02 - EDS. Despacho Placa WBE482.",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "consecutivo": "SETP99000127",
    "cufe": "b3c4d5e6...",
    "total": 1655200,
    "estado_dian": "Aceptado"
  }
}

Notas Crédito (Tipo 04)POST /v1/api/facturacion-es/nota-credito

Nota Crédito (Anulación o Ajuste con CUFE)

Emisión de Nota Crédito referenciando una factura electrónica previa mediante su ID o CUFE, con código de concepto DIAN.

Reglas Clave de Integración:

Especifica documento_referencia (ID interno de la factura) o cufe_factura_referencia.
Conceptos DIAN: 1 = Devolución total, 2 = Anulación por no cobro, 3 = Rebaja/descuento parcial, 4 = Ajuste de precio.
Si es devolución parcial, envía solo las líneas y cantidades que se van a descontar.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/facturacion-es/nota-credito" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "documento_referencia": 42,
  "concepto_nota": "2",
  "cliente": {
    "nombre": "Papelería El Lápiz S.A.S",
    "numero_identificacion": "900111222"
  },
  "lineas": [
    {
      "descripcion": "Devolución resma de papel",
      "cantidad": 5,
      "precio": 15000,
      "iva": 19
    }
  ],
  "observaciones": "Devolución por producto defectuoso",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "id": 504,
    "consecutivo": "NC-0012",
    "cude": "cude_sha384_nota_credito...",
    "total": 2975000,
    "estado_dian": "Aceptado"
  }
}

Doc. Soporte (05)POST /v1/api/documentos-soporte/emitir

Documento Soporte en Adquisiciones (Tipo 05)

Soporte de costos y deducciones por compras o servicios prestados por personas naturales no obligadas a facturar (sin RUT/DV obligatorio).

Reglas Clave de Integración:

El proveedor solo requiere cédula (tipo_documento: "13" o "CC") y nombre completo.
Aplica retención en la fuente (tipo: "07") y ReteICA (tipo: "05") según la tarifa aplicable.
Genera automáticamente el CUDS SHA-384 con prefijo y rango DIAN autorizado.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/documentos-soporte/emitir" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "proveedor": {
    "tipo_documento": "13",
    "numero_identificacion": "1018293847",
    "nombre": "Pedro Antonio Gómez Morales",
    "correo": "pedro.gomez@servicios.com"
  },
  "lineas": [
    {
      "descripcion": "Servicio de reparación y mantenimiento eléctrico de planta",
      "cantidad": 1,
      "precio_unitario": 450000,
      "retenciones": [
        {
          "tipo": "07",
          "porcentaje": 4,
          "base": 450000,
          "valor": 18000
        }
      ]
    }
  ],
  "forma_pago": "1",
  "metodo_pago": "10",
  "observaciones": "Cuenta de cobro No. 14 por servicios de mantenimiento",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "id": 302,
    "prefijo": "DS",
    "numero": "0089",
    "cuds": "f47ac10b58cc4372a5670e02b2f3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7",
    "subtotal": 850000,
    "total_retenciones": 42211,
    "total": 807789,
    "estado_dian": "Aceptado"
  }
}

POS (Código 20)POST /v1/api/pos/emitir

POS Electrónico (Tiquete de Caja Registradora)

Emisión instantánea (< 2s) de tirilla POS para cajas registradoras, supermercados y restaurantes. Incluye propina voluntaria y pagos combinados.

Reglas Clave de Integración:

Si no se envía cliente, el sistema asigna automáticamente Consumidor Final (NIT 222222222222).
Permite múltiples medios de pago en el array pagos (efectivo + datáfono).
Genera el PDF en formato tirilla térmica mediante /v1/api/pos/:id/tirilla?width=80.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/pos/emitir" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "lineas": [
    {
      "codigo": "MENU-001",
      "descripcion": "Combo Almuerzo Ejecutivo",
      "cantidad": 2,
      "precio_unitario": 18000,
      "porcentaje_iva": 8,
      "tipo_impuesto": "04"
    }
  ],
  "forma_pago": "10",
  "metodo_pago": "10",
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "id": 890,
    "numero": "POS-00045",
    "cude": "cude_sha384_pos_electronico...",
    "qr_url": "https://catalogo-vpfe.dian.gov.co/document/searchqr?...",
    "subtotal": 108500,
    "total_impuestos": 8680,
    "propina": 10000,
    "total": 127180,
    "tiempo_emision_ms": 1140,
    "estado_dian": "Aceptado"
  }
}

Nómina DIANPOST /v1/api/nomina/enviar

Nómina Electrónica Individual (Devengados y Deducciones)

Documento soporte de pago de nómina electrónica con liquidación mensual/quincenal, aportes a salud (4%), pensión (4%), cesantías y cálculo de CUNE.

Reglas Clave de Integración:

Incluye el objeto empleado con su tipo de contrato, sueldo y método de pago de nómina.
El bloque devengados suma básico, auxilio de transporte, comisiones y horas extras.
El bloque deducciones descuenta salud (4%), pensión (4%), libranzas y embargos.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/nomina/enviar" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "periodo": {
    "fecha_inicio": "2026-08-01",
    "fecha_fin": "2026-08-31",
    "fecha_pago": "2026-08-31"
  },
  "empleado": {
    "tipo_documento": "CC",
    "numero_documento": "1014234567",
    "primer_nombre": "Julián",
    "primer_apellido": "Ospina",
    "correo": "julian.ospina@empresa.com",
    "sueldo": 2500000
  },
  "devengados": {
    "basico": {
      "dias_trabajados": 30,
      "sueldo_trabajado": 2500000
    },
    "auxilio_transporte": 162000
  },
  "deducciones": {
    "salud": {
      "porcentaje": 4,
      "valor": 100000
    },
    "pension": {
      "porcentaje": 4,
      "valor": 100000
    }
  },
  "transmitir": true
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "data": {
    "id": 720,
    "consecutivo": "NOM-012",
    "cune": "cune_sha384_nomina_individual...",
    "total_devengado": 3800000,
    "total_deducciones": 315000,
    "total_comprobante": 3485000,
    "estado_dian": "Aceptado"
  }
}

RADIAN (035-038)POST /v1/api/radian/registrar-evento

RADIAN & Factoring (Endoso Electrónico en Propiedad 036)

Registro de endoso en propiedad ante el sistema RADIAN para cesión de derechos económicos de una factura a favor de una Fintech o Banco.

Reglas Clave de Integración:

La factura debe tener previamente los 3 eventos de recepción (030 Acuse, 032 Recibo Bien, 033/034 Aceptación).
El código de evento 036 transfiere la propiedad del título valor a la entidad financiera (Endosatario).
Permite consultar la trazabilidad y tenedor legítimo en /v1/api/radian/hoja-de-vida/:cufe.

Petición en Código

CURL

curl -X POST "https://api.jcflow.com.co/v1/api/radian/registrar-evento" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_test_tu_api_key_aqui" \
  -d '{
  "cufe": "a7c8e9f0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "codigo_evento": "036",
  "endosatario": {
    "tipo_documento": "NIT",
    "numero_documento": "900987654",
    "nombre": "Factor Financiero Colombia S.A.S."
  },
  "observaciones": "Endoso electrónico en propiedad para anticipo de liquidez"
}'

Respuesta DIAN Exitosa (200 OK)

JSON

{
  "success": true,
  "message": "Evento 036 registrado exitosamente en RADIAN",
  "cude_evento": "cude_del_evento_radian_emitido_dian_9876543210..."
}