Generalidades - Indice Manual Integración Directa

Historial de versiones

Versión	Fecha lanzamiento	Descripción
0	07/05/2019	Versión Preliminar.
1.0	14/06/2019	Versión Inicial. Referencia DIAN “Anexo Técnico V1.4 (19-04-19)”.
1.1	04/07/2019	Actualización Referencia DIAN “Anexo técnico de factura electrónica de venta – final”
1.2	04/07/2019	Actualizaciones menores
1.3	19/08/19	Actualizaciones menores
1.4	23/08/19	Actualización respuesta ante el método enviar. Lista de campos extensibles y catalogo de errores.
1.5	09/2019	Actualizaciones de comodines con base en el Anexo Técnico del 06 de septiembre
1.6	04/2020	Actualizaciones con base en el Anexo Técnico 1.8. Acuse del adquiriente. Personalización correo. Extras. Radicar documentos en recepción. Tablas de códigos. Cambio del nombre del documento. Entre otros cambios menores.
1.7	06/2020	Actualizaciones con base en el Anexo Técnico V1.7-2020. Ajustes de funcionalidades de la plataforma en el mes de mayo.
2.0	06/2021	Actualizaciones en base al anexo técnica V1.8 de la Resolución 000012. Campos Sector Salud. Tablas de códigos.
2.1	10/2021	Actualizaciones en base al anexo técnica V1.8 de la Resolución 000012. Campos Sector Salud. Tablas de códigos.

Cómo obtener soporte

• Soporte de 1er nivel:

Soporte telefónico / email / chat o tele-conferencias en horario 5x8 para atención de consultas y fallas de usuario.

• Soporte de 2do nivel:

Soporte resolución remota de incidencias en el sistema en horario 5x8

Escriba a soporte@thefactoryhka.com.co

Para consultas referente a configuraciones y errores en el Portal:

• soporte_fel_co@thefactoryhka.com

Para consultas referente a configuraciones de ERP, casa de software e integración:

• integracion_fel_co@thefactoryhka.com

Lineas de atención telefónica:

• MASTER +57 (1) 746.08.12
• +57 (1) 508.8990
• +57 (1) 517.6795
• +57 (1) 517.6796
• +57 (1) 311.3063
  • Soporte Técnico → Opción 2
  • Integración → Opción 5 Luego Opción 1

Para Sesiones:

Sesiones Soporte

Inscripción como facturador electrónico, Configuración de Rangos de Numeración, Configuración Datos Fiscales, Pruebas de Habilitación, Configuración ambiente Producción, manejo y uso del Portal de Facturación electrónica de TFHKA

Dirigido a: Agencias Comerciales – Casas de Software Aliadas - Clientes Finales

Horario: Martes y Jueves a partir de las 8:30 AM

Enlace Sesiones de Soporte

Sesiones Área Integración

Solución Casos de Integración

Dirigido a: Clientes que realicen desarrollos de Software para integrarse con TFHKA, Casas de Software Aliadas

Horario: Martes y Jueves a partir de las 8:30 AM

Enlace Sesiones Integración

Descripción general

En el presente documento se describe el proceso de integración entre el modelo de facturación electrónica con validación previa de acuerdo a las actualizaciones normativas y técnicas proveniente de la DIAN y/o controles propios en nuestro modelo de integración.

Para el desarrollo de éste documento, se tomó como referencia los Anexos técnicos V1.7-2020 (vigente) y V1.8 (este último liberado en octubre de 2019 por la DIAN).

Nota: No todas las funcionalidades, catalogos y escenarios de facturación referentes al Anexo Técnico V1.8 están habilitados por la DIAN.

¿Qué es The Factory HKA Factura?

Es una plataforma de facturación electrónica, diseñada para dar cumplimiento a la legislación vigente en Colombia y ofrecer valores agregados mediante servicios complementarios. Conformada por un portal con capacidad de emitir documentos bajo el esquema de facturación electrónica, administrada desde el portal web y dirigido a contribuyentes que tengan la obligación de expedir factura electrónica por resolución de la DIAN.

¿Qué es HKA Integración?

