Prerrequisitos por tenant
Cada empresa (tenant) debe reunir lo siguiente antes de poder operar con la API. Estos elementos son propios de cada NIT y no se comparten entre tenants.
1. Certificado digital PKCS#12
Un certificado de firma digital .p12 (PKCS#12) emitido por una entidad de
certificación acreditada por la ONAC, por ejemplo:
- GSE (Gestión de Seguridad Electrónica)
- Certicámara
- Olimpia IT
El certificado se sube a la API (no se coloca en el repositorio ni en disco): se cifra con AES-256 y se almacena como BLOB en la base de datos, descifrándose solo en memoria al momento de firmar.
:::tip Desarrollo local
Para pruebas locales del flujo de firma existe un certificado self-signed generado con
OpenSSL (certs/test/). Nunca se envía a la DIAN; solo sirve para validar que el
código de firma XAdES funciona.
:::
2. Registro en el portal DIAN
La empresa debe registrarse en el portal de habilitación de la DIAN seleccionando el modo "Software Propio". De ese registro se obtienen los siguientes valores, que luego se cargan en la API:
| Valor | Descripción | Dónde se obtiene |
|---|---|---|
softwareId | Identificador del software propio | Panel de software propio |
softwarePin | PIN del software | Panel de software propio |
testSetId | Identificador del set de pruebas (solo habilitación) | Sección Set de Pruebas |
contributorId | Identificador interno del facturador | URL del set de pruebas (?contributorId=...) |
claveTecnica | Clave técnica de la resolución de facturación | Resolución de numeración DIAN |
:::info SoftwareSecurityCode
El SoftwareSecurityCode que exige la DIAN se calcula como
SHA384(softwareId + softwarePin + numero). Por eso el softwareId y el softwarePin
deben corresponder exactamente a los asignados por la DIAN al software propio.
:::
3. Resolución de numeración de habilitación
Durante la habilitación, los documentos del set de pruebas usan el prefijo SETP y un
rango de numeración técnico asignado por la DIAN (típicamente SETP990000001 en adelante).
Esta resolución se registra en la API con ambiente: "habilitacion".
4. Resolución de numeración de producción
Una vez aprobada la habilitación, la DIAN autoriza una resolución de numeración real
para producción: un prefijo propio (p. ej. FV), un rango autorizado y una vigencia.
Esta resolución se registra con ambiente: "produccion" y la API lleva el consecutivo
automáticamente.
Los números SETP* son exclusivos del set de pruebas/habilitación. En producción se debe
usar siempre la numeración de la resolución real autorizada por la DIAN.
Siguiente paso
Con estos elementos listos, sigue el flujo de Alta de un nuevo tenant paso a paso →.