Spanish API — JCFlow | JCFlow API

🇪🇸 Spanish API

💡 This API is a translation layer over the main engine. All fields are in Spanish to make integration easier for Spanish-speaking developers. Internally uses the same engine — same security, validation, and DIAN transmission.

Available Endpoints

POST/facturacion-es/

Generic — type in body

POST/facturacion-es/factura

Electronic Invoice

POST/facturacion-es/nota-credito

Credit Note

POST/facturacion-es/nota-debito

Debit Note

POST/facturacion-es/documento-soporte

Support Document

POST/facturacion-es/nota-ajuste-ds

Support Doc. Adjustment

POST/facturacion-es/pos

Electronic POS Ticket

POST/facturacion-es/exportacion

Export Invoice

Comparison: Standard API vs Spanish API

❌ Standard API (technical English)

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

Issue an electronic invoice with Spanish field names.

Main Fields

Field	Type	Required	Description
tipo	string	No	Generic endpoint only: "factura", "nc", "nd", "ds", "exportacion"
cliente	object	Yes	Customer data (see table below)
lineas	array	Yes	Document lines. Aliases: productos, items
observaciones	string	No	Notes or observations. Alias: notas
transmitir	boolean	No	true to send to DIAN immediately. Alias: enviar_dian
referencia	string	No	Unique reference from your system (prevents duplicates). Aliases: referencia_externa, id_unico
documento_referencia	integer	No	NC/ND only: ID of the original document
concepto_nota	string	No	NC/ND only: concept code
ambiente	string	No	1=Production, 2=Testing (default)
asincrono	boolean	No	true = 202 response + background processing
totales	object	No	Manual totals. If omitted, auto-calculated from lines.
impuestos	array	No	Manual global taxes. If omitted, aggregated from lines.

Object: cliente

Field	Type	Required	Description
nombre	string	Yes	Business name or customer name
numero_identificacion	string	Yes	NIT or ID number. Aliases: nit, cedula
correo	string	Yes	Email for document delivery. Alias: correo_electronico
direccion	string	No	Customer address
telefono	string	No	Contact phone
tipo_documento	integer	No	13=CC, 31=NIT, 22=CE, 41=Pasaporte
tipo_organizacion	integer	No	1=Legal Entity, 2=Natural Person

Object: lineas[]

Field	Type	Required	Description
descripcion	string	Yes	Product/service description. Aliases: producto, nombre_producto
cantidad	number	Yes	Quantity (default: 1)
precio	number	Yes	Unit price. Aliases: precio_unitario, valor_unitario
iva	number	No	⚡ Shortcut: IVA % (e.g., 19). DIAN code: 01
inc	number	No	⚡ Shortcut: INC % - National Consumption Tax (e.g., 8). DIAN code: 04
ica	number	No	⚡ Shortcut: ICA % (e.g., 1.04). DIAN code: 03
retefuente	number	No	⚡ Shortcut: ReteFuente %. DIAN code: 07
reteiva	number	No	⚡ Shortcut: ReteIVA %. DIAN code: 06
reteica	number	No	⚡ Shortcut: ReteICA %. DIAN code: 05
bolsas	number	No	⚡ Shortcut: Plastic Bags Tax %. DIAN code: 22
impuestos	array	No	Detailed array (alternative to shortcuts). Each: { tipo: "iva"\|"inc"\|"01"\|"04", porcentaje, base, valor }
codigo	string	No	Product code. Aliases: codigo_producto, referencia
unidad_medida	string	No	Unit of measure code (default: "94" = Unit)

⚡ Tax Shortcuts: Pass iva: 19, inc: 8, ica: 1.04, etc. directly in each line. The system auto-calculates base, amount, and totals by tax type. Combine multiple: { iva: 19, inc: 8 } for restaurants. For non-standard taxes use the impuestos array with { tipo, porcentaje }.

🧮 Auto-calculation: If you don't send totals or global taxes, the system auto-calculates them from lines. Subtotal, total taxes, payable amount and tax_totals grouped by type are auto-generated.

⚙️ Automatic Rules in Production (DIAN Annex 1.8):

Synchronous Transmission: In the production environment (or when using production API keys sk_live_...), document transmission is always processed synchronously (SendBillSync) to prevent rejections due to lack of authorization for asynchronous batch processing.
Suppression of Empty Taxes: To avoid restrictive warnings (such as FAX05 and FAX14 notifications) on the DIAN portal, the system dynamically suppresses empty ICA (03) and INC (04) blocks with base/percentage at 0.00 when operating in production.
Date and Signature Alignment: The emission date and time in the XML document are automatically synchronized in real-time with the digital signature timestamp (using Colombia time zone -05:00), completely eliminating rejections caused by rule FAD09e.
Transactional Recalculation of CUFE/CUDE: The CUFE/CUDE code is dynamically recalculated and injected, integrating the official time offset of -05:00 in both the mathematical calculation and the IssueTime tag of the XML, ensuring exact consistency.

Example: Electronic Invoice

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

Try EndpointPOST /facturacion-es/factura

Your API Key

Request Body (JSON)

POST /facturacion-es/nota-credito

Issue a credit note. Requires documento_referencia (original invoice ID).

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

Issue a debit note. Same structure as credit note.

POST /facturacion-es/documento-soporte

Issue a support document for providers not required to invoice.

POST /facturacion-es/

Single endpoint for all types. The type is sent in the tipo field of the body.

Accepted values for tipo:

Value	Document
`"factura"` o `"fe"`	Electronic Invoice
`"nota_credito"` o `"nc"`	Credit Note
`"nota_debito"` o `"nd"`	Debit Note
`"documento_soporte"` o `"ds"`	Support Document
`"nota_ajuste_ds"` o `"na"`	DS Adjustment Note
`"exportacion"` o `"fx"`	Export Invoice

Example: Multiple taxes (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
}

Example: Detailed tax array

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
}

Aliases Table

Many fields accept multiple names for flexibility:

Main field	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`