Es un producto dirigido al integrador y está conformado por los siguientes componentes:

• Manuales de integración.
• Bolsa de horas de soporte vía email y/o tele-conferencias.
• Credenciales para ambiente de pruebas (DEMO) y productivo.
• Templates configurables para representación gráfica.

Funcionalidades

La plataforma The Factory HKA Factura permite la emisión, recepción, consulta, visualización y descarga de los siguientes documentos en formato XML y/o su correspondiente representación gráfica en PDF:

• Factura de Venta Nacional
• Factura de Exportación
• Factura por contingencia
• Nota de Crédito
• Nota de Débito

Adicionalmente, la plataforma permite consultar el estatus del Acuse de Recibo por parte del adquirente, estatus del documento por parte de la DIAN, consultar la cantidad de timbres/folios disponibles y enviar comprobantes a través de correo electrónico.

@Importante: Solo es posible visualizar en nuestro portal web o descargar representaciones graficas (PDF de documentos electrónicos) generados por nuestra plataforma.

La integración directa

La integración es una actividad esencial para la puesta en marcha de la facturación electrónica en un Sistema de Facturación o Software Administrativo (ERP) y se realizará sólo una vez. Esta actividad consiste en enlazar dos plataformas con tecnologías distintas con el objetivo de transmitir los datos necesarios para la construcción de los documentos y el seguimiento exitoso del ciclo de vida.

En el caso de la integración directa, la comunicación se conecta directamente al Web Service, lo cual tiene como ventaja el control total del ciclo de vida del documento electrónico, desde el origen de los datos, pasando por el proceso de transmisión hasta su entrega, acuse de recibo y validación. Esta forma de integración permite reaccionar de un modo más rápido y eficiente ante errores o inconsistencias que se presenten en el proceso.

La integración directa es un proceso exclusivo entre el software integrado y la plataforma The Factory HKA Factura.

@Importante: No es necesario implementar integración adicional ante la DIAN, ya que se cuenta con la funcionalidad completa de seguimiento del estatus del documento.

Requerimientos técnicos para la integración directa

The Factory HKA Factura es una plataforma tipo SaaS (Software as a Service): Los servicios, la información, el procesamiento, los insumos y resultados están alojados en nuestros servidores (como proveedor tecnológico), y nos ocupamos del mantenimiento, la operación, los cambios normativos y el soporte de la solución.

Por normativa de la DIAN, el proveedor tecnológico tiene la obligación de conservar los documentos y garantizar la integridad y seguridad de los datos bajo el estándar ISO 27001. Por tanto, no es necesario una extensa planificación de infraestructura de procesamiento y almacenamiento para implementar la facturación electrónica.

Los parámetros necesarios para la construcción de cada transacción son expuestos independientemente al momento de consumir los servicios, y el resultado es entregado enteramente al final de la operación. Eso significa que The Factory HKA no requiere manejar bases de datos de clientes o productos/servicios. Como proveedor tecnológico, The Factory HKA Colombia cuenta con recurso humano dedicado a hacer seguimiento y analizar los cambios normativos que progresivamente emite la DIAN. De generarse un cambio significativo que impacte del lado de la integración como, se proveerá de las herramientas necesarias y de instrucciones para aplicar los correctivos de la forma más sencilla posible.

La plataforma The Factory HKA Factura pone a disposición de la integración un Web Service como solución para interoperación con terceros. El Web Service está desarrollado en SOAP (Simple Object Access Protocol). Por tanto, como únicos requerimientos para la integración serán los siguientes:

• Capacidad de consumo de WS SOAP del software (ambiente de desarrollo) a utilizar.
• Capacidad de captación y validación de los datos de entrada.
• Opcional: Capacidad para almacenar copia del XML/PDF por transacción.
• Capacidad para el despliegue del estado del ciclo de vida del documento electrónico.

Esquemas de integración directa para Factura Electrónica TFHKA

The Factory HKA Factura expone los siguientes esuqemas de integración directa por medio del consumo de Web Service como solución para interoperación con terceros. El Web Service está desarrollado en SOAP (Simple Object Access Protocol) y REST (Representational State Transfer)

