Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa
Sumario
Objetivo
El presente manual tiene como propósito dar a conocer los detalles de la interfaz de aplicación IntTfhkaFel21 para la integración directa y la descripción de las funciones para la generación de facturación electrónica ofrecida por The Factory HKA Colombia SAS.
Alcance
El presente documento abarca desde la configuración del API hasta las funciones utilizables para el consumo del Servicio Web de Integración. La librería IntTfhkaFel21 es multiplataforma, es decir, compatible con sistemas operativos Windows y Linux.
Esta librería permite consumir el servicio de integración de The Factory HKA Colombia SAS en sistemas administrativos (ERP) que nativamente tienen limitantes para el consumo de servicios web referenciando o importando el WSDL.
Definiciones y Términos
EXE: En el ámbito de la informática .exe (de la abreviación del inglés executable, que se traduce en ejecutable) es una extensión que se refiere a un archivo ejecutable de código reubicable, es decir, sus direcciones de memoria son relativas. Los sistemas operativos que utilizan de forma nativa este formato son DOS, Microsoft Windows, OS/2 y ReactOS.
Servicio Web de Integración: Servicio Web de The Factory HKA Colombia SAS puesto en disposición a propietarios de software administrativos o de gestión para la generación de factura electrónica.
Configuración
En el archivo descargado, se encontrará con las tres herramientas básicas para realizar la integración del software administrativo con nuestra plataforma de factura electrónica: librería de integración indirecta (IntTfhkaFel21), el presente manual y un archivo de texto (config.txt) que contendrá los datos de acceso a la plataforma de facturación electrónica de The Factory HKA. La estructura del archivo config.txt debe ser la siguiente:
Donde:
- 1: Corresponde a la URL para consumir el servicio de Emisión.
- 2: Corresponde a la URL para consumir el servicio de Adjuntos.
- 3: Corresponde a la URL para consumir el servicio de Reportes.
- 4: Corresponde al token empresa (suministrado por TFHKA).
- 5: Corresponde al token password (suministrado por TFHKA).
- 6: Personalización de ruta y nombre del archivo Resultado.txt (OPCIONAL)
Luego de editar el archivo config.txt de acuerdo a lo descrito anteriormente, la librería estará lista para ser utilizada desde la ventana de comandos del sistema (CMD ó BASH).
Funciones de la Aplicación
Version:
PARA SABER LA VERSION DEL API INTTFHKAFEL21, PUEDE EJECUTAR EL SIGUIENTE COMANDO DESDE CONSOLA DEL SISTEMA:
- IntTfhkaFel.exe version (Windows)
- ./IntTfhkaFel version (Linux)
En el presenta manual se describen las funcionalidades disponibles del API IntfhkaFel21 que pone a disposición del desarrollador las funciones del Servicio Web de Integración de The Factory HKA Colombia SAS, dichas funciones se listan a continuación:
FoliosRestantes:
Permite consultar la cantidad de folios. Los valores de la consulta son almacenados en el archivo Resultado.txt.
Comando:
- IntTfhkaFel21.exe FoliosRestantes (Windows)
- ./IntTfhkaFel21 FoliosRestantes (Linux)
Parámetros:Ninguno
Retorno:
- Código
- Cantidad de folios restantes
- Mensaje
- Resultado
Resultado.txt:
Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
Id|Código|FoliosRestantes|Mensaje|Resultado
Ejemplo:
01|200|9929|Se retorna folios restantes.|Procesado
EstadoDocumento:
Permite consultar el estado de un documento. Los valores de la consulta son almacenados en el archivo Resultado.txt.
Comando:
- IntTfhkaFel21.exe EstadoDocumento PRUE100 (Windows)
- ./IntTfhkaFel21 EstadoDocumento PRUE100 (Linux)
Parámetros:String numeroDocumento: Numero del documento a consultar
Retorno: Mensaje en ventana del sistema
- aceptacionFisica
- acuseComentario
- acuseEstatus
- acuseResponsable
- acuseRespuesta
- ambiente
- cadenaCufe
- código
- consecutivo
- cufe
- descripcionDocumento
- descripcionEstatusDocumento
- entregaMetodoDIAN
- esValidoDIAN
- estatusDocumento
- fechaAceptacionDIAN
- fechaDocumento
- mensaje
- mensajeDocumento
- poseeAdjuntos
- poseeRepresentacionGrafica
- resultado
- tipoCufe
- tipoDocumento
- trackID
Resultado.txt:
Campos separados por el carácter pipe “|”. El campo Id indica si la información corresponde a los datos generales sobre el estado del documento consultado (ID 01) o al historial de entregas del mismo (ID 01B).
01|aceptacionFisica|ambiente|cadenaCufe|código|consecutivo|cufe|descripcionDocumento|descripcionEstatusDocumento|entregaMetodoDIAN|esValidoDIAN|estatusDocumento| fechaDocumento|mensaje|mensajeDocumento|poseeAdjuntos|poseeRepresentacionGrafica|resultado|tipoCufe|tipoDocumento|trackID|acuseComentario|acuseEstatus| acuseResponsable|acuseRespuesta|fechaAceptacionDIAN01B|LeidoEmailIPAddress|LeidoEstatus|LeidoFecha|canalDeEntrega|email|entregaEstatus|entregaEstatusDescripcion| entregaFecha|fechaProgramada|mensajePersonalizado|nitProveedorReceptor|recepcionEmailComentario|recepcionEmailEstatus|recepcionEmailFecha|recepcionEmailIPAddress| telefono
NOTA: Se genera una línea con identificador 01B por cada email informado en el identificador 01A al momento de la emisión del documento.
Ejemplo:
01|False|2|F7PR2352020-06-0500:00:00-05:001003.0001190.57040.00030.001193.5790039012612345678unaclavetecnicacualquiera2|200|F7PR235| db2a48e3724480c071adeb455eb29f97e54814766366d80ab4a772b2648e95d90628fa5c573dd9a9be6e5dfe339b1b81|Factura de Venta Nacional| Procesado Correctamente|NoEnvioDIAN|True|0|2020-06-05 00:00:00-05:00|Se retornan datos de la Factura.|Procesado Correctamente| True|True|Exitoso|CUFE-SHA384|01|db2a48e3724480c071adeb455eb29f97e54814766366d80ab4a772b2648e95d90628fa5c573dd9a9be6e5dfe339b1b81||0||0| 2020-06-05 21:39:35-05:00
01B||||0|email1@thefactoryhka.com|0|Send|2020-06-05 12:00:00+00:00||Mensaje de Correo Electrónico entregado exitosamente.|12345789||0|||5555555
01B||||0|email2@thefactoryhka.com|0|Send|2020-06-05 12:00:00+00:00||Mensaje de Correo Electrónico entregado exitosamente.|12345789||0|||5555555
@Importante: El string del código QR al consultar el estado del documento, se almacena en el archivo string_QR.txt (en caso de que el escenario sea EXITOSO, en caso contrario se indica mensaje de Error en la ejecución del método).
DescargarXml:
Permite descargar un documento en formato XML. Los valores de la consulta son almacenados en el archivo Resultado.txt y el archivo XML es creado en la carpeta donde se ejecuta la librería.
Comando:
- IntTfhkaFel21.exe DescargarXML PRUE100 (Windows)
- ./IntTfhkaFel21 DescargarXML PRUE100 (Linux)
Parámetros: String numeroDocumento: Numero del documento a consultar
Retorno: Mensaje en ventana del sistema
- Código
- Cufe
- Mensaje
- Resultado
Resultado.txt:
Campos separados por el carácter porcentaje “%”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
Id|Código|CUFE|Mensaje|Resultado
DescargarPDF:
Permite descargar la representación gráfica de un documento. Los valores de la consulta son almacenados en el archivo Resultado.txt y el archivo PDF es creado en la carpeta donde se ejecuta la librería.
Comando:
- IntTfhkaFel21.exe DescargarPDF PRUE100 (Windows)
- ./IntTfhkaFel21 DescargarPDF PRUE100 (Linux)
Parámetros: String numeroDocumento: Numero del documento a consultar
Retorno: Mensaje en ventana del sistema
- Código
- Cufe
- Mensaje
- Resultado
Resultado.txt:
Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
Id|Código|CUFE|Mensaje|Resultado
Ejemplo:
01|200|9929|Se retorna folios restantes.|Procesado
EnvioCorreo:
Permite reenviar el correo que se emite cuando se genera un documento. Si se indica un correo, entonces reenvía el XML y la Representación Gráfica a dicha dirección. En caso de que se desee reenviar un documento previamente emitido con adjuntos (parámetro adjuntos del método Enviar en ‘1’ u ‘11’ al momento de la emisión de dicho documento), se debe indicar el parámetro de adjuntos del método en ‘1’, el envío de éste es opcional. La respuesta se almacena en Resultado.txt.
Comando:
- IntTfhkaFel21.exe EnvioCorreo PRUE100,email@dominio.com (Windows)
- ./IntTfhkaFel21 EnvioCorreo PRUE100,email@dominio.com (Linux)
Parámetros:
String numeroDocumento: Numero del documento.
String correoElectronico: Dirección de correo a donde se desea reenviar el documento.
String adjuntos:
0 -> No reenviar los adjuntos anexos en la emisión del documento.
1 -> Reenvía los adjuntos anexos en la emisión del documento.
Retorno: Mensaje en ventana del sistema, donde se detalla:
- Código
- Mensaje
- Resultado
Resultado.txt:
Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
Id|Código|Mensaje|Resultado
Ejemplo:
01|200|Se ha enviado el email de manera correcta.|Procesado
Enviar:
Función utilizada para la creación del documento electrónico (factura, nota de crédito o débito). La respuesta del servicio se almacena en Resultado.txt.
Comando:
- IntTfhkaFel21.exe Enviar Factura.txt)
- ./IntTfhkaFel21 Enviar Factura.txt
Parámetros:
String rutaArchivo: Nombre o ruta de acceso al documento de texto que contiene los datos de la factura, nota de crédito o débito de acuerdo a la estructura descrita en el Val. Previa - Layout Archivo Plano (TXT) - Emisión.
Retorno: Mensaje en ventana del sistema
- Código
- Consecutivo del Documento
- CUFE
- Fecha Respuesta
- Fecha Aceptacion DIAN
- Mensaje
- Resultado
- EsValidoDian
- Hash
- Nombre
- Tipo CUFE
Resultado.txt:
Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
La respuesta del método Enviar adicional al identificador 01 contiene, identificadores adicionales, los cuales son:
- 01A -> mensajesValidacion: Validaciones TFHKA + XSLT DIAN (Demo y Producción)
- 01B -> reglasNotificacionDIAN: Notificaciones DIAN (Producción)
- 01C -> reglasValidacionDIAN: Rechazos DIAN (Producción)
Id|Código|Consecutivo del Documento|CUFE|Fecha Respuesta|Mensaje|Resultado|EsValidoDian|Hash|Nombre|Tipo CUFE|fechaAceptacionDIAN
Ejemplo:
Exitoso: 01|200|F7PR253|67e4be70066fad97dc79cd2996d857f464775de10579b2ea990a9803c71156623fa52ee5bf24c4a33a293aeacd3f4fde|2020-06-08 13:11:35-05:00|El documento se envió correctamente.|Procesado|True|7bdce37568845f5c64c5826fb572503931f37217|fv09003901260162000000253.xml|CUFE-SHA384|2020-06-08 23:11:34-05:00
Con Error: 01|109|||2019-09-15 01:59:04|El documento no superó las validaciones.||False|||| 01A|El campo obligaciones debe tener un valor del catálogo.
@Importante: El string del código QR al consultar el estado del documento, se almacena en el archivo string_QR.txt (en caso de que el escenario sea EXITOSO, en caso contrario se indica mensaje de Error en la ejecución del método).
Envio de Adjuntos:
Para esta funcionalidad, se envía el archivo adjunto en un archivo .txt distinto a donde se carga la información del documento electrónico, se debe seguir la siguiente estructura en la emisión del documento, teniendo en cuenta que el documento emitido queda pendiente por adjuntos al enviar el Parámetro Adjuntos en “1” u “11”
N° | Nombre | Requerido | Tipo|Long|Formato | Descripción |
---|---|---|---|---|
1 | Identificador | SI | 2 | Valor fijo “05” |
2 | Parámetro Adjunto | SI | 2 | Parámetro Adjunto Ver tabla 1 |
Luego de esto se procedería a consumir nuevamente el método Enviar, pero consumiendo un archivo .txt solo con la siguiente estructura, la cual se puede repetir tantas veces como archivos adjuntos se necesiten enviar:
N° | Nombre | Requerido | Tipo|Long|Formato | Descripción |
---|---|---|---|---|
1 | Identificador | SI | N|2 | Valor fijo “05” |
2 | Número de Documento | SI | AN|..20 | Número de la Factura Electrónica a la cual se asocian los archivos adjuntos. |
3 | Enviar | SI | N|1 | Indica si envía el correo:
0- No se envía (queda a la espera de más adjuntos) 1- Se envía el documento con los adjuntos asociados hasta el momento |
4 | Formato | SI | AN|..4 | Extensión del archivo que se desea adjuntar. Valores aceptados: png bmp jpg pdf doc docx xls xlsx ppt pptx. |
5 | Nombre | SI | AN|..50 | Nombre del documento que se desea adjuntar (sin la extensión). |
6 | Tipo | SI | N|1 | Indicar si el documento es Representación gráfica: 2- Anexo |
7 | SI | Array<string> | Indica los correos a los cuales se desea realizar la entrega. (Pueden enviarse máximo 5 correos separados por coma “,”). | |
8 | Ruta del Archivo | SI | - | Ruta del archivo que desea enviar como adjunto. |
Ejemplo para emitir documento con un archivo adjunto en diferentes archivos .txt de la información del comprobante:
Resultado.txt:
Campos separados por el carácter pipe “|” y cada respuesta por archivo adjunto separados por un salto de línea. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio, por ejemplo:
01|200|VALF162|a1a3283d31e284c3d77326a5efa2e2a05a45f2c034c2d66649371bda7239d73703e42e8b1c9420bae6e1dae90cf88ab5|2019-09-17 12:42:52 | Documento pendiente por Adjuntos. |Procesado|True|593b52129119d248c3b1466f5db7f8168b13c279|fv00205192210161900000162.xml|CUFE-SHA384
@Importante: El string del código QR al consultar el estado del documento, se almacena en el archivo string_QR.txt (en caso de que el escenario sea EXITOSO, en caso contrario se indica mensaje de Error en la ejecución del método).
Luego, se vuelve a consumir el método Enviar con un archivo .txt configurado de la siguiente manera:
Resultado.txt:
Campos separados por el carácter pipe “|” y cada respuesta por archivo adjunto separados por un salto de línea. El campo Id hace referencia a que el servicio consumido fue el de Adjuntos (02), los demás campos son propios de la respuesta de servicio, por ejemplo:
02|200|Archivo cargado satisfactoriamente. No se considera la información especificada en el atributo email ya que se indicó que no se desea enviar correo alguno|Procesado - Con Advertencia 02|200|Archivo cargado satisfactoriamente|Procesado
Código | Descripción |
---|---|
adjuntos=0 |
|
adjuntos=1 |
|
adjunto=10 |
|
adjuntos=11 |
|
GenerarContenedor:
Un contendor es un tipo de documento AttachedDocument, cuya estructura tiene por objetivo contener y transmitir en un único archivo XML un documento electrónico (Invoice, CreditNote ó DebitNote) y todos los eventos (ApplicationResponse) generados hasta la fecha. Este método genera un archivo con el nombre: AttachedDocument_NumeroConsecutivo.
Comando:
- IntTfhkaFel21.exe GenerarContenedor PRUE100 (Windows)
- ./IntTfhkaFel21 GenerarContenedor PRUE100 (Linux)
Parámetros:
String numeroDocumento: Numero del documento al cual se le generará el contenedor.
Retorno: Mensaje en ventana del sistema
- Código
- Fecha
- Mensaje
- Resultado
Resultado.txt:
Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
Id|código|fechaDocumento|mensaje|resultado
Ejemplo:
Exitoso: 01|200|2020-01-22 10:04:36-05:00|Documento Generado con éxito|Procesado
Nota:Las funciones descritas anteriormente fueron puestas a prueba bajo los siguientes Sistemas Operativos:
- Windows 7 - 64bits
- Windows 10 - 64bits
- Windows XP - 32bits
- Linux CentOS 6.9 (Final) - 32bits
- Linux CentOS 7.5.1804 (Core) - 64bits
- Linux Kali 2016.1 – 32bits
- Ubuntu 18.04 LTS – 64bits
Bajo entorno Linux – 32 bits, esta librería es compatible para GCC 4.4.7 o superior
Bajo entorno Linux – 64 bits, esta librería es compatible para GCC 4.8.5 o superior
CATÁLOGO DE ERRORES DE RESPUESTA DEL SERVICIO WEB
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Envío Satisfactorio | Procesado | 200 | El documento se envió correctamente (Síncrono). |
Envío Satisfactorio | Procesado | 201 | Documento recibido, se enviará más tarde a la DIAN (Asíncrono). |
Envío Satisfactorio | Procesado | 208 | Documento de contingencia recibido, se enviará más tarde a la DIAN (Asíncrono). |
Error por Excepciones generales | Error | 103 | Error de Procesamiento (Debe enviar xml-request para su análisis) |
Error en capa de Validaciones TFHKA | Error | 109 |
|
Error por Excepciones XSLT Local (TFHKA) | Error | 161 | Debe validarse el XML/UBL generado (Debe enviar xml-request para su análisis) |
Error en Validaciones XSLT Local (TFHKA) | Error | 110 | Ejm: Fatal: [FAR08]- (R) Total de la factura 100.00 diferente de la suma de Total valor bruto + Total Tributos - Anticipos (+/-) Redondeos : 120.00 } (Debe enviar xml-request para su análisis) |
Error Factura ya emitida o se encuentra en TFHKA y DIAN | Error | 114 | Documento emitido previamente (Debe consultar el EstadoDocumento) |
Documento rechazo por la DIAN | Error | 99 | Documento fue rechazado por la DIAN (Debe validarse los motivos de rechazo o reglasValidacionDIAN) |
Envío de Datos | Error | 111 |
|
Token invalido | Error | 101 | El Token del Emisor es inválido. (Debe validarse el ambiente al que corresponden los tokens utilizados y URL’s de conexión) |
Error al parsear el documento | Error | 112 | Error al extraer la información del documento al comprobante.(Debe enviar xml-request para su análisis) |
Error validaciones incorrectas en los rangos | Error | 117 | Error. El rango, fecha de la factura o fecha de autorización son inválidos. / Error el número de documento es inválido.(Debe validarse configuraciones del secuencial en el portal y ERP) |
Error validación de autorización en los rangos | Error | 118 | Error, el número de autorización o el tipo de documento es inválido. / Error el número de documento es inválido.
(Debe validarse configuraciones del secuencial en el portal y ERP) |
Error validación de Folios | Error | 119 | No posee folios disponibles.Se debe contactar al nuestro equipo de facturación para adquirir un paquete de transacciones o folios. |
Error validación en rango | Error | 150 | No existe el rango de numeración.(Debe validarse el tipo de documento y si el rango está configurado en el portal) |
@IMPORTANTE:Ante un código de error diferente a los anteriores por favor enviar el request soap-Envelope del documento al alias integracion_fel_co@thefactoryhka.com exponiendo el caso.
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Se retornan datos de la factura |
Token Invalido | Error | 101 | El Token del Emisor es inválido. |
Error en Validaciones | Error | 102 | Número de documento inválido, no existe. |
Error de Ejecución | Error | 103 | Ha ocurrido un error en la ejecución del servicio, por favor intente más tarde. |
Error al Extraer Datos | Error | 105 | Error al extraer los datos del documento. |
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Se ha enviado el email de manera correcta |
Token Invalido | Error | 101 | El Token del Emisor es inválido. |
Error en Validaciones | Error | 102 | Número de documento inválido, no existe. |
Error de Ejecución | Error | 103 | Ha ocurrido un error en la ejecución del servicio, por favor intente más tarde. |
Correo inválido | Error | 106 | Formato de correo electrónico inválido. |
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Se retorna el archivo solicitado |
Token Invalido | Error | 101 | El Token del Emisor es inválido. |
Error en Validaciones | Error | 102 | Número de documento inválido, no existe. |
Error de Ejecución | Error | 103 | Ha ocurrido un error en la ejecución del servicio, por favor intente más tarde. |
Error al Extraer Datos | Error | 105 | Error, no se pudo obtener el archivo solicitado. |
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Se retorna el archivo solicitado |
Token Invalido | Error | 101 | El Token del Emisor es inválido. |
Error en Validaciones | Error | 102 | Número de documento inválido, no existe. |
Error de Ejecución | Error | 103 | Ha ocurrido un error en la ejecución del servicio, por favor intente más tarde. |
Error al Extraer Datos | Error | 105 | Error, no se pudo obtener el archivo solicitado. |
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Se retorna el archivo solicitado |
Token Invalido | Error | 101 | El Token del Emisor es inválido. |
Error en Validaciones | Error | 102 | Número de documento inválido, no existe. |
Error de Ejecución | Error | 103 | Ha ocurrido un error en la ejecución del servicio, por favor intente más tarde. |
Error al Extraer Datos | Error | 105 | Error, no se pudo obtener el archivo solicitado. |
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Se retorna el archivo solicitado |
Token Invalido | Error | 101 | El Token del Emisor es inválido. |
Error en Validaciones | Error | 102 | Número de documento inválido, no existe. |
Error de Ejecución | Error | 103 |
Códigos Genéricos | Resultado | Código de Respuesta | Mensaje |
---|---|---|---|
Respuesta Satisfactoria | Procesado | 200 | Archivo {nombreDelArchivo}{extension} almacenado exitosamente |
Error en carga de archivo | Error | 107 | Se señaló previamente que para el documento {consecutivo} emitido por {NIT Emisor} ya se habían completado los adjuntos esperados (Quiere decir que ya la propiedad enviar fuen setada en “1” anteriormente) |
Error en Validaciones | Error | 109 |
|