Saltar al contenido principal

Alta de un nuevo tenant paso a paso

Este es el flujo completo para dar de alta una empresa nueva, desde su registro hasta quedar emitiendo en producción. Todas las llamadas requieren un token de un usuario admin o superadmin (ver Autenticación) y, donde aplica, el NIT de la empresa en la ruta.

:::info Prerrequisitos Antes de empezar, la empresa debe tener listos su certificado .p12 y sus credenciales DIAN. Ver Prerrequisitos por tenant. :::

1. Registrar el tenant​

POST /tenants

Crea el registro de la empresa con su NIT, dígito de verificación, razón social, municipio y ambiente inicial (habilitacion).

{
  "nit": "900123456",
  "digitoVerificacion": "7",
  "razonSocial": "Mi Empresa SAS",
  "ambiente": "habilitacion",
  "municipioCodigo": "11001",
  "regimen": "48",
  "email": "facturacion@miempresa.com"
}

2. Subir el certificado digital​

POST /tenants/:nit/certificate

Sube el .p12 en Base64 junto con su contraseña. La API lo cifra con AES-256 y lo guarda en la base de datos (nunca en disco).

{
  "certBase64": "<contenido .p12 en Base64>",
  "password": "<contraseña del certificado>"
}

3. Configurar las credenciales DIAN​

PATCH /tenants/:nit/dian-config

Registra softwareId, softwarePin, testSetId, contributorId y la clave técnica obtenidos del portal DIAN.

{
  "softwareId": "<id asignado por DIAN>",
  "softwarePin": "<pin del software>",
  "technicalKey": "<clave técnica de la resolución>",
  "testSetId": "<id del set de pruebas>",
  "contributorId": "<número de la URL del portal>"
}

4. Registrar la resolución de habilitación​

PATCH /tenants/:nit/resolution

Resolución de numeración para el set de pruebas, con prefijo SETP y ambiente: "habilitacion".

{
  "ambiente": "habilitacion",
  "prefijo": "SETP",
  "desde": 990000001,
  "hasta": 995000000,
  "fechaDesde": "2026-01-01",
  "fechaHasta": "2027-01-01"
}

5. Ejecutar el proceso de habilitación​

POST /tenants/:nit/habilitacion/run

Envía automáticamente el set de pruebas a la DIAN (4 documentos: 2 facturas, 1 nota crédito y 1 nota débito) usando SendTestSetAsync. Ver Proceso de habilitación DIAN.

6. Consultar el estado de la habilitación (polling)​

GET /tenants/:nit/habilitacion/status

Consulta el estado del proceso: pendiente, en_proceso, aprobada o rechazada. Se consulta repetidamente (polling) hasta obtener un estado final.

7. Registrar la resolución de producción​

PATCH /tenants/:nit/resolution

Una vez aprobada la habilitación, registra la resolución real autorizada por la DIAN, con el prefijo propio y ambiente: "produccion".

{
  "ambiente": "produccion",
  "numero": "18760000001",
  "prefijo": "FV",
  "desde": 1,
  "hasta": 5000,
  "fechaDesde": "2026-01-01",
  "fechaHasta": "2027-01-01"
}

8. Activar producción​

POST /tenants/:nit/go-production

Valida que la habilitación esté aprobada y que exista una resolución de producción vigente; si todo está correcto cambia el ambiente del tenant a produccion. A partir de aquí, la emisión usa SendBillSync contra la URL de producción de la DIAN.

:::tip Estado del tenant En cualquier momento puedes consultar GET /tenants/:nit/status para ver el ambiente, estado de habilitación, resolución activa y próximo consecutivo. :::

Siguiente paso​

Con el tenant en producción, ya puedes Emitir documentos electrónicos →.