Esquema de integración directa para Factura Electrónica SOAP

Contamos con un web service basado en arquitectura XML SOAP, en el cual se permite hacer validaciones iniciales frente a la DIAN y el posterior envio de los documentos electronicos en ambiente PRODUCTIVO y de esta forma conocer la estructura del objeto Factura y origen de datos propuesto por TFHKA

URL Ambiente DEMO (ambiente de pruebas en el cual las emisiones no son transmitidas a la DIAN):

http://demoemision21v4.thefactoryhka.com.co/ws/v1.0/Service.svc?wsdl --> Servicio Emisión
http://demoemision21v4.thefactoryhka.com.co/ws/adjuntos/Service.svc?wsdl --> Servicio Adjuntos
http://demoemision21.thefactoryhka.com.co/ws/reportes/Service.svc?wsdl --> Servicio Reportes

URL Ambiente Productivo (ambiente en el cual se realizan las emisiones correspondientes al set de habilitación y posteriormente la emisión de documentos en operación):

https://emision21v4.thefactoryhka.com.co/ws/v1.0/Service.svc?wsdl --> Servicio Emisión (HTTPS)
https://emision21v4.thefactoryhka.com.co/ws/adjuntos/Service.svc?wsdl --> Servicio Adjuntos (HTTPS)
https://emision21.thefactoryhka.com.co/ws/reportes/Service.svc?wsdl --> Servicio Reportes (HTTPS)

@IMPORTANTE:La url del servicio SOAP en producción solo esta funcional bajo el protocolo https.

NOTA: Si no pueden acceder a dicha configuración en el interfaz del sistema, por favor, comunicarse con su casa de software o desarrollador del ERP con el fin de que puedan validar lo anteriormente descrito. De no solventarse el inconveniente con lo mencionado, por favor, enviar un correo al área de integración integracion_fel_co@thefactoryhka.com con la siguiente información:

• Request enviado al WS.
• Captura de la configuración realizada en el sistema donde se visualice la información de las URL y tokens indicada.

NUEVO Esquema de integración directa para Factura Electrónica REST

Web Service REST basado en arquitectura JSON permite hacer validaciones iniciales frente a la DIAN y el posterior envio de los documentos electronicos en ambiente PRODUCTIVO y de esta forma conocer la estructura del objeto Factura y origen de datos propuesto por TFHKA.

URL Ambiente DEMO (ambiente de pruebas en el cual las emisiones no son transmitidas a la DIAN):

https://demoemision21-api.thefactoryhka.com.co --> Servicio Emisión (HTTPS)

URL Ambiente Productivo (ambiente en el cual se realizan las emisiones correspondientes al set de habilitación y posteriormente la emisión de documentos en operación):

https://emision21-api.thefactoryhka.com.co --> Servicio Emisión (HTTPS)

@IMPORTANTE:La url del servicio REST en producción solo esta funcional bajo el protocolo https.

NOTA: Si no pueden acceder a dicha configuración en el interfaz del sistema, por favor, comunicarse con su casa de software o desarrollador del ERP con el fin de que puedan validar lo anteriormente descrito. De no solventarse el inconveniente con lo mencionado, por favor, enviar un correo al área de integración integracion_fel_co@thefactoryhka.com con la siguiente información:

• Request enviado al WS.
• Captura de la configuración realizada en el sistema donde se visualice la información de las URL y tokens indicada.

Esquema de operación de la factura electrónica con validación previa

¿Qué es la Facturación Electrónica con Validación Previa?

La Facturación Electrónica (FEL) es un esquema de operación que permite emitir documentos de respaldo de las operaciones comerciales entre contribuyentes en formato digital en lugar de papel, permite la aplicación de control fiscal durante el proceso, y tiene validez legal para el ente tributario designado por el gobierno del país.

A partir de septiembre de 2019, se tiene previsto que una factura electrónica solo será válida cuando se haya validado previamente su contenido a través de la DIAN o a través de un proveedor autorizado por la administración de impuestos.

