Ir al contenido

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).

  1. 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.
  2. 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.
  3. Mandato y autorización de custodia firmados por el facturador (Ley 527 de 1999).

Todas las rutas usan Authorization: Bearer <api key> y X-Tenant-Id: <NIT> (o una llave restringida al 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.

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.

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.

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": "..." }.

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).