Autenticación y Credenciales

Credenciales Activas

Las credenciales de ambiente Demo están activas y validadas. Las credenciales de Producción se proporcionarán tras completar las pruebas.

Tipos de Credenciales

Facturatech maneja tres tipos de credenciales según el propósito de uso:

C1 - Demo para ERP

Propósito: Desarrollo y validación de estructura XML
Características:

• Validación completa de estructura
• Sin envío real a DIAN
• Ideal para pruebas de integración

Ambiente Actual

C2 - Demo con Consumo

Propósito: Pruebas de integración completas
Características:

• Validación completa
• Simulación de respuestas DIAN
• Rate limiting activo

C3 - Productivo

Propósito: Emisión real de nómina electrónica
Características:

• Envío real a DIAN
• Firma digital oficial
• CUNE válido legalmente

Próximamente

---

Ambientes Disponibles

Sandbox (Demo)

Ambiente de Desarrollo

Ambiente actual para pruebas y desarrollo de la integración.

Configuración Sandbox

{
  "ambiente": "demo",
  "wsdl": "https://ws-nomina.facturatech.co/v1/demo/index.php?wsdl",
  "namespace": "urn:https://ws-nomina.facturatech.co/v1/demo/",
  "usuario": "DATAEM19112025",
  "password_sha256": "f8c0e8471f126c77bd23f664f3ce251b8f9943f1d95a6ffdda72f8e6b76c9b93",
  "tipo_credencial": "C1"
}

Note

El password debe estar pre-encriptado en SHA256 antes de enviarse en cada request.

Características del Sandbox

• Todas las validaciones de estructura XML activas
• Rate limiting simulado (20 req/10s)
• Generación de TransactionID
• Simulación de estados (pendiente → autorizado)
• Descarga de XML y PDF de prueba
• CUNE generado NO es válido ante DIAN
• Sin envío real a sistemas gubernamentales

Producción

Ambiente Productivo

Próximamente

El ambiente productivo estará disponible tras completar exitosamente:

1. Todas las pruebas en Sandbox
2. Piloto con nómina de Conectera
3. Validación del PO y líder técnico

Configuración Producción

{
  "ambiente": "produccion",
  "wsdl": "[POR DEFINIR - Pendiente por Facturatech]",
  "namespace": "[POR DEFINIR]",
  "usuario": "[A proporcionar]",
  "password_sha256": "[A proporcionar]",
  "tipo_credencial": "C3"
}

Requisitos para Activación

• Finalizar fase de pruebas en Sandbox
• Completar piloto interno (nómina Conectera)
• Aprobación del líder técnico
• Validación del Product Owner
• Solicitud formal a Facturatech
• Configuración de certificados digitales (si aplica)

---

Generación de Password SHA256

El API requiere que el password se envíe encriptado con SHA256 en cada petición.

PHP

Encriptación SHA256 en PHP

<?php
$passwordOriginal = "mi_password_secreto";
$passwordSHA256 = hash('sha256', $passwordOriginal);

echo $passwordSHA256;
// Output: f8c0e8471f126c77bd23f664f3ce251b8f9943f1d95a6ffdda72f8e6b76c9b93

JavaScript

Encriptación SHA256 en Node.js

const crypto = require('crypto');

const passwordOriginal = "mi_password_secreto";
const passwordSHA256 = crypto
  .createHash('sha256')
  .update(passwordOriginal)
  .digest('hex');

console.log(passwordSHA256);
// Output: f8c0e8471f126c77bd23f664f3ce251b8f9943f1d95a6ffdda72f8e6b76c9b93

Bash

Encriptación SHA256 en Terminal

echo -n "mi_password_secreto" | sha256sum
# Output: f8c0e8471f126c77bd23f664f3ce251b8f9943f1d95a6ffdda72f8e6b76c9b93

Importante

• El password debe encriptarse en cada petición
• No enviar el password en texto plano
• El hash debe ser en minúsculas (lowercase)
• No incluir saltos de línea ni espacios

---

Configuración en Zend Framework 1.12

application.ini

application/configs/application.ini

; Facturatech - Nómina Electrónica
facturatech.ambiente = "demo"
facturatech.wsdl.demo = "https://ws-nomina.facturatech.co/v1/demo/index.php?wsdl"
facturatech.wsdl.produccion = ""
facturatech.namespace.demo = "urn:https://ws-nomina.facturatech.co/v1/demo/"
facturatech.namespace.produccion = ""
facturatech.usuario = "DATAEM19112025"
facturatech.password = "f8c0e8471f126c77bd23f664f3ce251b8f9943f1d95a6ffdda72f8e6b76c9b93"
facturatech.timeout = 30
facturatech.trace = 1

Clase de Configuración

library/Dataemunah/Facturatech/Config.php

<?php

class Dataemunah_Facturatech_Config
{
    private static $_config = null;

    public static function init()
    {
        if (self::$_config === null) {
            $config = Zend_Registry::get('config');
            self::$_config = $config->facturatech;
        }
        return self::$_config;
    }

