La API de FactuColombia está diseñada para facilitar la integración de soluciones de
facturación electrónica en Colombia. Proporciona a los desarrolladores las herramientas
necesarias para crear, validar y gestionar documentos electrónicos como facturas y notas crédito,
cumpliendo con las normativas establecidas por la DIAN.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la solicitud
Encabezado
Tipo
Descripción
AuthorizationstringBearer <access_token> — Token de acceso OAuth2. Requerido
Content-Typestringapplication/json. Requerido
Acceptstringapplication/json. Opcional
Estructura para crear la factura
Para crear una factura, el cuerpo de la solicitud debe organizarse en 3 secciones:
1Datos generales de la factura
2Datos del adquiriente (customer)
3Items del producto o servicio (items)
Parámetros del cuerpo (Body)
Parámetros Factura Mandatorios
CampoTipoDescripción
reference_codeStringRequiredCódigo único de referencia de la factura en el sistema e-commerce o plataforma que origina la factura. Si ya existe una factura con el mismo código, se retornarán los datos de la factura existente.
rateNumericRequiredPorcentaje de la retención aplicada. Ej: "3.50".
amountNumericValor de la retención. Si no se envía, se calcula automáticamente con base en el precio y la tasa.
Descuentos y cargos del ítem — items[].allowance_charges[]
CampoTipoDescripción
charge_indicatorIntegerRequired0 = Descuento, 1 = Cargo adicional al precio del ítem.
allowance_charge_reasonStringDescripción o motivo del descuento o cargo. Ej: "Descuento por volumen".
amountNumericRequiredValor del descuento o cargo aplicado al ítem.
base_amountNumericBase sobre la cual se calcula el descuento o cargo.
Período de facturación — billing_period{}
Aplica cuando se factura un servicio continuo con un período de prestación definido (ej: servicios públicos, arrendamientos, suscripciones).
CampoTipoDescripción
start_dateStringRequiredFecha de inicio del período de facturación. Formato: YYYY-MM-DD.
end_dateStringRequiredFecha de fin del período de facturación. Formato: YYYY-MM-DD.
start_timeStringHora de inicio. Formato: HH:mm:ss. Opcional.
end_timeStringHora de fin. Formato: HH:mm:ss. Opcional.
Descuentos/Cargos globales — allowance_charges[]
Descuentos o cargos adicionales que aplican sobre el total de la factura (no sobre ítems individuales).
CampoTipoDescripción
charge_indicatorIntegerRequired0 = Descuento global, 1 = Cargo global a la factura.
allowance_charge_reasonStringDescripción del descuento o cargo global. Ej: "Descuento comercial".
amountNumericRequiredValor total del descuento o cargo a nivel de factura.
base_amountNumericBase imponible sobre la que se aplica el descuento o cargo.
Redondeo — cash_rounding_amount
CampoTipoDescripción
cash_rounding_amountNumericValor de ajuste por redondeo en el total de la factura. Enviar "0.00" si no aplica. Puede ser positivo o negativo. Máx. 2 decimales.
Orden de compra — order_reference{}
CampoTipoDescripción
id_orderStringNúmero o identificador de la orden de compra asociada a esta factura.
issue_date_orderStringFecha de emisión de la orden de compra. Formato: YYYY-MM-DD.
Campos del sector salud — health_fields{}
Aplica únicamente para facturas del sector salud. Permite registrar información de la atención médica según los requisitos de la DIAN para el sector.
CampoTipoDescripción
user_codeStringCódigo del usuario o paciente en el sistema del prestador de salud.
sequence_numberIntegerNúmero de secuencia de la atención dentro del contrato.
copay_amountNumericValor de la cuota moderadora o copago a cargo del paciente.
deductible_amountNumericValor del deducible de la póliza aplicado en esta atención.
authorized_amountNumericMonto autorizado por la aseguradora para la atención prestada.
Importante
Si por algún motivo los ítems tienen valores diferentes a los esperados por la API, este endpoint puede
rechazar la factura. En ese caso revise los totales y la estructura de los impuestos antes de volver a enviar la solicitud. Para cualquier duda consulte la sección de
buenas prácticas de facturación.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la solicitud
Encabezado
Valor
Tipo
Content-Type
application/json
Requerido
Authorization
Bearer <access_token>
Requerido
Accept
application/json
Opcional
Tener en cuenta
Si envía un reference_code ya procesado, recibirá los datos correspondientes a la factura existente.
Si el endpoint responde con error 400 Conflict, debe eliminar la factura usando la referencia y proceder con la creación de una nueva factura.
Guíese por el campo is_validated: true validada, false sin validar.
Campo
Tipo
Descripción
reference_codestringCódigo único de referencia interna. Máx. 50 caracteres. Debe ser único por factura.
documentstringTipo de documento. 01 = Factura de venta, 02 = Factura de exportación.
numbering_range_idintegerID del rango de numeración habilitado y vigente en la DIAN.
operation_typestringTipo de operación: 10 estándar, 20 exportación, 30 no aplica.
observationstringObservación libre asociada a la factura. Opcional.
payment_detailsarrayArreglo con los métodos y condiciones de pago. Mínimo 1 elemento.
customerobjectDatos del adquiriente: identificación, empresa, dirección, contacto.
itemsarrayLista de productos o servicios. Mínimo 1 ítem por factura.
cash_rounding_amountstringAjuste de redondeo al total. Usar "0.00" si no aplica.
prepayment_detailsarrayDetalles de anticipos o pagos previos asociados a la factura. Opcional.
Esta sección describe los campos necesarios para la estructura de facturas. Aquí encontrará el tipo de datos que
necesita para cada campo, así como la descripción de los campos correspondientes.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la solicitud
Encabezado
Valor
Tipo
Content-Type—application/json
Authorization—Bearer <access_token>
Estructura para crear la factura
Esta estructura describe los parámetros aceptados agrupados en 3 secciones:
Datos principales de la factura
Datos del adquiriente
Ítems del producto o servicio
Parámetros del Cuerpo (Body)
Parámetros Factura Mandatory
Este grupo de parámetros identifica los campos que incluye la factura en sí mismos y garantizan que sea
reconocida como legítima. Hay un número mínimo de campos obligatorios que se deben cumplir para
que la factura sea válida.
ID del rango de numeración. Se obtiene del endpoint de rangos. Para su validación, la obligación en la aguja del rédimo es máximo 100 dígitos sin decimales.
operation_type
string
RequeridoNullable
Tipo de la operación. Es obligatoria su inclusión, el campo no admite cadena vacía (""). Tablas de operaciones.
observation
string
OpcionalNullable
Observación libre de la factura. Máx. 250 caracteres.
Fecha de inicio del período de facturación. Formato YYYY-MM-DD.
billing_period_end
string
OpcionalNullable
Fecha de fin del período de facturación. Formato YYYY-MM-DD.
notes_due_date
string
Opcional
Notas sobre el vencimiento y forma de pago.
order_reference
string
OpcionalNullable
Referencia de la orden de compra asociada a la factura. Número de Romancillo Disponibles. Debe coincidir con el campo indicado en las tablas de referencia de la DIAN.
cash_rounding_amount
string
Opcional
Monto de ajuste de redondeo al total. Usar "0.00" si no aplica.
Parámetros Customer (Adquiriente)
Datos del adquiriente o cliente al que se emite la factura. Estos campos son validados contra
los registros de la DIAN para contribuyentes colombianos.
Cada ítem representa un producto o servicio facturado. Se debe incluir al menos un ítem por
factura. Los impuestos se definen por ítem según las tarifas vigentes.
Campo
Tipo
Estado
Descripción
code_reference
string
Requerido
Código de referencia interna del producto o servicio.
name
string
Requerido
Nombre o descripción del producto o servicio.
quantity
string
Requerido
Cantidad del ítem. Máximo 2 decimales. Ej: "1.00", "2.50".
price
string
Requerido
Precio unitario antes de impuestos. Máximo 2 decimales. Ej: "50000.00".
discount_rate
string
Opcional
Porcentaje de descuento sobre el precio. Ej: "10.00" para 10%. Usar "0.00" si no aplica.
Código del medio de pago. 10 = Efectivo, 42 = Consignación. Medios disponibles.
reference_code
string
Opcional
Referencia del pago (número de transacción, cheque, etc.).
amount
string
Requerido
Monto del pago. Debe coincidir con el total de la factura si es pago único.
Parámetros Prepayment Details (Anticipos)
Campo
Tipo
Estado
Descripción
reference_code
string
Opcional
Código de referencia del anticipo.
received_date
string
Opcional
Fecha de recepción del anticipo. Formato YYYY-MM-DD.
amount
string
Opcional
Valor del anticipo recibido.
note
string
Opcional
Texto libre con notas del anticipo.
Importante
Para que una factura sea válida ante la DIAN debe tener al menos un ítem y un método de pago.
El campo reference_code de la factura debe ser único en su sistema. Si envía uno ya usado, recibirá los datos de la factura existente.
Los montos deben ser enviados como string con exactamente 2 decimales: "10000.00".
ÍndiceAutenticaciónIntroducción a la autenticación
Introducción a la autenticación
La API de FactuColombia utiliza el estándar OAuth 2.0 para autenticar las solicitudes.
Antes de realizar cualquier llamada a los endpoints protegidos, debes obtener un access_token
que deberás incluir en el encabezado Authorization de cada solicitud.
access_token
Token de corta duración (1 hora) que se incluye en cada request para autenticar la sesión activa.
refresh_token
Token de larga duración para renovar el access_token sin necesidad de re-autenticarse con credenciales.
Flujo de autenticación
1. Solicita un token usando tus credenciales en el endpoint /oauth/token.
2. Incluye el access_token en el header Authorization: Bearer <access_token> de cada solicitud.
3. Cuando el token expire (1 hora), usa el refresh_token para obtener uno nuevo sin volver a ingresar credenciales.
AcceptStringapplication/json — Indica que la respuesta debe estar en formato JSON.
Parámetros del Cuerpo de Solicitud
El cuerpo de la solicitud debe enviarse como form-data e incluir los siguientes parámetros obligatorios:
Parámetros
CampoTipoDescripción
grant_typeStringRequiredTipo de autenticación. El valor debe ser password. El resto de datos se deben reemplazar por los enviados al solicitar las credenciales.
client_idStringRequiredIdentificador único del cliente. Proporcionado por el administrador de la API.
client_secretStringRequiredSecreto asociado al cliente. Mantener seguro, no exponer en código público.
usernameStringRequiredCorreo electrónico del usuario registrado en el sistema.
passwordStringRequiredContraseña del usuario asociada a la cuenta registrada.
Ejemplo de Solicitud
A continuación, se muestra un ejemplo de cómo enviar una solicitud al endpoint:
PHP — Laravel (Guzzle)
// Requiere: composer require guzzlehttp/guzzleuseIlluminate\Support\Facades\Http;
classAuthControllerextendsController
{
public functiongetToken()
{
// Parámetros necesarios para la solicitud$response = Http::asForm()->post('https://api-sandbox.factucolombia.com.co/oauth/token', [
'grant_type' => 'password',
'client_id' => 'tu client id',
'client_secret' => 'tu client secret',
'username' => 'tu username',
'password' => 'tu password',
]);
// Verificamos si la respuesta es exitosaif ($response->successful()) {
// Acceder a los datos del token$data = $response->json();
$accessToken = $data['access_token'];
$refreshToken = $data['refresh_token'];
// Mostrar los tokens (o devolverlos en la respuesta de la API)returnresponse()->json([
'access_token' => $accessToken,
'refresh_token' => $refreshToken,
]);
} else {
// En caso de error, devolver el mensaje de errorreturnresponse()->json([
'error' => 'No se pudo obtener el token',
'message' => $response->body(),
], 400);
}
}
}
Este endpoint permite renovar el token de acceso sin necesidad de re-autenticarse con credenciales de usuario,
usando el refresh_token obtenido en la autenticación inicial.
Nota
El refresh_token tiene una duración mayor al access_token.
Úsalo para renovar la sesión sin interrumpir la experiencia del usuario.
Recuerde: el access_token caduca cada hora.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Content-Type—application/jsonRequerido
Accept—application/jsonOpcional
Estructura para crear la nota crédito
Para crear una nota crédito, el cuerpo debe organizarse en 3 secciones:
1Datos generales de la nota crédito
2Datos del cliente (customer)
3Ítems del producto o servicio (items)
Parámetros del Cuerpo (Body)
El cuerpo de la solicitud debe enviarse en formato JSON e incluir los siguientes parámetros:
Parámetros generales de la nota crédito
CampoTipoDescripción
reference_codeStringRequiredCódigo único de referencia de la nota crédito. No puede existir previamente en el sistema, de lo contrario se retornarán los datos de la nota crédito existente.
credit_note_dateStringRequiredNullableEs el id al que va a generar la nota crédito. Debe ser enviado únicamente cuando el identification_code sea igual a 2 o 4. Se usa la CUDE de la referencia.
billing_reference_codeStringRequiredCódigo de referencia de la factura asociada a la nota crédito. No puede tener más de 250 caracteres.
billing_reference_uuidStringRequiredAplica cuando es obligatorio vincular el pago a una factura. Debe agregar el billing_reference_uuid en el payment para vincular el pago a la factura. Requerido cuando el identification_code es 2 o 4.
payment_method_codeStringRequiredCódigo que especifica el medio de pago de la nota crédito (p. ej.: 1=de contado, 2=a crédito). No puede estar vacío ni contener espacios. Tabla de medios de pago disponibles.
service_provider_addressStringNombre del archivo. Requerido, cuando el tipo de referencia corresponde a ruta (XML, URL, etc.). Si no se especifica, el proveedor tomará el valor predeterminado. Los campos del nombre son obligatorios.
headStringInicio del encabezado del suministrador.
tailStringTérmino del encabezado del suministrador.
head_noteStringCabecera del encabezado del suministrador.
foot_noteStringCódigo de la factura que se va a utilizar en el encabezamiento. Documentos disponibles.
billing_period_start_dateStringFecha de inicio del período de facturación. Formato: YYYY-MM-DD.
billing_period_start_timeStringHora de inicio del período de facturación. Formato: HH:mm:ss.
billing_period_end_dateStringFecha de fin del período de facturación. Formato: YYYY-MM-DD.
billing_period_end_timeStringHora de fin del período de facturación. Formato: HH:mm:ss.
customerObjectEn este objeto se consolida la información del cliente de la nota crédito. Si no se envía los datos del cliente de la nota crédito, se utilizará el cliente de la factura. Ver campos del customer a continuación.
discount_rateNumericPorcentaje del descuento del producto o servicio (entre 0 y 100).
is_excludedIntegerIndica si el ítem está excluido de IVA. 0 = gravado, 1 = excluido.
item_typeStringTipo del producto actualizado al producto o servicio. Validos los tipos disponibles.
descriptionStringDescripción del producto o servicio. Configure las operaciones de la nota crédito.
notesStringFecha de la configuración de la información del ítem. Debe ser la referencia en Formato ISO 8601.
billing_start_dateStringFecha de inicio de la facturación del ítem. Formato: YYYY-MM-DD. Obligatoria para configuraciones con período.
billing_end_dateStringFecha de fin de la facturación del ítem. Formato: YYYY-MM-DD. Obligatoria para configuraciones con período.
item_identification_codeStringCódigo que corresponde a los productos e impuestos o beneficios que aplican al ítem. Código de la identificación disponible.
allowance_chargesArrayEs la lista de los descuentos adicionales aplicados al ítem.
withholding_taxesArrayRetenciones aplicadas al ítem (retefuente, reteIVA, reteICA, etc.).
rateNumericRequiredPorcentaje de la tasa del impuesto. Ej: "19.00" para IVA del 19%.
amountNumericValor del impuesto. Si no se envía, se calcula automáticamente.
unit_amountNumericValor unitario del impuesto por ítem.
per_unit_amountNumericValor del impuesto por unidad del ítem.
base_unit_measureStringUnidad de medida base para el cálculo del impuesto.
brand_nameStringNombre de la marca del producto.
class_indicatedStringClase indicada del impuesto.
Descuentos y cargos — items[].allowance_charges[]
CampoTipoDescripción
charge_indicatorIntegerRequired0 = Descuento, 1 = Cargo al ítem.
allowance_charge_reasonStringMotivo del descuento o cargo aplicado.
amountNumericRequiredValor del descuento o cargo.
base_amountNumericBase sobre la cual se aplica el descuento o cargo.
Descuentos globales — allowance_charges[]
CampoTipoDescripción
charge_indicatorIntegerNúmero de notas de la nota crédito correspondiente. Esto viene de un 0 al pago y +1.
allowance_charge_reasonStringDescripción del descuento global aplicado a la nota crédito.
amountNumericValor del descuento o cargo global.
base_amountNumericBase sobre la cual se aplica el descuento global.
Redondeo — cash_rounding_amount
CampoTipoDescripción
cash_rounding_amountNumericMonto de redondeo de la nota crédito correspondiente. Esto está en los medios de pago, con un máximo de 2 decimales.
Nota
Para los casos de uso de notas crédito que no aplican, se puede omitir los campos de impuestos y descuentos del ítem. Sin embargo, es importante que los campos de la nota crédito sí se envíen en la solicitud a la misma.
Tener en cuenta
En el caso de que los valores de la nota crédito sean correctos, se puede omitir los campos de la nota crédito. Sin embargo, es importante que los ítems de la nota crédito sí se envíen en la misma solicitud.
ÍndiceInformación de adquirientesObtener datos de adquirientes
Obtener datos de adquirientes
GET/v2/dian/acquirer
Este endpoint permite consultar el nombre o razón social y la
dirección de correo electrónico asociada a un adquiriente, utilizando
como criterios de búsqueda el tipo y número de documento.
La DIAN ha implementado un nuevo servicio de consulta para completar la información de adquirientes con el
objetivo de facilitar y agilizar la generación de facturas electrónicas.
Fuente oficial
Consulta directa al servicio de la DIAN en tiempo real.
Búsqueda por documento
Tipo y número de documento como criterios.
Retorna nombre y email
Datos listos para llenar la factura automáticamente.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Accept—application/jsonOpcional
Variables de Ruta — Path Variables
Estos parámetros se envían como query strings en la URL de la solicitud:
ParámetroTipoDescripción
identification_document_id
Required
string
Código que corresponde al tipo de identificación del adquiriente. Consulte la tabla de
códigos de tipos de documentos
para conocer los valores disponibles. Ej: 1 = Registro civil, 12 = NIT, 13 = Cédula de ciudadanía
identification_number
Required
string
Número de documento del adquiriente a consultar. Ej: 1199991
Pruebas en Sandbox
En la sección de Datos de prueba encontrarás los valores proporcionados por la DIAN para realizar consultas en el entorno sandbox.
Tablas de referencia para la implementación de la Factura Electrónica en Colombia.
Estos códigos son utilizados en los campos de las facturas, notas crédito y documentos soporte.
Códigos de tipos de documentos para la factura
Código
Descripción
01
Factura de venta
02
Factura de exportación
03
Documento soporte en adquisiciones efectuadas a no obligados a facturar
04
Nota de ajuste al documento soporte
Código de tipos de operación
Código
Descripción
09
Estándar
10
Importación
20
Exportación
30
Nota crédito que referencia una o varias facturas electrónicas de venta
32
Nota crédito sin referencia a facturas
22
Nota crédito para factura electrónica de exportación
Código de tipos de conexión
Código
Descripción
1
Sandbox (entorno de pruebas)
2
Producción — habilitado para hacer uso de los servicios de la API
3
Producción — en proceso de habilitación
4
Producción — no habilitado
Código de tipos de operación (notas crédito)
Código
Descripción
1
Devolución parcial de los bienes y/o no aceptación parcial del servicio
2
Anulación de la factura electrónica
3
Rebaja o descuento parcial
4
Ajuste de precio
Código de estándar de identificación del producto
Código
Descripción
001
Estándar de adopción del contribuyente
010
Nombre estándar UNSPSC
999
Estándar sin definir
Código de tipos de documentos de identidad
Código
Descripción
11
Registro civil
12
Tarjeta de identidad
13
Cédula de ciudadanía
21
Tarjeta de extranjería
22
Cédula de extranjería
31
NIT
41
Pasaporte
42
Documento de identificación extranjero
43
Sin identificación del exterior o para uso definido por la DIAN
44
Documento de identificación extranjero persona jurídica
46
NUIP
50
NIT de otro país
Código de tributos clientes
Código
Descripción
ZZ
No aplica
01
IVA e INC
Código de impuestos
Código
Descripción
01
Impuesto sobre las ventas IVA
02
Impuesto al consumo (INC) — bebidas azucaradas
03
Impuesto de industria y comercio ICA
04
Impuesto al consumo INC
05
Impuesto al consumo de bolsas plásticas
06
Retención en la fuente
07
Retención IVA
08
Retención ICA
20
Impuesto Nacional al Consumo a la gasolina
21
Impuesto Nacional al Consumo al ACPM
22
Impuesto al consumo de carbono
ZY
No causado (Factura de Exportación)
Código de métodos de pago
Código
Descripción
10
Efectivo
20
Cheque
31
Débito ACH
42
Consignación bancaria
47
Tarjeta débito
48
Tarjeta crédito
49
Pago por transferencia — crédito
ZZZ
Otro
1
Instrumento no definido
Código de Formas de pago
Código
Descripción
1
Contado
2
Crédito
Responsabilidades fiscales
Código
Descripción
O-13
Gran contribuyente
O-15
Autorretenedor
O-23
Agente de retención en el impuesto sobre las ventas
O-47
Régimen simple de tributación SIMPLE
R-99-PN
No aplica — Otros
ZZ
No responsable
Sector Salud — Planes de cobertura
Código
Descripción
01
Contributivo EPS - Plan Obligatorio de Salud (POS)
El endpoint Rangos de Numeración permite obtener los rangos de numeración disponibles en la API.
Útil para obtener información precisa sobre los rangos de numeración de documentos específicos,
incluyendo su prefijo, rango de numeración, resolución, fecha de inicio y fin, entre otros.
Este endpoint permite ver un rango de numeración en específico. Es útil para obtener información
detallada sobre un rango de numeración en particular, incluyendo su prefijo, rango de numeración,
resolución, fecha de inicio y fin, entre otros.
Nota
Es necesario el envío del token de acceso <access_token>.
Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Accept—application/json
Respuesta del Endpoint
CampoDescripción
idID del rango de numeración
documentNúmero del documento
document_nameNombre del documento
prefixPrefijo del rango de numeración
fromNúmero de inicio del rango de numeración
toNúmero de final del rango de numeración
currentSiguiente número dentro del rango de numeración
resolution_numberNúmero de resolución
start_dateFecha en la que se expidió el rango de numeración
end_dateFecha de vencimiento del rango de numeración
technical_keyClave técnica
is_expiredEl valor es 1 cuando el rango está vencido y 0 cuando está vigente
is_activeEl valor es 1 cuando el rango está activo y 0 cuando está inactivo
Variables de Ruta, Path Variables
ParámetroTipoDescripción
numbering_range_id
Required
stringID del rango de numeración. Se recomienda guardar el ID del rango de numeración para no hacer múltiples llamadas al endpoint al momento de realizar los documentos electrónicos.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Content-Type—application/json — Indica que los datos se envían en formato JSON.
Authorization—Bearer token_de_acceso — Token de autenticación necesario. Requerido
Accept—application/json — Indica que la respuesta debe estar en formato JSON.
Parámetros
ParámetroTipoDescripción
track_id
Required
stringCUFE de la factura electrónica a cargar en el sistema de recepción.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Content-Type—application/json — Indica que los datos se envían en formato JSON.
Authorization—Bearer token_de_acceso — Token de autenticación. Cómo generar token.
Accept—application/json — Indica que la respuesta debe estar en formato JSON.
Nota—Reemplaza token_de_acceso con el token proporcionado tras autenticarte.
Filtros de Búsqueda
Parámetros
FiltroDescripción
filter[id]ID de la factura electrónica en el sistema de recepción.
filter[number]Número de la factura electrónica.
filter[issue_date]Fecha de emisión de la factura electrónica. Formato: YYYY-MM-DD.
filter[cufe]CUFE de la factura electrónica.
filter[company_nit]NIT de la empresa o persona que te emitió la factura electrónica.
filter[company_name]Nombre de la empresa o persona que te emitió la factura electrónica.
filter[completed_events]Usa 1 para listar las facturas que no tienen eventos pendientes por emitir y 0 para mostrar las facturas que tienen eventos pendientes por emitir.
En este endpoint podrás emitir los siguientes eventos de la factura electrónica.
Tipos de eventos
1
Acuse de recibo de Factura Electrónica de Venta
Este evento se emite para confirmar que has recibido la factura electrónica, ya sea en físico o a través de un medio electrónico.
2
Recibo del bien o prestación del servicio
Este evento se emite cuando has recibido los bienes (productos) o servicios que adquiriste y que están especificados en la factura.
Nota
Para emitir este evento, es obligatorio haber generado previamente el Acuse de recibo de Factura Electrónica de Venta.
3
Reclamo de la Factura Electrónica de Venta
Este evento se emite en caso de que la factura presente alguna inconsistencia, como la entrega parcial o total de los productos, o si el servicio no fue prestado.
Nota
Para emitir este evento, es obligatorio haber generado previamente el Recibo del bien o prestación del servicio.
4
Aceptación expresa
Este evento se emite para indicar que estás de acuerdo con la factura recibida, y que los productos han sido entregados o el servicio ha sido prestado satisfactoriamente.
Importante
Una vez que emitas este evento, ya no será posible generar otros eventos, notas crédito ni modificar el estado de la factura como Título Valor en el sistema RADIAN.
5
Aceptación tácita
Este evento no puede ser emitido por ti. Será generado automáticamente por la persona o empresa (comprador/emisor) de la factura si, pasados tres (3) días hábiles desde la emisión del evento
Recibo del bien o prestación del servicio, no has emitido un
Reclamo de la Factura Electrónica de Venta ni una Aceptación expresa.
Importante
Una vez que se genere este evento, ya no será posible emitir otros eventos, notas crédito ni modificar el estado de la factura como Título Valor en el sistema RADIAN.
Es necesario el envío del token de acceso <access_token>.
Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Content-Type—application/json
Authorization—Bearer token_de_accesoRequerido
Accept—application/json
Tabla de Códigos de Eventos
Código
Nombre del evento
030
Acuse de recibo de Factura Electrónica de Venta
031
Reclamo de la Factura Electrónica de Venta
032
Recibo del bien y/o prestación del servicio
033
Aceptación expresa
034
Aceptación tácita
Descripción del body
Se envían los datos de la persona del evento. Los datos de la persona pueden cambiar dependiendo del evento:
Acuse de recibo de Factura Electrónica de Venta: debes agregar los datos de la persona que recibió la factura.
Reclamo de la Factura Electrónica de Venta: debes agregar los datos de la persona que hizo el reclamo.
Recibo del bien y/o prestación del servicio: debes agregar los datos de la persona que recibió los bienes (productos) o servicio.
Aceptación expresa: debes agregar los datos de la persona que aceptó expresamente la factura y los bienes (productos) y servicios.
Parámetros del cuerpo (Body)
Parámetros
CampoTipoDescripción
claim_concept_code
optional
StringRequerido si se envía el evento de Reclamo de la Factura Electrónica de Venta. Nota: Para saber los códigos de los conceptos, consulta la tabla Códigos conceptos de reclamo.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Content-Type—application/json
Accept—application/json
Tener en cuenta
Si envía un reference_code ya procesado, recibirá los datos correspondientes a la factura existente.
Si el endpoint responde con 400 Conflict, debe Eliminar la factura usando la referencia y proceder con la creación de una nueva factura. Puede guiarse por el campo is_validated de la factura: true validada, false sin validar.
Esta sección describe los campos que podría contener la factura con operación de mandatos (operation_type: 11). Permite incluir información del mandatario por ítem mediante el campo mandate.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Content-Type—application/json
Accept—application/json
Tener en cuenta
Si envía un reference_code ya procesado, recibirá los datos correspondientes a la factura existente.
Si el endpoint responde con 400 Conflict, debe Eliminar la factura usando la referencia y proceder con la creación de una nueva factura. Puede guiarse por el campo is_validated de la factura: true validada, false sin validar.
Esta sección describe los campos que podría contener la factura con operación de transporte (operation_type: 12). Permite incluir propiedades adicionales por ítem mediante el campo additional_properties.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Content-Type—application/json
Accept—application/json
Tener en cuenta
Si envía un reference_code ya procesado, recibirá los datos correspondientes a la factura existente.
Si el endpoint responde con 400 Conflict, debe Eliminar la factura usando la referencia y proceder con la creación de una nueva factura. Puede guiarse por el campo is_validated de la factura: true validada, false sin validar.
Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint.
Para ver cómo generar el token, consulte Cómo generar un token de acceso. Recuerde: El token de acceso caduca cada hora.
Encabezados de la Solicitud
Encabezado
Valor
Descripción
Authorization—Bearer <access_token>Requerido
Content-Type—application/json
Accept—application/json
Tener en cuenta
Si envía un reference_code ya procesado, recibirá los datos correspondientes a la factura existente.
Si el endpoint responde con 400 Conflict, debe Eliminar la factura usando la referencia y proceder con la creación de una nueva factura. Puede guiarse por el campo is_validated de la factura: true validada, false sin validar.
