Emitir documentos electrónicos

Toda la emisión general (facturas, notas crédito y notas débito) se realiza con el método SendBillSync de la DIAN, que es síncrono: el resultado (CUFE/CUDE, estado, errores) llega en la misma llamada HTTP, sin polling. Solo cambia la URL según el ambiente del tenant.

Tipos de documento

Documento	Código (Catálogo 1)	Endpoint
Factura electrónica de venta	01	POST /tenants/:nit/invoices
Nota crédito electrónica	91	POST /tenants/:nit/credit-notes
Nota débito electrónica	92	POST /tenants/:nit/debit-notes

Todos requieren un token con permiso sobre el tenant (admin, superadmin, o el tenant dueño del NIT). Ver Autenticación.

Referenciar la factura original en NC y ND

Las notas crédito y débito deben referenciar la factura original mediante el bloque facturaReferencia. Hay dos formas:

• Por CUFE directo — enviar cufe de la factura original.
• Por lookup automático — enviar prefijo + numero; la API busca el CUFE de la factura aceptada en su base de datos.

{
  "facturaReferencia": {
    "numero": "SETP990000001",
    "prefijo": "SETP",
    "fecha": "2026-06-01"
  }
}

Si la factura referenciada no existe para el tenant, la API responde 400 Bad Request con un mensaje claro ("No se encontró factura aceptada ... Verifica el número o provee el CUFE en facturaReferencia.cufe.").

:::info Elementos XML propios de cada tipo

• Nota crédito → raíz <CreditNote>, cbc:CreditNoteTypeCode = 91, cac:CreditNoteLine, cbc:CreditedQuantity.
• Nota débito → raíz <DebitNote>, cbc:DebitNoteTypeCode = 92, cac:DebitNoteLine, cbc:DebitedQuantity.

Usar elementos de Invoice en una NC/ND produce el error ZB01. :::

Campos del response

Campo	Descripción
cufe / cude	Código único del documento (SHA-384, 96 caracteres). cufe en facturas; cude en NC/ND.
estado	aceptada o rechazada.
errores	Lista de errores que bloquean el documento (vacía si fue aceptado).
notificaciones	Advertencias informativas cuando el documento fue aceptado.
qrUrl	URL del catálogo DIAN con el QR (contiene el CUFE/CUDE).
fechaValidacion	Fecha/hora de validación reportada por la DIAN.

Ejemplo de respuesta aceptada:

{
  "cufe": "a1b2c3...",
  "estado": "aceptada",
  "fechaValidacion": "2026-06-17T10:30:00-05:00",
  "errores": [],
  "qrUrl": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=...",
  "notificaciones": [{ "codigo": "FAS01", "descripcion": "..." }]
}

"Aprobado" vs "Aprobado con notificación"

• Aprobado — el documento fue aceptado sin observaciones (estado: "aceptada", notificaciones vacío o ausente).
• Aprobado con notificación — el documento fue aceptado pero con advertencias informativas. No es un rechazo. Las notificaciones llegan en las LineResponse cuando el documento fue aceptado y se exponen en notificaciones[].

La regla de parseo del estado es: isValid = (ResponseCode === '00' || ResponseCode === '02'). Ver Errores DIAN frecuentes para el detalle de ResponseCode.

Ambiente habilitación: sin validez fiscal

Mientras el tenant esté en ambiente habilitacion, los documentos emitidos con SendBillSync son válidos estructuralmente y aparecen en el catálogo de habilitación (catalogo-vpfe-hab.dian.gov.co), pero no tienen validez fiscal. Solo los documentos emitidos en ambiente produccion (tras go-production) tienen valor legal.

	Habilitación	Producción
WS URL	vpfe-hab.dian.gov.co	vpfe.dian.gov.co
Método	SendBillSync	SendBillSync
Numeración	SETP990000001…	Resolución real autorizada
Validez fiscal	No	Sí