Paso a producción

Producción emite documentos con validez fiscal ante la DIAN. Por eso es un paso que decide una persona, no un agente ni un script. Esta guía reúne lo que cambia y lo que conviene comprobar; el proceso de la DIAN para producción lo describe la propia DIAN.

Los pasos para pasar a producción

En foliios no hay un botón que «active» producción ni un paso en que foliios la habilite para tu empresa. Producción es un ambiente del portal: queda lista cuando tiene su propio software, certificado, resolución y una clave sk_live_.

1. En la DIAN, con el set de habilitación aprobado, pasa tu software al estado «Facturando electrónicamente».
2. En la DIAN, pide la numeración de producción (formulario 1876) y asóciala a tu software.
3. En foliios, activa tu cuenta: compra una bolsa de documentos (se activa al instante; ver precios) o acuerda con foliios otra vía. Sin activar, el portal responde 402 activation_required (errores) al crear una clave sk_live_, guardar el software o registrar o sincronizar resoluciones de producción, y no cambia nada: verás el aviso «Activa tu cuenta para producción», con el botón Comprar documentos cuando la compra en línea está abierta, o el contacto de foliios.
4. En el portal, cambia al ambiente Producción: con el selector Ambiente de la barra lateral o con Cambiar a Producción, en la franja que avisa que estás en habilitación. Lo que sigue se hace en ese ambiente; lo que configuraste en Habilitación no cuenta para Producción.
5. En Empresa, sección Software DIAN · Producción, pulsa Configurar y guarda el SoftwareID, el NIT del proveedor y el PIN. Va antes que la resolución: sin software, registrarla o sincronizarla responde 409 software_not_configured.
6. En Certificado, sube el certificado de firma de producción (Subir certificado). El portal te deja configurar lo demás sin él, pero no sincroniza las resoluciones.
7. En Resoluciones, usa Sincronizar con la DIAN (deshabilitado mientras falte el certificado de Producción) o Registrar resolución para copiarla a mano.
8. En Claves de API, pulsa Crear clave y elige el ambiente Producción.

Quién puede hacerlo. Los pasos 5 a 8 piden el rol owner o admin; con otro rol la API del portal responde 403 insufficient_permissions. Crear una clave sk_live_ exige además haber iniciado sesión hace menos de 15 minutos: si no, responde 403 reauthentication_required y basta con volver a iniciar sesión.

La página Primeros pasos del portal resume estos pasos y marca los que ya están hechos.

Antes de empezar

1. Terminaste la integración en el sandbox. La verificación de integración da complete: true, y revisaste las comprobaciones que ella no puede hacer: reintento idempotente y corrección de rechazos.
2. Aprobaste la habilitación. El set de habilitación aprobado con tu software vigente (habilitación). Es el ensayo real con la DIAN.
3. Tu cuenta está activada (una compra vigente o un acuerdo con foliios). Es una condición para configurar producción, no para el sandbox ni la habilitación; las claves sk_live_ que ya existían siguen funcionando.
4. La empresa está configurada para producción en el portal: datos del emisor, software de producción, resolución de producción y certificado. Hasta que lo esté, una clave sk_live_ responde 409 environment_not_configured, sin consumir número ni tu Idempotency-Key.
5. Registraste las resoluciones de producción. Con el certificado de producción cargado, el portal puede sincronizarlas con la DIAN (en habilitación se copian a mano; en producción se traen desde la DIAN) y registra las que falten.
6. Tienes un gestor de secretos para la clave sk_live_ y el secreto del webhook de producción. No son los del sandbox.

Qué cambia

	Sandbox	Habilitación (test)	Producción (live)
Clave	sk_sandbox_	sk_test_	sk_live_
Destino	DIAN simulada	Habilitación de la DIAN	Producción de la DIAN
Efecto fiscal	Ninguno	Ninguno	Real
Escenarios (Foliios-Sandbox-Scenario)	Sí	422 sandbox_scenario_not_allowed	422 sandbox_scenario_not_allowed
Correo al comprador	Buzón de pruebas	Buzón de habilitación (no se envía, salvo el tope de correos reales que foliios habilite para tu empresa)	Correo real
Contingencia	Reintentos acelerados	Intervalo normal	Intervalo normal
Datos del sandbox	Se borran a los 30 días	No aplica	No aplica
Bloqueo hasta aprobar el set	No	Sí (409 habilitation_required)	No

Cambia también tu configuración:

• Usa una clave por ambiente y no mezcles las variables: la clave decide el ambiente, y un documento nunca cambia de ambiente.
• Cambia el resolution_id por el de la resolución de producción. La del sandbox (18760000000000) no existe en producción: 422 resolution_not_found.
• El endpoint de webhooks se registra aparte para producción, con su propio secreto. Distingue por environment y livemode en el cuerpo (webhooks).
• Quita cualquier cabecera Foliios-Sandbox-Scenario de tu código.

Si usas el MCP

En producción, las herramientas que escriben (issue_document, resubmit_document, retry_document y la transcripción) piden una confirmación explícita. Un agente debe parar y pedírsela a la persona, no darla por sí mismo. Con una conexión de agente puedes además exigir aprobación de borradores, un monto máximo por documento y un tope diario.

El primer documento real

1. Emite una factura real, de bajo monto, con una Idempotency-Key propia.
2. Consulta que llega a accepted y guarda number y cufe.
3. Verifica que el correo llegó al comprador (o, si no hay correo, descarga el PDF).
4. Confirma en el catálogo de la DIAN que el documento aparece.
5. Revisa que tus webhooks de producción recibieron document.accepted y que la firma se verifica (verificar la firma).

Plan para cuando algo falla

• Rechazo: rechazos y reenvío. El número de una factura rechazada se libera; el de una nota no.
• La DIAN no responde: contingencia. No reenvíes: espera.
• Tu sistema se cae: factura de papel, con sus plazos y su carta.
• No sabes si un documento quedó aceptado: consulta GET .../documents/{document_id} antes de emitir otro; no repitas la emisión con otra Idempotency-Key.

Lo que foliios hace por tu empresa, y lo que sigue siendo tuyo, está en responsabilidades.