API en Español — JCFlow | JCFlow API

🇪🇸 API en Español

💡 Esta API es una capa de traducción sobre el motor principal. Todos los campos están en español para facilitar la integración a desarrolladores hispanohablantes. Internamente usa el mismo motor — misma seguridad, validación y transmisión DIAN.

Endpoints Disponibles

POST/facturacion-es/

Genérico — tipo en el body

POST/facturacion-es/factura

Factura Electrónica

POST/facturacion-es/nota-credito

Nota Crédito

POST/facturacion-es/nota-debito

Nota Débito

POST/facturacion-es/documento-soporte

Documento Soporte

POST/facturacion-es/nota-ajuste-ds

Nota Ajuste Doc. Soporte

POST/facturacion-es/pos

Tiquete POS Electrónico

POST/facturacion-es/exportacion

Factura de Exportación

Comparación: API Estándar vs API en Español

❌ API Estándar (inglés técnico)

JSON

{
  "id_tipo_documento": 1,
  "customer": {
    "identification_number": "900123456",
    "name": "Empresa XYZ"
  },
  "invoice_lines": [
    {
      "price_amount": 50000,
      "invoiced_quantity": 1,
      "description": "Producto"
    }
  ],
  "transmit": true
}

✅ API en Español

JSON

{
  "cliente": {
    "numero_identificacion": "900123456",
    "nombre": "Empresa XYZ"
  },
  "lineas": [
    {
      "precio": 50000,
      "cantidad": 1,
      "descripcion": "Producto",
      "iva": 19
    }
  ],
  "transmitir": true
}

POST /facturacion-es/factura

Emitir una factura electrónica con campos en español.

Campos Principales

Campo	Tipo	Requerido	Descripción
tipo	string	No	Solo endpoint genérico: "factura", "nc", "nd", "ds", "exportacion"
cliente	object	Sí	Datos del cliente (ver tabla abajo)
lineas	array	Sí	Líneas del documento. Alias: productos, items
observaciones	string	No	Notas u observaciones. Alias: notas
transmitir	boolean	No	true para enviar a DIAN inmediatamente. Alias: enviar_dian
referencia	string	No	Referencia única de tu sistema (previene duplicados). Alias: referencia_externa, id_unico
documento_referencia	integer	No	Solo NC/ND: ID del documento original
concepto_nota	string	No	Solo NC/ND: código del concepto
ambiente	string	No	1=Producción, 2=Habilitación (default)
asincrono	boolean	No	true = respuesta 202 + procesamiento en background
totales	object	No	Totales manuales. Si se omite, se auto-calculan desde las líneas.
impuestos	array	No	Impuestos globales manuales. Si se omite, se agrupan desde las líneas.

Objeto: cliente

Campo	Tipo	Requerido	Descripción
nombre	string	Sí	Razón social o nombre del cliente
numero_identificacion	string	Sí	NIT o cédula. Alias: nit, cedula
correo	string	Sí	Email para envío del documento. Alias: correo_electronico
direccion	string	No	Dirección del cliente
telefono	string	No	Teléfono de contacto
tipo_documento	integer	No	13=CC, 31=NIT, 22=CE, 41=Pasaporte
tipo_organizacion	integer	No	1=Persona Jurídica, 2=Persona Natural

Objeto: lineas[]

Campo	Tipo	Requerido	Descripción
descripcion	string	Sí	Descripción del producto/servicio. Alias: producto, nombre_producto
cantidad	number	Sí	Cantidad (default: 1)
precio	number	Sí	Precio unitario. Alias: precio_unitario, valor_unitario
iva	number	No	⚡ Shortcut: % de IVA (ej: 19). Código DIAN: 01
inc	number	No	⚡ Shortcut: % INC - Impuesto Nacional al Consumo (ej: 8). Código DIAN: 04
ica	number	No	⚡ Shortcut: % ICA (ej: 1.04). Código DIAN: 03
retefuente	number	No	⚡ Shortcut: % ReteFuente. Código DIAN: 07
reteiva	number	No	⚡ Shortcut: % ReteIVA. Código DIAN: 06
reteica	number	No	⚡ Shortcut: % ReteICA. Código DIAN: 05
bolsas	number	No	⚡ Shortcut: % Imp. Bolsas Plásticas. Código DIAN: 22
impuestos	array	No	Array detallado (alternativa a shortcuts). Cada uno: { tipo: "iva"\|"inc"\|"01"\|"04", porcentaje, base, valor }
codigo	string	No	Código del producto. Alias: codigo_producto, referencia
unidad_medida	string	No	Código unidad de medida (default: "94" = Unidad)

