Documento Soporte en Adquisiciones (DS)
El Documento Soporte Electrónico en adquisiciones efectuadas a sujetos no obligados a expedir factura de venta permite soportar costos y deducciones en el impuesto sobre la renta y descontables en IVA. JCFlow se encarga de calcular el CUDS, firmar el XML con XAdES y transmitir a la DIAN en tiempo real.
Auto-Resolución de Proveedor
No requiere que el proveedor tenga RUT si es persona natural con Cédula o Pasaporte.
Cálculo de CUDS SHA-384
Generación y firmado criptográfico del código único conforme a la Resolución DIAN 000167.
Notas de Ajuste (Tipo 95)
Anulación total o corrección de valores con referencia al CUDS original.
Emitir Documento Soporte Electrónico
/v1/api/documentos-soporte/emitirCrea, firma y transmite un Documento Soporte (Código 05) a la DIAN.
Parámetros principales del payload:
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| proveedor | object | Sí | Datos del proveedor no obligado a facturar (persona natural / jurídica) |
| lineas | array | Sí | Detalle de compras o servicios adquiridos con sus retenciones |
| forma_pago | string | No | 1 = Contado, 2 = Crédito (default: 1) |
| metodo_pago | string | No | 10 = Efectivo, 42 = Transferencia, 48 = Tarjeta Crédito, etc. (default: 10) |
| fecha_emision | string | No | Fecha de la adquisición YYYY-MM-DD (default: hoy) |
| observaciones | string | No | Notas u observaciones del documento soporte |
| transmitir | boolean | No | true para firmar y enviar a DIAN inmediatamente (default: true) |
| centro_costos | string | No | Centro de costos o cuenta contable interna |
Objeto Proveedor
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| numero_identificacion | string | Sí | Número de cédula o NIT del proveedor no obligado |
| nombre | string | Sí | Nombre completo o razón social del proveedor |
| tipo_documento | string | No | 13 = Cédula de Ciudadanía, 22 = Cédula de Extranjería, 41 = Pasaporte, 31 = NIT (default: 13) |
| correo | string | No | Correo electrónico para notificación |
| telefono | string | No | Teléfono de contacto |
| direccion | string | No | Dirección de residencia o establecimiento |
| municipio | string | No | Código DANE del municipio (ej: 11001 para Bogotá) |
| tipo_regimen | string | No | 49 = No responsable de IVA (default) |
Objeto Líneas de Compra
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| descripcion | string | Sí | Descripción del bien o servicio adquirido |
| cantidad | number | Sí | Cantidad de unidades adquiridas |
| precio_unitario | number | Sí | Valor unitario antes de retenciones |
| codigo | string | No | Código interno del servicio o insumo |
| unidad_medida | string | No | Código unidad DIAN (default: 94 = Unidad, E48 = Servicio) |
| retenciones | array | No | Array de retenciones aplicadas: 07=ReteFuente, 05=ReteICA |
Ejemplos de Consumo
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",
"telefono": "3124567890",
"direccion": "Vereda San José Finca El Roble",
"municipio": "25899"
},
"forma_pago": "1",
"metodo_pago": "10",
"lineas": [
{
"codigo": "SERV-ELEC-01",
"descripcion": "Mantenimiento eléctrico preventivo de oficinas",
"cantidad": 1,
"precio_unitario": 850000,
"retenciones": [
{ "tipo": "07", "porcentaje": 4, "base": 850000, "valor": 34000 },
{ "tipo": "05", "porcentaje": 0.966, "base": 850000, "valor": 8211 }
]
}
],
"observaciones": "Cuenta de cobro No. 14 por servicios de mantenimiento",
"transmitir": true
}'Respuesta Exitosa (200 OK)
{
"success": true,
"message": "Documento Soporte Electrónico emitido exitosamente",
"data": {
"id": 302,
"prefijo": "DS",
"numero": "0089",
"cuds": "f47ac10b58cc4372a5670e02b2f3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7",
"qr_url": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=f47ac10b...",
"subtotal": 850000,
"total_retenciones": 42211,
"total": 807789,
"estado_dian": "Aceptado",
"pdf_url": "https://api.jcflow.com.co/v1/api/documentos-soporte/302/pdf",
"xml_url": "https://api.jcflow.com.co/v1/api/documentos-soporte/302/xml"
}
}Nota de Ajuste a Documento Soporte (Tipo 95)
/v1/api/documentos-soporte/:id/nota-ajusteEmite una nota de ajuste para corregir o anular un Documento Soporte previo.
La Nota de Ajuste permite reversar total o parcialmente los valores de un Documento Soporte previamente aceptado por la DIAN.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| documento_referencia | integer | Sí | ID del Documento Soporte original en JCFlow |
| concepto_nota | string | Sí | 1 = Devolución o anulación, 2 = Anulación por no cobro, 3 = Ajuste de precio |
| motivo | string | Sí | Explicación del motivo del ajuste o anulación |
| lineas | array | No | Líneas corregidas (para ajustes parciales de valor) |
| transmitir | boolean | No | true para transmitir a DIAN inmediatamente |
Ejemplo de Petición
curl -X POST "https://api.jcflow.com.co/v1/api/documentos-soporte/302/nota-ajuste" \
-H "Content-Type: application/json" \
-H "X-Api-Key: sk_test_tu_api_key_aqui" \
-d '{
"documento_referencia": 302,
"concepto_nota": "1",
"motivo": "Anulación de cuenta de cobro por no ejecución del servicio",
"transmitir": true
}'Consultas y Descarga de Archivos
/v1/api/documentos-soporteListado paginado de documentos soporte con filtros por fecha, estado y proveedor.
/v1/api/documentos-soporte/:idObtiene el detalle completo de un Documento Soporte por su ID.
/v1/api/documentos-soporte/:id/consultar-dianConsulta el estado síncrono del CUDS directamente en los servidores de la DIAN.
/v1/api/documentos-soporte/:id/pdfDescarga la representación gráfica oficial en formato PDF.
/v1/api/documentos-soporte/:id/xmlDescarga el archivo XML UBL 2.1 firmado electrónicamente con XAdES.