Skip to main content
El servicio permite a los usuarios registrar facturas de venta en la plataforma en línea en formato JSON. Si el cliente no existe en la plataforma, se registra automáticamente con los datos enviados en la solicitud. El método de solicitud es POST y se requiere un encabezado “Authorization” para la autenticación, que debe contener un token JWT obtenido previamente del servicio de autenticación.

​
Prerequisitos

Antes de realizar el registro de una factura de venta, se debe contar con los siguientes datos:
  • Token solicitado mediante el API de autenticación
  • Resolución de facturación vigente configurada en la plataforma para el prefijo y consecutivo que se va a registrar
  • Impuestos configurados en la plataforma con el código y porcentaje que se enviarán en los detalles
  • Para facturación electrónica, la sucursal no debe tener facturas, notas crédito ni notas débito con error de envío a la DIAN

​
Registrar factura de venta

Request URL: https://{{Ambiente}}/API_FE/api/DocumentosElectronicos/FacturaInsertar
Tipo: POST
Content Type: application/json

​
Datos del documento

​
string
required
Código del tipo de operación de la factura de venta. Se envía como texto de dos dígitos (ej. “10”).
​
string
required
Fecha de creación del documento. Para facturación electrónica debe ser la fecha actual.
​
string
Fecha de vencimiento del documento. Si no se envía, se calcula con los días de crédito del cliente o, en su defecto, con los días de vencimiento configurados en la resolución de facturación.
​
string
Prefijo de la resolución con la que se registrará el documento (máx. 20 caracteres).
​
int
required
Consecutivo del documento.
​
int
Parámetro interno de la plataforma.
​
string
Número de la orden de compra (máx. 60 caracteres).
​
string
Fecha de la orden de compra.
​
string
Código de la moneda del documento, según la tabla de monedas. Si no se envía, se utiliza la moneda configurada en la plataforma.
​
number
Tasa de cambio. Es obligatoria cuando la moneda es diferente al peso colombiano (COP).
​
string
Código DIAN de la forma de pago (1: Contado, 2: Crédito). Debe estar configurada en la plataforma.
​
string
Observaciones del documento (máx. 1500 caracteres).
​
string
Descripción del área o departamento del cliente a donde se dirige el documento (centro de costo), máx. 100 caracteres.

​
Datos del cliente

​
int
required
Código del tipo de documento de identificación del cliente.
​
string
required
Número de identificación del cliente, sin puntos, sin comas y sin espacios (máx. 20 caracteres).
​
int
required
Tipo de persona del cliente.
​
string
required
Primer nombre del cliente si es persona natural; en caso contrario, la razón social (máx. 250 caracteres).
​
string
Segundo nombre del cliente.
​
string
Primer apellido del cliente.
​
string
Segundo apellido del cliente.
​
string
Dirección del cliente (máx. 200 caracteres).
​
string
Número de celular del cliente, sin puntos, sin comas y sin espacios (máx. 20 caracteres).
​
string
required
Email del cliente para el envío del documento electrónico (máx. 400 caracteres).
​
string
Responsabilidad tributaria del cliente.
​
string
País del cliente, código alfa-2 según la tabla de países (ej. “CO”).
​
string
Ciudad del cliente, código de municipio de 5 dígitos según la tabla de municipios (ej. “11001”).

​
Detalles del documento

​
array
required
Detalles (conceptos o productos) del documento. Debe contener al menos un detalle.

​
Terceros y documentos referenciados

​
array
Terceros adicionales del documento. Opcional. No se debe incluir al cliente principal.
​
array
Documentos referenciados en la factura. Opcional.

​
Validaciones

El servicio realiza las siguientes validaciones antes de registrar el documento. Si alguna no se cumple, no se registra la factura y se retorna el error correspondiente. Resolución y consecutivo
  • El prefijo y el consecutivo deben corresponder a una resolución de facturación configurada en la plataforma y vigente a la fecha actual.
  • El consecutivo no debe estar registrado previamente en la plataforma.
  • Para facturación electrónica, la sucursal no debe tener facturas, notas crédito ni notas débito con error de envío a la DIAN.
Fechas
  • Para facturación electrónica, la FechaInicio debe ser la fecha actual; no se permiten fechas pasadas ni futuras.
  • La FechaVencimiento es obligatoria si el cliente no tiene días de crédito y la resolución no tiene días de vencimiento configurados.
Cliente y terceros
  • Los datos del cliente deben estar completos para la emisión del documento.
  • El cliente principal no debe enviarse dentro de FacturasTerceros.
  • La sumatoria del porcentaje de participación de los terceros debe ser exactamente 100 %.
Moneda y forma de pago
  • La moneda enviada debe estar configurada en la plataforma. Si es diferente a COP, la TasaCambio es obligatoria.
  • La forma de pago enviada debe estar configurada en la plataforma.
Detalles e impuestos
  • El ValorTotal de cada detalle debe ser igual a (Cantidad × ValorUnitario) − Descuento, con una tolerancia de ±10.
  • Los valores se redondean según el número de decimales configurado en la resolución de facturación.
  • El código y el porcentaje de cada impuesto deben estar configurados en la plataforma.
  • El ValorImpuesto debe ser igual a la base del detalle (Cantidad × ValorUnitario − Descuento) × Porcentaje / 100, con una tolerancia de ±1. Para la ReteIVA (05), la base es el valor del IVA del detalle.
Tipos de operación
  • AIU (09): al menos un detalle debe estar marcado con AIU = true, y el IVA solo se admite en ese detalle.
  • Mandato (11): todos los detalles deben tener un mandante.
  • Transporte (12): al menos un detalle debe tener Remesa.TipoServicio = true, con RadicadoRemesa, NumeroRemesa, CantidadTransportada y UnidadMedida.

​
Respuesta

​
string
Resultado de la operación: “OK” o “Error”.
​
int
Código único de la factura registrada (ID). Retorna -1 cuando ocurre un error.
​
string
“Transacción Exitosa” cuando el registro es correcto, o el detalle del error precedido de “Error:”.