Set de pruebas de la DIAN
Esta guía lleva un facturador desde cero hasta pasar el set de pruebas en el ambiente de habilitación (el ambiente de pruebas de la DIAN).
Antes de empezar (fuera de la API)
Sección titulada «Antes de empezar (fuera de la API)»- Registro en el portal de habilitación de la DIAN (por cada facturador en el modelo B): modo de operación Software propio. El portal entrega SoftwareID, PIN y TestSetId. Cada modo (facturación, documento soporte, nómina, POS) se habilita por separado y tiene su propio SoftwareID/PIN/TestSetId.
- Certificado de firma a nombre del facturador (Camerfirma u otra ECD acreditada por ONAC). La DIAN valida la firma con la cadena de confianza: un certificado autofirmado sirve para pruebas locales pero no pasa la validación de la DIAN.
- Mandato y autorización de custodia firmados por el facturador (Ley 527 de 1999).
Pasos en la API
Sección titulada «Pasos en la API»Todas las rutas usan Authorization: Bearer <api key> y X-Tenant-Id: <NIT> (o una llave
restringida al facturador).
1. Registrar el facturador
Sección titulada «1. Registrar el facturador»POST /v1/tenants con NIT, DV, razón social, responsabilidades fiscales, dirección (DIVIPOLA) y correo.
El DV se valida con el algoritmo módulo 11 de la DIAN. Si envía sus actividades económicas del RUT
(industryCodes, códigos CIIU de 4 dígitos, p. ej. ["6201"]), sus documentos las informan.
2. Configurar el software
Sección titulada «2. Configurar el software»PUT /v1/tenant/software/invoicing{ "softwareId": "...", "pin": "...", "testSetId": "...", "environment": "2", "enablementMode": true }Familias: invoicing (FEV, NC, ND), support_document, pos, payroll, radian.
Con enablementMode: true los documentos se envían con SendTestSetAsync + GetStatusZip.
Al terminar la habilitación se cambia a enablementMode: false (y luego environment: "1"
para producción) y se usa SendBillSync / SendNominaSync / SendEventUpdateStatus.
Modelo A (proveedor tecnológico): se envían también providerNit y providerDv, y se configura
PROVIDER_CODE con el código asignado por la DIAN.
3. Rangos de numeración
Sección titulada «3. Rangos de numeración»Para habilitación hay rangos predefinidos:
POST /v1/tenant/numbering-ranges/enablement{ "kinds": ["invoice", "credit_note", "debit_note"] }La factura usa la resolución de pruebas de la DIAN (prefijo SETP, 990000000–995000000,
resolución 18760000001 y su clave técnica). Verifica en el portal los datos del rango de
pruebas de documento soporte y POS asignados a tu software y créalos con
POST /v1/tenant/numbering-ranges si difieren de los predefinidos.
En producción, las resoluciones se consultan con GET /v1/tenant/numbering-ranges/dian
(GetNumberingRange) y se registran con POST /v1/tenant/numbering-ranges, incluida la
clave técnica (technicalKey) para la factura.
4. Certificado
Sección titulada «4. Certificado»Opción A: generar la clave en la plataforma y pedir el certificado con el CSR:
POST /v1/tenant/certificates/csr → csrPem (y GET /v1/tenant/certificates/{id}/csr descarga el .p10)POST /v1/tenant/certificates/{id}/import { "certificate": "<PEM / DER base64 / PKCS#7 entregado por la ECD>" }Opción B: subir un .p12/.pfx completo: POST /v1/tenant/certificates/p12 { "p12": "<base64>", "password": "..." }.
5. Enviar el set de pruebas
Sección titulada «5. Enviar el set de pruebas»Emite los documentos que exige el set (normalmente facturas, notas crédito y notas débito).
Cada documento queda sent con su zipKey y el worker consulta GetStatusZip hasta obtener
accepted o rejected. Revisa los errores en GET /v1/documents/{id} (dian.errors): incluyen
la regla del anexo (ej. Regla: FAD06).
Cuando el set queda aceptado en el portal, cambia el software a producción (paso 2).