Developer Quickstart Guide

Examples by DIAN Document Type

Explore real-world use cases ready to copy and paste into your application. Select any document type to view the fast minimal payload or the comprehensive payload with full DIAN metadata, along with examples in cURL, JavaScript, Python, and PHP.

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

Standard Electronic Invoice (General Sales)

Invoice for goods or services on credit/cash with automatic calculation of VAT (19%), withholding tax and ReteICA.

Key Integration Rules:

Use shortcuts iva: 19 or inc: 8 inside line items so the engine auto-calculates subtotals, tax totals and totals.
If payment form is "credito", include fecha_vencimiento and dias_credito.
Customer verification digit (DV) is automatically calculated if NIT is provided.

Code Request

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
}'

Successful DIAN Response (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

Healthcare Sector Invoice (RIPS / MinSalud)

Invoice for Clinics, Hospitals, HMOs and Health Professionals. Integrates healthcare provider code, patient data, payment mode, CUPS codes and copays.

Key Integration Rules:

Include tipo_operacion: "11" to trigger healthcare sector DIAN validations.
The salud block specifies provider code, contract mode (01=Fee for service, 02=Capitation) and coverage.
Each medical line must specify the procedure CUPS code and beneficiary patient data.

Code Request

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
}'

Successful DIAN Response (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

Freight Transport Invoice (RNDC)

Freight transport invoice regulated by the Ministry of Transport. Includes RNDC manifest, dispatch note, truck plates, route and freight costs.

Key Integration Rules:

Use tipo_operacion: "12" for ground freight transportation.
The transporte object holds remesa_numero, manifiesto_numero, vehiculo_placa, origin and destination with DANE codes.
Ground freight transport is VAT-exempt (iva: 0) and subject to 1% withholding tax.

Code Request

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
}'

Successful DIAN Response (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

Export Invoice (Multi-currency USD & Incoterms)

Invoice for international clients in foreign currency (USD, EUR) with daily TRM rate and Incoterms (CIF, FOB, EXW, etc.).

Key Integration Rules:

Specify tipo_documento: "02" or tipo: "exportacion".
Include moneda: "USD" and tasa_cambio object with the official TRM rate.
Define incoterms: "FOB" / "CIF" / "EXW" according to international terms.

Code Request

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
}'

Successful DIAN Response (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

Fuel & Hydrocarbons Invoice (Gas Stations)

Gas stations invoice with National Fuel Tax (Code 24), Fuel Surcharge (Code 25) and Sordicom (Code 26).

Key Integration Rules:

Use unit_measure: "GLL" (Gallons) or "LTR" (Liters).
Pass specific taxes in the array: tipo: "combustibles" (24) and tipo: "sobretasa_combustibles" (25).
Fuels do not carry standard VAT, but nominal taxes per dispensed gallon.

Code Request

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
}'

Successful DIAN Response (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

Credit Note (Void or Adjustment with CUFE)

Credit Note issue referencing a previous electronic invoice via ID or CUFE, with official DIAN concept code.

Key Integration Rules:

Specify documento_referencia (invoice internal ID) or cufe_factura_referencia.
DIAN concepts: 1 = Total refund, 2 = Void due to non-charge, 3 = Partial discount, 4 = Price adjustment.
For partial refunds, send only the lines and quantities to be deducted.

Code Request

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
}'

Successful DIAN Response (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

Support Document for Non-Invoicing Vendors (Type 05)

Expense support for purchases or services from individuals not required to issue invoices (no RUT/DV required).

Key Integration Rules:

The vendor only requires citizen ID (tipo_documento: "13" or "CC") and full name.
Apply withholding tax (tipo: "07") and ReteICA (tipo: "05") as required.
Automatically generates CUDS SHA-384 with authorized DIAN prefix and number range.

Code Request

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
}'

Successful DIAN Response (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

Electronic POS (Cash Register Receipt)

Instant (< 2s) POS receipt for cash registers, supermarkets and restaurants. Includes voluntary tips and split payments.

Key Integration Rules:

If customer is omitted, automatically defaults to Final Consumer (NIT 222222222222).
Allows multiple payment methods in the pagos array (cash + card terminal).
Generates thermal receipt PDF via /v1/api/pos/:id/tirilla?width=80.

Code Request

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
}'

Successful DIAN Response (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

Electronic Payroll (Earnings & Deductions)

Electronic payroll payment document with earnings, health deduction (4%), pension (4%), severance and CUNE calculation.

Key Integration Rules:

Include empleado object with contract type, salary and bank disbursement method.
The devengados block aggregates base salary, transport aid, commissions and overtime.
The deducciones block subtracts health (4%), pension (4%), loans and withholdings.

Code Request

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
}'

Successful DIAN Response (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 (Electronic Endorsement 036)

Electronic property endorsement registration on DIAN RADIAN for factoring with Fintechs or Banks.

Key Integration Rules:

The invoice must already have all 3 incoming events (030 Acknowledgment, 032 Goods Receipt, 033/034 Acceptance).
Event code 036 transfers legal ownership to the financial institution (Endosatario).
Allows real-time query of legitimate holder at /v1/api/radian/hoja-de-vida/:cufe.

Code Request

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"
}'

Successful DIAN Response (200 OK)

JSON

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