La validación previa se encuentra establecida en la ley 1943 de 2018, conocida como Ley de Financiamiento. El artículo 16 de esta Ley modifica el artículo 616-1 del Estatuto Tributario, en su parágrafo primero consagra que:

“Todas las facturas electrónicas para su reconocimiento tributario deberán ser validadas previo a su expedición, por la DIAN o por un proveedor autorizado por esta. La factura electrónica solo se entenderá expedida cuando sea validad y entregada al adquiriente. (…)”

En el modelo de facturación electrónica con validación previa se utilizarán 5 tipos de documentos:

• Invoice (Factura)
• CreditNote (Nota Crédito)
• DebitNote (Nota Débito)
• ApplicationResponse (Evento): Ocurrencia relacionada con un Documento Electrónico, generada por una persona o entidad relacionada con el documento (DIAN, Emisor, Adquiriente), este documento también contiene una firma electrónica.
• AttachedDocument (Contenedor de Documentos): La estructura de este documento tiene por objetivo contener en un único archivo XML un documento electrónico (Invoice, CreditNote ó DebitNote) y todos los eventos (ApplicationResponse) registrados hasta la fecha.

¿Quiénes participan en este esquema?

El Ente Tributario (DIAN): Es una institución pública, nombrada por el gobierno para recaudar, controlar y regular todo lo relacionado con los tributos. Es el que tiene el derecho de aceptar y autorizar un documento electrónico. En Colombia, es la DIAN (Dirección de Impuestos y Aduanas Nacionales).

El Emisor o Contribuyente: Es una persona natural o jurídica que posee un registro de información fiscal único y legal ante el ente tributario (NIT: Número de Identificación Tributario) y está bajo la obligación de emitir documentos para respaldar sus transacciones comerciales. El emisor adquiere el Sistema de Facturación o Software administrativo ERP para simplificar y potenciar sus labores y hace uso de él para interactuar con la plataforma de facturación electrónica.

El Proveedor Tecnológico: Es un ente privado autorizado por la DIAN para prestar servicios relacionados con el esquema de Facturación Electrónica: construcción del XML, control de secuenciales, firmado, control de cambio normativo, procesamiento, almacenamiento y consulta. The Factory HKA Colombia es su proveedor tecnológico.

El Adquiriente: Es la persona que da origen a una transacción comercial mediante la compra de un producto o servicio, y que finalmente, opta por recibir su documento electrónico vía email.

La Autoridad de Certificación: Es un ente público o privado habilitado por el Ente Tributario para expedir certificados electrónicos conforme a la ley y a las normas asociadas. En Colombia, hay varias autoridades acreditadas para expedir certificados electrónicos para facturación electrónica, entre ellas ANDES SCD.

Ventajas de la Facturación Electrónica

El esquema de Facturación Electrónica es ventajoso porque es:

• Íntegro: Garantiza que la información contenida está protegida y no puede ser alterada.
• Auténtico: Permite verificar la identidad del emisor del documento.
• Legal: Este esquema está implementado y aceptado bajo el marco de la Ley.
• Práctico: Elimina la infraestructura para el manejo, envío y almacenamiento de soportes físicos, y permite la impresión.
• Eficiente: Se basa 100% en plataforma electrónica, lo cual hace que el manejo, envío, búsqueda y almacenamiento sea más rápido y práctico.

Proceso de la Facturación Electrónica con Validación Previa

1. El Adquiriente da origen a una transacción mediante la compra de un producto o servicio.
2. El Emisor o Contribuyente carga los datos mediante la UI (User Interface) de su ERP.
3. El Emisor o Contribuyente visualiza los timbres disponibles en la UI de su ERP.
4. El ERP construye el objeto y lo expone directamente a la plataforma HKA Factura mediante el método correspondiente del Web Service.
5. La plataforma The Factory HKA Factura:
   • Valida las credenciales de acceso del Contribuyente.
   • Valida la estructura del objeto que envía el ERP.
   • Valida el contenido del objeto que envía el ERP.
   • Asigna el CUFE (Código único de Factura Electrónica) al documento.
   • Construye el XML del documento según normativa DIAN.
   • Firma el documento con el Certificado Digital del Contribuyente.
   • Opcional: Genera una representación impresa en PDF según normativa DIAN.
   • Almacena la información en Base de Datos (Conservación).
   • Envía el XML a la DIAN para validación.
   • Espera respuesta de la DIAN con resultado de la validación.
   • Envía el XML y PDF al email proporcionado por el Adquiriente.
   • Responde a la solicitud del ERP indicando que la operación fue satisfactoria.