⚡ Shortcuts de Impuestos: Pasa iva: 19, inc: 8, ica: 1.04, etc. directamente en cada línea. El sistema auto-calcula base, valor, y totaliza por tipo de impuesto. También puedes combinar varios: { iva: 19, inc: 8 } para restaurantes. Para impuestos no estándar usa el array impuestos con { tipo, porcentaje }.

🧮 Auto-cálculo: Si no envías totales ni impuestos globales, el sistema los calcula automáticamente sumando las líneas. Subtotal, total de impuestos, total a pagar y tax_totals agrupados por tipo se generan solos.

⚙️ Reglas Automáticas en Producción (DIAN Anexo 1.8):

Transmisión Síncrona: En el ambiente de producción (o utilizando API keys de producción sk_live_...), la transmisión de los documentos se procesa siempre de forma síncrona (SendBillSync) para prevenir rechazos por falta de autorización para envíos por lotes asíncronos.
Supresión de Impuestos Vacíos: Para evitar advertencias restrictivas (como las notificaciones FAX05 y FAX14) en el portal oficial de la DIAN, el sistema suprime dinámicamente los bloques vacíos ICA (03) e INC (04) con base/porcentaje en 0.00 al operar en producción.
Alineación de Fechas y Firma: La fecha y hora de emisión del documento XML se auto-sincronizan en tiempo real con la marca de tiempo de la firma digital (con zona horaria Colombia -05:00), eliminando de raíz el rechazo por regla FAD09e.
Recálculo Transaccional del CUFE/CUDE: El código CUFE/CUDE se calcula e inyecta dinámicamente integrando el desfase horario oficial de -05:00 tanto en el cálculo matemático como en el tag IssueTime del XML, garantizando la consistencia exacta requerida.

Ejemplo: Factura Electrónica

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" \
  -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
    }
  ],
  "observaciones": "Entrega en bodega principal",
  "transmitir": true,
  "referencia": "VENTA-2026-001"
}'

Probar EndpointPOST /facturacion-es/factura

Tu API Key

Request Body (JSON)

POST /facturacion-es/nota-credito

Emitir una nota crédito. Requiere documento_referencia (ID de la factura original).

JSON

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

POST /facturacion-es/nota-debito

Emitir una nota débito. Misma estructura que nota crédito.

POST /facturacion-es/documento-soporte

Emitir documento soporte para proveedores no obligados a facturar.

POST /facturacion-es/

Endpoint único para todos los tipos. El tipo se envía en el campo tipo del body.

Valores aceptados para tipo:

Valor	Documento
`"factura"` o `"fe"`	Factura Electrónica
`"nota_credito"` o `"nc"`	Nota Crédito
`"nota_debito"` o `"nd"`	Nota Débito
`"documento_soporte"` o `"ds"`	Documento Soporte
`"nota_ajuste_ds"` o `"na"`	Nota Ajuste DS
`"exportacion"` o `"fx"`	Factura de Exportación

Ejemplo: Múltiples impuestos (IVA + INC)

JSON

{
  "tipo": "factura",
  "cliente": {
    "nombre": "Restaurante La Sazón",
    "nit": "900333444",
    "correo": "contable@lasazon.co"
  },
  "lineas": [
    {
      "producto": "Almuerzo ejecutivo",
      "cantidad": 100,
      "precio": 25000,
      "iva": 19,
      "inc": 8
    },
    {
      "producto": "Servicio de meseros",
      "cantidad": 1,
      "precio": 500000,
      "iva": 19
    }
  ],
  "notas": "Evento 15 de mayo — 100 personas",
  "transmitir": true
}

Ejemplo: Array detallado de impuestos

JSON

{
  "cliente": {
    "nombre": "Importadora ABC",
    "nit": "900555666",
    "correo": "compras@abc.com"
  },
  "lineas": [
    {
      "descripcion": "Maquinaria industrial",
      "cantidad": 1,
      "precio": 50000000,
      "impuestos": [
        {
          "tipo": "iva",
          "porcentaje": 19
        },
        {
          "tipo": "advalorem",
          "porcentaje": 5
        }
      ]
    }
  ],
  "transmitir": true
}

Tabla de Aliases

Muchos campos aceptan múltiples nombres para mayor flexibilidad:

Campo principal	Aliases
`nombre`	`razon_social`
`numero_identificacion`	`nit`, `cedula`
`correo`	`correo_electronico`, `email`
`descripcion`	`producto`, `nombre_producto`
`precio`	`precio_unitario`, `valor_unitario`
`lineas`	`productos`, `items`
`observaciones`	`notas`
`transmitir`	`enviar_dian`
`referencia`	`referencia_externa`, `id_unico`