Guía de habilitación con software propio
GuíaCómo pasar de cero a emitir facturas electrónicas de venta con Gravamenex: qué haces tú ante la DIAN, qué hace Gravamenex y en qué orden. Gravamenex es software de facturación; no somos proveedor tecnológico autorizado por la DIAN, por eso cada emisor se habilita con software propio.
Gravamenex es un software de facturación electrónica: construye el XML UBL 2.1, firma con el certificado del emisor, transmite a la DIAN y entrega XML, PDF y ZIP por API, portal y correo.
Gravamenex no es proveedor tecnológico autorizado (PTA) por la DIAN. Por eso no te habilitamos bajo un código nuestro: tú te habilitas ante la DIAN como facturador electrónico con software propio, y Gravamenex usa los datos de tu habilitación (identificador de software, PIN, certificado y numeración) para emitir a nombre de tu empresa.
La habilitación, la numeración y cada documento emitido siguen siendo responsabilidad del emisor, la empresa obligada a facturar. Esta guía no reemplaza la asesoría de tu contador o abogado tributario y no es una garantía de aceptación por la DIAN.
| Etapa | Tú (emisor) | Gravamenex | DIAN |
|---|---|---|---|
| Registro como facturador | Registras a la empresa con un RUT actualizado | — | Habilita la calidad de facturador electrónico |
| Software y set de pruebas | Registras tu software propio y anotas Software ID, PIN y Test Set ID | Guarda esos datos en un gestor de secretos; la API no devuelve el PIN | Asigna el identificador de software y el set de pruebas |
| Certificado de firma | Adquieres un certificado de firma digital a nombre de tu empresa y lo cargas | Lo almacena cifrado y firma cada documento | Valida la firma de cada documento |
| Numeración | Solicitas el rango de numeración en MUISCA | Sincroniza el rango y numera cada factura sin saltos ni repetidos | Autoriza el rango y su vigencia |
| Habilitación | Emites el set de pruebas desde Gravamenex en ambiente de habilitación | Emite, transmite y reporta el resultado de cada documento | Valida el set de pruebas |
| Producción | Solicitas el paso a producción y activas el ambiente en Gravamenex | Activa producción solo si el preflight del core lo confirma | Autoriza la emisión productiva |
| Emisión diaria | Emites por API o desde el portal | XML, firma, envío, artefactos y entrega | Responde con la validación previa |
Ingresa al portal de la DIAN (www.dian.gov.co) con el usuario autorizado de la empresa y registra a la empresa como facturador electrónico.
Elige la modalidad de software propio, no la de proveedor tecnológico. Registra tu software con un nombre y un PIN. La DIAN te asigna el identificador de software (Software ID, un UUID) y el set de pruebas (Test Set ID) para la etapa de habilitación.
Guarda Software ID, PIN y Test Set ID: los usarás en el Paso 5. El PIN solo se escribe en Gravamenex una vez; después no se vuelve a mostrar.
Adquiere un certificado de firma digital a nombre de tu empresa, emitido por una entidad de certificación acreditada ante el ONAC, en formato PKCS#12 (.p12 o .pfx) con su contraseña.
El certificado debe permitir la firma de documentos (usos digitalSignature y contentCommitment). Vigencia vencida o certificado de otra empresa hacen fallar el preflight.
Para habilitación y producción carga el certificado de tu empresa. El sandbox usa material de prueba y no tiene valor fiscal.
En el portal MUISCA de la DIAN solicita la autorización de numeración de facturación: define el prefijo y el rango que necesitas. Firma la solicitud y descarga la resolución.
Anota el número de resolución, el prefijo, el rango y su vigencia. La resolución puede tardar en reflejarse en los servicios de la DIAN; si la sincronización no la encuentra, espera y reintenta.
Las notas crédito y débito no usan la resolución de la factura: Gravamenex las numera con series internas que defines en la configuración fiscal. Documento soporte y documento equivalente tienen rangos propios que se registran por separado.
Regístrate en Gravamenex con tu correo (código de un solo uso), registra a la empresa y recibe tu llave de API de sandbox.
El sandbox es un simulador de desarrollo para integrar y probar: no es la habilitación DIAN, no emite documentos con valor fiscal y no cuenta como set de pruebas.
En Configuración fiscal carga el RUT en PDF (se verifica contra el NIT de la empresa), elige software propio y escribe Software ID, PIN y Test Set ID, carga el certificado y su contraseña, sincroniza el rango de facturas de venta y define las series de notas crédito y débito.
Corre el preflight. El preflight lo evalúa el core de Gravamenex, no solo el portal: si el core no responde o algún requisito falla, el resultado es no listo. Un preflight en verde confirma que la configuración está completa; no equivale a la habilitación ni transmite una factura.
Con la conexión en ambiente de habilitación, emite desde Gravamenex los documentos que pide el set de pruebas de la DIAN y revisa el estado de cada uno: queued, accepted, rejected o manual_review.
Un documento aceptado en habilitación demuestra que tu configuración funciona; no es una factura de producción. Si la DIAN rechaza un documento, el detalle trae las reglas incumplidas (FAD/FAJ): corrige y reenvía conservando el mismo consecutivo.
Cuando la DIAN confirme tu habilitación, solicita el paso a producción, registra en Gravamenex el rango y la clave técnica de producción y cambia el ambiente de la conexión.
Activa producción desde el portal. La activación solo procede si el core de Gravamenex confirma el preflight de producción y que la conexión está lista para emitir. Pagar un plan no activa la emisión fiscal por sí solo.
Emite con POST /v1/invoices o desde el portal. Cada factura recibe CUFE y código QR, un XML UBL 2.1 firmado, el PDF de la representación gráfica y un ZIP con ambos.
El estado de la entrega por correo es el que reporta el servicio de correo: «aceptado para envío» no es «entregado». Si un correo rebota puedes reenviarlo sin reemitir la factura.
- ¿Gravamenex es proveedor tecnológico autorizado por la DIAN? No. Es software de facturación; cada emisor se habilita con su propio software ante la DIAN.
- ¿Necesito mi propio Software ID y PIN? Sí: se obtienen al registrar tu software propio en la DIAN (Paso 1).
- ¿Puedo facturar con la fecha de ayer? No. La fecha de la factura es la fecha de generación y firma, día calendario de America/Bogota (Anexo Técnico FEV 1.9, regla FAD09e).
- ¿Qué pasa si no hay conexión con la DIAN? El documento queda en cola y se reintenta sin duplicar el CUFE. El flujo completo de contingencia todavía no está soportado.
- ¿Dónde se guardan mi certificado y mi PIN? En un gestor de secretos; la API nunca los devuelve. Cambiarlos no reinicia tu numeración ni tus documentos.
- ¿Una nota crédito corrige un documento rechazado? No. Las notas ajustan una factura válida; un rechazo se corrige y se reenvía.
- ¿Qué documentos puedo emitir? Consulta el estado de cada familia (factura, notas, documento soporte, documento equivalente POS y nómina) en las páginas de producto y en el estado del servicio.
- Resolución DIAN 165 de 2023 — https://normograma.dian.gov.co/dian/compilacion/docs/resolucion_dian_0165_2023.htm
- Anexo Técnico de la Factura Electrónica de Venta, versión 1.9 — https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo-Tecnico-Factura-Electronica-de-Venta-vr-1-9.pdf
- Concepto DIAN 1532 de 2024 (fecha de la factura) — https://normograma.dian.gov.co/dian/compilacion/docs/oficio_dian_1532_2024.htm
- Resolución DIAN 202 de 2025 (datos mínimos del adquirente) — https://normograma.dian.gov.co/dian/compilacion/docs/resolucion_dian_0202_2025.htm
Los nombres de menús y los pasos del portal de la DIAN cambian con el tiempo: la fuente vigente es dian.gov.co y el Anexo Técnico. Confirma con tu asesor tributario que la modalidad de software propio es adecuada para tu empresa.
Si algo de esta guía no coincide con lo que ves, escríbenos desde Soporte.