6. Opcionalmente, el ERP puede enviar el XML y PDF al adquiriente.
7. Opcionalmente, el ERP puede descargar el XML y PDF para propósito interno.
8. El Adquiriente recibe el XML y el PDF (vía email).
9. El Adquiriente tiene hasta 72 horas para dar Acuse de Recibo del documento, después de lo cual se considerará una aceptación tácita (este proceso aún no está definido totalmente por la DIAN).
10. El Emisor o Contribuyente visualiza el estatus del acuse de recibo del Adquiriente en la UI de su ERP.

Proceso de Facturación Electrónica con Validación Previa

@Importante: Para ambientes de desarrollo con limitaciones para consumir Web Services SOAP de manera directa, The Factory HKA Colombia pone a disposición API’s simplificando al integrador éste proceso.

Características del proceso con Validación Previa

1. En una etapa inicial, por única vez, el emisor debe registrarse y la plataforma debe ser configurada directamente desde el portal The Factory HKA Factura.
2. La plataforma opera bajo un modelo comercial de timbres o folios. Los timbres corresponden a un paquete de operaciones que el contribuyente contrata bajo un acuerdo comercial con The Factory HKA Colombia, y le da derecho a un determinado número de transacciones. El ERP puede consultar al Web Service de THE FACTORY HKA los timbres disponibles.
3. Para que el documento sea considerado factura electrónica, se requiere validación de la DIAN para su posterior envío al Adquiriente por parte de HKA Factura.
4. En caso de que el documento no sea válido exitosamente ante la DIAN, éste deberá ser corregido y reexpedido.
5. El ERP puede consumir el Web Service para descargar XML y PDF si desea un respaldo alterno u ofrecer funcionalidad de consulta offline.
6. El ERP opcionalmente puede decidir si enviar el XML y PDF al Adquiriente bajo su estructura.
7. El Web Service de la plataforma ofrece la funcionalidad de consulta de estado del Acuse de Recibo por parte del Adquiriente. Éste se actualiza de forma asincrónica.
8. El Web Service de la plataforma ofrece la funcionalidad de consulta de estado del documento por parte de la DIAN. Éste se actualiza de forma asincrónica.
9. El ERP refleja en su UI los resultados de sus consultas y operaciones con la plataforma. Sin embargo, el Emisor o Contribuyente puede hacer seguimiento o revisión a la vista de su ERP accediendo al portal The Factory HKA Factura, ya que las operaciones realizadas en el Web Service se reflejan en el portal.

Diagrama de componentes y dependencias del sistema de facturación electrónica

La Figura anterior muestra la forma en la que el Software de Facturación (ERP) se integra y hace uso de las funcionalidades de facturación electrónica de la plataforma The Factory HKA Factura, interactuando con los elementos externos (el emisor, el Adquiriente y la DIAN) mediante las dependencias disponibles, pueden verse las funciones que cada sistema debe realizar.

Seguridad de la información: recomendaciones en la implementación de la factura electrónica dentro de la red y sistemas del emisor

En este apartado se brindan recomendaciones en la implementación e integración de Factura electrónica en su organización y en la configuración de sus Sistemas y redes para mitigar riesgos de acceso indebido a datos por externos a su organización.

En General:

1. Contar con antivirus en su empresa.
2. Tener políticas y procedimientos de backup frecuentes, realizados en un período de ejecución que sea acorde con la criticidad del negocio. Para ello tener en cuenta los siguientes aspectos:
   • Deben realizarse pruebas de restauración.
   • Deben estar en una infraestructura distinta a la operativa (ante un ransomware toda la infraestructura accedida estará comprometida)