    public static function getWsdl()
    {
        $config = self::init();
        $ambiente = $config->ambiente;

        return ($ambiente === 'produccion')
            ? $config->wsdl->produccion
            : $config->wsdl->demo;
    }

    public static function getNamespace()
    {
        $config = self::init();
        $ambiente = $config->ambiente;

        return ($ambiente === 'produccion')
            ? $config->namespace->produccion
            : $config->namespace->demo;
    }

    public static function getUsuario()
    {
        return self::init()->usuario;
    }

    public static function getPassword()
    {
        return self::init()->password; // Ya está en SHA256
    }

    public static function isProduccion()
    {
        return self::init()->ambiente === 'produccion';
    }
}

---

Mejores Prácticas de Seguridad

NO Hacer

• Guardar passwords en texto plano
• Hacer commit de credenciales al repo
• Loggear passwords (ni SHA256)
• Compartir credenciales por email
• Usar mismas credenciales en todos los ambientes

SÍ Hacer

• Usar variables de entorno
• Encriptar archivos de configuración
• Rotar credenciales periódicamente
• Documentar cambios de credenciales
• Restringir acceso a configuración

Variables de Entorno (Recomendado)

.env (NO committear)

FACTURATECH_AMBIENTE=demo
FACTURATECH_USUARIO=DATAEM19112025
FACTURATECH_PASSWORD_SHA256=f7fc87af7f8887g7878ad7777887ddf60f8d8998

Cargar desde .env

<?php
// En Bootstrap
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$config->facturatech->usuario = $_ENV['FACTURATECH_USUARIO'];
$config->facturatech->password = $_ENV['FACTURATECH_PASSWORD_SHA256'];

---

Validar Conexión

Script de Prueba

tests/facturatech-connection-test.php

<?php
require_once 'library/Dataemunah/Facturatech/Config.php';

try {
    $wsdl = Dataemunah_Facturatech_Config::getWsdl();

    $client = new SoapClient($wsdl, [
        'trace' => 1,
        'exceptions' => true,
        'encoding' => 'UTF-8',
        'soap_version' => SOAP_1_1,
        'connection_timeout' => 10
    ]);

    echo "Conexión exitosa a Facturatech\n";
    echo "Ambiente: " . Dataemunah_Facturatech_Config::init()->ambiente . "\n";
    echo "WSDL: " . $wsdl . "\n";

    // Listar funciones disponibles
    echo "\nFunciones disponibles:\n";
    foreach ($client->__getFunctions() as $function) {
        echo "  - " . $function . "\n";
    }

} catch (SoapFault $e) {
    echo "Error de conexión: " . $e->getMessage() . "\n";
    exit(1);
} catch (Exception $e) {
    echo "Error general: " . $e->getMessage() . "\n";
    exit(1);
}

Salida esperada:

 Conexión exitosa a Facturatech
 Ambiente: demo
 WSDL: https://ws-nomina.facturatech.co/v1/demo/index.php?wsdl

 Funciones disponibles:
  - uploadDocument(string $username, string $password, string $xmlBase64)
  - documentStatus(string $username, string $password, string $transaccionID)
  - downloadXML(string $username, string $password, string $prefijo, string $folio)
  - downloadPDF(string $username, string $password, string $prefijo, string $folio)
  - downloadCUNE(string $username, string $password, string $prefijo, string $folio)

---

Checklist de Configuración

Antes de iniciar la integración, verificar:

• Credenciales de Sandbox validadas
• Configuración en application.ini correcta
• Variables de entorno configuradas (si aplica)
• Clase Dataemunah_Facturatech_Config implementada
• Script de validación de conexión ejecutado exitosamente
• Extensión SOAP de PHP habilitada
• OpenSSL instalado para SHA256
• Firewall permite conexión a *.facturatech.co
• Logs de conexión configurados
• Documentación de credenciales en lugar seguro

---

Rotación de Credenciales

Proceso Recomendado

1. Solicitar nuevas credenciales a Facturatech
2. Validar en ambiente de prueba antes de aplicar
3. Actualizar configuración en archivo .env o application.ini
4. Ejecutar script de validación de conexión
5. Documentar el cambio con fecha y responsable
6. Eliminar credenciales antiguas de sistemas

Frecuencia Recomendada

Se recomienda rotar credenciales cada 6 meses o inmediatamente si:

• Se detecta acceso no autorizado
• Personal con acceso deja la empresa
• Se compromete el sistema de configuración

---

Soporte

¿Problemas con las credenciales o autenticación?

• Facturatech: [soporte@facturatech.co]
• Equipo Dataemunáh: [helpdesk@conectera.co]
• Documentación oficial: Revisar PDFs proporcionados los cuales estan en la unidad de red NOMINA:\3. documentacion\facturatech\integracion o comunicarse con el Lider tecnico del producto

---

Próximos Pasos

Una vez configurada la autenticación:

1. Explorar la Estructura XML de Nómina
2. Revisar los Endpoints disponibles
3. Ejecutar Pruebas en Sandbox