Ambientes

Emitia tiene tres ambientes. Subes de uno al siguiente cuando estás listo — no hay saltarse pasos.

test (sandbox)  →  habilitacion  →  production

---

Resumen rápido

Propiedad	test (sandbox)	habilitacion	production
Clave API	sk_test_…	sk_live_…	sk_live_…
DIAN destino	Ninguno (simulado)	VPFE habilitación	VPFE producción
Certificado .p12	Mock interno	ONAC real	ONAC real
CUFE	Simulado (no válido ante DIAN)	Válido ante DIAN habilitación	Válido ante DIAN producción
Efectos legales	Ninguno	Pruebas oficiales	Facturas legales
Costo por factura	Sin costo	Sin costo (cuota mensual)	Según plan

---

test — sandbox

El ambiente de desarrollo. Las llamadas con sk_test_ nunca llegan a la DIAN: Emitia simula la respuesta internamente.

Para qué sirve:

• Integrar y probar tu código sin efectos reales.
• Usar los NITs de prueba deterministas:
  • 900000001-1 → siempre aceptada
  • 900000002-9 → siempre rechazada (FAJ21)
  • 900000003-7 → timeout simulado
• Recibir webhooks de prueba en tu endpoint local.

Lo que NO tiene:

• Un CUFE válido ante la DIAN (es una cadena simulada).
• Envío real de email al adquirente.
• Numeración que cuenta ante la DIAN.

Usa sk_test_ en todo tu desarrollo

Nunca expongas una sk_live_ en desarrollo local, en tests automatizados ni en variables de entorno de staging sin los permisos correctos. sk_test_ es suficiente para todo lo anterior.

---

habilitacion — ambiente oficial de pruebas DIAN

El ambiente de certificación. Las facturas van al sistema real de la DIAN (vpfe-hab.dian.gov.co), se firman con un certificado ONAC real, y el CUFE generado es válido ante la DIAN de habilitación.

Requisitos para habilitar este ambiente:

1. Certificado .p12 emitido por una CA acreditada ONAC (no el de prueba).
2. Resolución de numeración registrada ante la DIAN.
3. Software habilitado por la DIAN (Emitia ya está habilitado como Proveedor Tecnológico).

Para qué sirve:

• Correr el proceso de habilitación oficial DIAN (enviar los 10 documentos de prueba).
• Validar tu integración contra el sistema real antes de ir a producción.

El certificado de prueba NO funciona aquí

Muchos desarrolladores se confunden: el certificado autofirmado o de desarrollo firma el XML localmente, pero la DIAN rechaza el documento porque el certificado no está en la cadena de confianza ONAC. Para habilitacion y production se requiere un certificado real emitido por una CA acreditada como Certicámara, GSE, o ANDES SCD. Ver Conceptos: Certificados.

---

production — producción real

Facturas legalmente vinculantes ante la DIAN y el adquirente.

Cómo llegar a producción:

1. Completar el proceso de habilitación en el ambiente habilitacion.
2. Obtener la resolución de numeración para producción.
3. Cambiar el ambiente del tenant a production desde el dashboard.
4. A partir de ese momento, todas las llamadas con sk_live_ van a producción.

No hay rollback fácil de producción

Una vez que tienes facturas en producción, la numeración es legal y secuencial. No puedes “anular” una secuencia de numeración. Asegúrate de completar la habilitación en el ambiente de pruebas antes de activar producción.

---

¿Cómo sé en qué ambiente está mi tenant?

GET /v1/account devuelve el campo dian_environment:

{
  "id": "ten_01HX…",
  "name": "Mi empresa SAS",
  "dian_environment": "habilitacion",
  "key_mode": "test"
}

• key_mode: "test" → estás usando una clave sk_test_, el ambiente es sandbox.
• key_mode: "live" → estás usando sk_live_, el ambiente real es dian_environment.

---

El ambiente es estado del tenant, no del sistema

Una misma instancia de Emitia atiende a tenants en distintos ambientes. El ambiente no es un toggle global del stack — es una propiedad del tenant guardada en base de datos (tenants.dian_environment).

Esto significa:

• Puedes tener un tenant en habilitacion y otro en production al mismo tiempo.
• Cambiar el ambiente de un tenant no afecta a los demás.
• La API recibe el ambiente del tenant que autenticó la request.

---

Próximos pasos

• Conceptos: Certificados — escalera del certificado .p12
• Inicio rápido — primera factura en sandbox
• Guía de mapeo POS — mapeo de datos de tu sistema a Emitia