3. De ser posible, buscar asesores y especialistas en seguridad y hacer auditorias ISO 27001:2013 que evalúen la calidad de las decisiones tomadas en la implantación de factura electrónica en su empresa.
4. Evitar uso de usuarios genéricos y/o Administradores en la organización y aplicar a cada usuario el control de acceso, permisología y roles que le corresponde según su función.

Particulares con The Factory HKA Colombia SAS:

1. Sólo permitir acceso a los puertos TCP/UDP 80 y 443 a los dominios indicados a continuación :
   • *.thefactoryhka.com.co
   • emisionrest21.thefactoryhka.com.co (Integración – Producción)
   • factura21.thefactoryhka.com.co (Portal – Producción)
   • demoemisionrest21.thefactoryhka.com.co (Integración –Demo)
   • demofactura.thefactoryhka.com.co (Portal – Demo)
2. No se recomienda acceso abierto a estos puertos TCP/UDP a toda la internet.
3. En el modelo de factura electrónica con The Factory HKA Colombia SAS las peticiones surgen del cliente solamente por lo que pueden establecer reglas desde intentos de conexión externos. (La comunicación siempre será iniciada por el software cliente).
4. Si se hace uso de herramientas de software clientes de The Factory HKA Colombia SAS como lo son:
   • IntTFHKAFEL21.exe
   • AutoFact.exe

   Y los mismos se visualizan como un riesgo por el sistema de antivirus o protección del cliente, debe generarse una excepción en firewall, antivirus, y cualquier otro sistema de protección única y exclusivamente para ellos.

5. Los TOKEN Empresa y TOKEN Password de producción para la Plataforma de Facturación Electrónica de The Factory HKA Colombia SAS deben ser guardados de forma confidencial y únicamente ser accesibles por personal de confianza.
6. Para el caso en que el emisor contrate un servicio de representación gráfica con la casa de software, o desarrollador, encargado de realizar los ajustes correspondientes en el software contable o ERP para la emisión de documentos electrónicos, se deben tener en cuenta los siguientes aspectos:
   • The Factory HKA es responsable de la generación del UBL y su transmisión a la DIAN.
   • Una vez se compruebe la correcta validación y generación del UBL la casa de software puede proceder a generar una representación gráfica que debe cumplir con:

   Los elementos de ley exigidos por la DIAN: inclusión del código QR y de la cadena del CUFE ó CUDE en los documentos, según corresponda.

   Los elementos de ley exigidos por cualquier entidad supervisora al emisor de los documentos.

   Los elementos visuales y de representación de marca exigidos por el propio cliente: logos, información bancaria, leyendas referentes a las responsabilidades tributarias del emisor, etc.

   • La Casa de Software, en este escenario, asume la responsabilidad junto con el propio contribuyente de cualquier incidente de fraude por evasión, malinterpretación, error u omisión de información relevante y obligatoria por parte de la normativa.

   TFHKA no resguarda esta representación en sus sistemas y deja claro que su participación como proveedor tecnológico se limita a la generación del UBL y su validación ante la DIAN.

Web services TFHKA con validación previa

Para el consumo de los métodos del Web Service es imprescindible el uso de las credenciales de acceso, conformadas por un Token Empresa y un Token Password. También será necesario conocer los URL’s de los Web Services del ambiente de integración con validación previa. Estos elementos serán proporcionados por el equipo de Integración de The Factory HKA Colombia.

@Importante: En éste documento se hace referencia al proceso de integración con validación previa, sus controles de cambios técnicos y normativos y sus diferencias con el servicio web con validación posterior.

A continuación, se muestran los métodos que estarán disponibles en los Web Services de THE FACTORY HKA Factura para la facturación electrónica con validación previa:

Servicio	Método
Emisión Web Service TFHKA	Enviar EstadoDocumento EnvioCorreo DescargaPDF DescargaXML FoliosRestantes CargarCertificado (Uso interno) DescargarEventoXML (Nuevo) GenerarContenedor (Nuevo) GenerarEvento (Nuevo)
Adjuntos Web SOAP	CargarAdjuntos
Reportes Web SOAP (Nuevo)	DescargarReporte ProgramarReporte SolicitudReporteSincrono