La integración con la plataforma de facturación electrónica se realiza mediante llamadas REST utilizando JSON.

El flujo básico de integración es el siguiente:

Enviar un JSON con el siguente contenido:

1. Encabezado del documento Obligatorio (1 vez por documento)
2. Detalles (Items) Obligatorio (repetible)
3. Impuestos (Tax) del documento Obligatorio (1 vez por documento)
4. Salud (Area datos Salud) Opcional, solo para facturas del sector salud (1 vez por documento)
5. Referencia Opcional, para documentos que referencian otro documento
6. OrdenPedido Opcional, cuando el documento contiene datos de una orden
7. POS Opcional, para documentos generados desde un punto de venta

Nota! El JSON puede contener hasta 50 documentos a la vez.

Opcionalmente enviar el archivo PDF

El área de datos Salud es opcional. Si se envía, el documento será marcado como factura de Salud.

Para mantener compatibilidad con integraciones anteriores, el bloque de impuestos puede enviarse como Tax o como Impuestos.

Los bloques Referencia, OrdenPedido y POS son opcionales y deben enviarse únicamente cuando sean necesarios para el documento.

Los datos RIPS no forman parte de esta versión del endpoint y serán incorporados posteriormente.

En el JSON de Tax, los impuestos deben enviarse agrupados por tipo y porcentaje.

Si no se envían, la API utiliza los siguientes valores predeterminados:

Los campos impuestoperc2, impuestovalor2 e impuestotipo2 permiten indicar una segunda imposición en el detalle y son opcionales.

• fechacompra: fecha predeterminada del sistema
• esdescuento: false
• tercerobeneficiarioide: vacío
• tercerobeneficiariotipoide: vacío
• tercerobeneficiarionombre: vacío
• estercerobeneficiario: false

Es decir:

• Se envía una sola vez por factura
• Se agrupan todos los ítems que tengan el mismo impuesto
• Si el mismo impuesto tiene diferentes porcentajes, se deben separar
• Se debe enviar el total del impuesto por cada grupo

Item 1 → IVA 19%
Item 2 → IVA 19%
Item 3 → IVA 5%

Resultado:

IVA 19% → base total + valor total
IVA 5%  → base total + valor total
            

El valor del impuesto enviado debe coincidir exactamente con la suma de los impuestos calculados en los ítems.

Estos son los errores más frecuentes al integrar con facturación electrónica:

• Valores sin 2 decimales
  Ejemplo incorrecto: 1000
  Correcto: 1000,00
• Formato de fecha inválido
  Debe ser DD/MM/AAAA
• NIT o DV incorrecto
  Verificar que el NIT del cliente sea válido y coincida con el DV
• Totales no coinciden
  El valor total debe ser igual a:
  Bruto + Impuestos - Descuentos + Cargos
• Impuestos mal calculados
  El valor del impuesto debe corresponder al porcentaje enviado
• Campos obligatorios vacíos
  Ejemplo: cliente, ciudad, dirección, moneda, etc.
• Correos electrónicos inválidos
  El sistema valida formato antes de enviar
• Uso incorrecto de separadores
  Usar coma para decimales y sin puntos de miles

Se recomienda validar los datos antes de enviar la factura para evitar rechazos.