Glosario

Facturación electrónica

DIAN

La Dirección de Impuestos y Aduanas Nacionales: la entidad de Colombia que recibe y valida las facturas electrónicas. Cada factura se le envía antes o al mismo tiempo que al comprador.

Factura electrónica

Una factura en formato XML, firmada digitalmente y validada por la DIAN. El PDF es solo una representación para leerla; la factura "de verdad" es el XML.

Habilitación

El ambiente de pruebas de la DIAN. Allí se envían facturas para comprobar que el sistema funciona, sin validez fiscal. El sandbox de Trifaco envía todas sus facturas a este ambiente.

Producción

El ambiente real de la DIAN: las facturas tienen validez fiscal. En Trifaco, producción todavía está deshabilitada.

CUFE

Código Único de Factura Electrónica. Es un código largo (96 caracteres) que identifica cada factura ante la DIAN y que aparece en el PDF y en el código QR. En la API está en fiscal_identity.unique_code.

CUDE

Código Único de Documento Electrónico. Es el equivalente del CUFE para las notas crédito y débito.

NIT

Número de Identificación Tributaria. Identifica a empresas y personas ante la DIAN.

DV (dígito de verificación)

El número que va después del guion en un NIT (por ejemplo, el 7 en 900123456-7). En la API el NIT va sin DV en number y el DV va aparte en check_digit.

Emisor

Quien expide la factura, es decir, quien vende. En el sandbox todas las cuentas usan un emisor de pruebas compartido, así que no necesitas tu propio certificado.

Adquiriente o comprador

Quien recibe la factura, es decir, quien compra. En la API es el objeto buyer.

Certificado digital

Un archivo que emite una entidad certificadora (como Andes o GSE) y que sirve para firmar las facturas. Garantiza que la factura la expidió quien dice haberla expedido. En el sandbox no necesitas uno.

Resolución de facturación

La autorización que la DIAN le da a una empresa para numerar sus facturas. Indica el prefijo, el rango de números y las fechas de vigencia.

Rango de numeración

Los números que la empresa puede usar en sus facturas, por ejemplo del 990000000 al 995000000. Trifaco asigna el siguiente número disponible a cada factura, en orden y sin repetir. En la API lo indicas con numbering_range_id.

Prefijo

Las letras que van antes del número de la factura, por ejemplo SETP en SETP990001234. En habilitación la DIAN usa el prefijo SETP.

Nota crédito

Un documento que disminuye o anula el valor de una factura ya emitida: por ejemplo, una devolución o un descuento posterior. Siempre hace referencia a la factura original.

Nota débito

Un documento que aumenta el valor de una factura ya emitida: por ejemplo, intereses o un cobro que faltó. También hace referencia a la factura original.

IVA

Impuesto al Valor Agregado. En la API es el tributo con código 01. Las tarifas admitidas hoy son 0 %, 5 % y 19 %.

Retención

Un valor que el comprador descuenta del pago para entregarlo a la DIAN en nombre del vendedor (por ejemplo, retención en la fuente). En la API va en withholdings.

La API

API key

La clave secreta que identifica a tu cuenta en cada petición. Va en el encabezado X-API-Key. Trátala como una contraseña.

Sandbox

El ambiente de pruebas de Trifaco. Te registras solo, obtienes tu API key y envías facturas a la DIAN en habilitación, sin costo y sin certificado.

Idempotencia

La garantía de que repetir una petición no crea un documento duplicado. Envías un encabezado Idempotency-Key con un texto único: si la conexión se corta y reintentas con la misma clave, recibes la misma factura en lugar de una nueva.

Referencia externa

El identificador de la factura en tu sistema (por ejemplo, el número de pedido). En la API es external_reference. Te sirve para encontrar la factura sin guardar nuestros IDs.

Prevalidar

Revisar una factura sin emitirla, para saber si tiene errores antes de enviarla. Se hace con POST /v1/invoice-validations.

Webhook

Un aviso que Trifaco envía a una dirección de tu sistema cuando pasa algo, por ejemplo cuando la DIAN valida una factura. Así no tienes que consultar a cada rato. Detalle en Webhooks.

Artefacto

Un archivo asociado a una factura: el PDF, el XML firmado o la respuesta de la DIAN. Se descargan con GET /v1/artifacts/{id}/content.

Catálogo

La lista de códigos válidos para un campo, por ejemplo los tipos de identificación o las unidades de medida. Se consultan con GET /v1/catalogs/{catalog}.