Diferencia entre revisiones de «Manual de usuario API IntTfhkaFel21»

De tfhkacolwiki
Ir a la navegación Ir a la búsqueda
(Página creada con «<includeonly>=</includeonly>==Manual de usuario API IntTfhkaFel21==<includeonly>=</includeonly>…»)
 
 
(No se muestran 4 ediciones intermedias del mismo usuario)
Línea 1: Línea 1:
<includeonly>=</includeonly>==[[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa|Manual de usuario API IntTfhkaFel21]]==<includeonly>=</includeonly>
+
<includeonly>=</includeonly>== <font color="Blue"> Objetivo </font> ==<includeonly>=</includeonly>
# [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa# Objetivo|Objetivo]]
+
<br>
# [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa#Alcance|Alcance]]
+
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.
# [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #Definiciones y Términos|Definiciones y Términos]]
 
# [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #Configuración|Configuración]]
 
# [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #Funciones de la Aplicación|Funciones de la Aplicación]]
 
#      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #Funciones de la Aplicación|PARA SABER LA VERSIÓN DEL API INTTFHKAFEL21, PUEDE EJECUTAR EL SIGUIENTE COMANDO DESDE CONSOLA DEL SISTEMA]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #FoliosRestantes|FoliosRestantes]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #EstadoDocumento|EstadoDocumento]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #DescargarXml|DescargarXml]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #DescargarPDF|DescargarPDF]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #EnvioCorreo|EnvioCorreo]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #Enviar|Enviar]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #Envio de Adjuntos|Envio de Adjuntos]]
 
##      [[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #GenerarContenedor|GenerarContenedor]]
 
  
[[Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa #CATÁLOGO DE ERRORES DE RESPUESTA DEL SERVICIO WEB|CATÁLOGO DE ERRORES DE RESPUESTA DEL SERVICIO WEB]]
+
<includeonly>=</includeonly>== <font color="Blue">Alcance</font> ==<includeonly>=</includeonly>
 +
<br>
 +
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.
 +
 
 +
<includeonly>=</includeonly>== <font color="Blue">Definiciones y Términos</font>==<includeonly>=</includeonly>
 +
<br>
 +
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.
 +
 
 +
<includeonly>=</includeonly>==<font color="Blue"> Configuración</font>  ==<includeonly>=</includeonly>
 +
<br>
 +
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:
 +
 
 +
<center>'''Configuración Api IntTfhkaFel21 '''</center>
 +
[[Archivo:ConfiguracionApi.png|centro|ConfiguracionApi]]
 +
 
 +
'''''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).
 +
 
 +
<includeonly>=</includeonly>==<font color="Blue"> Funciones de la Aplicación</font> ==<includeonly>=</includeonly>
 +
<br>
 +
'''''Version:'''''
 +
 
 +
PARA SABER LA VERSION DEL API INTTFHKAFEL21, PUEDE EJECUTAR EL SIGUIENTE COMANDO DESDE CONSOLA DEL SISTEMA:
 +
 
 +
*  IntTfhkaFel.exe version (Windows)
 +
*  ./IntTfhkaFel version (Linux)
 +
 
 +
 
 +
'''<Big>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:</Big>'''
 +
 
 +
 
 +
===<u><font color="Blue"> Enviar: </font></u>===
 +
 
 +
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.<br />
 +
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)
 +
 
 +
<u><center><pre> Id|Código|Consecutivo del Documento|CUFE|Fecha Respuesta|Mensaje|Resultado|EsValidoDian|Hash|Nombre|Tipo CUFE|fechaAceptacionDIAN </pre></center></u>
 +
 
 +
'''''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.
 +
 
 +
<font color="red">'''@Importante:'''</font> 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).
 +
 
 +
===<u><font color="Blue"> FoliosRestantes:</font ></u>===
 +
 
 +
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.
 +
 
 +
<u><center><pre>Id|Código|FoliosRestantes|Mensaje|Resultado</pre></center></u>
 +
 
 +
'''''Ejemplo:'''''
 +
 
 +
01|200|9929|Se retorna folios restantes.|Procesado
 +
 
 +
 
 +
===<u><font color="Blue"> EstadoDocumento:</font> </u>===
 +
 
 +
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).
 +
 
 +
<u><pre>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</pre></u>
 +
 
 +
'''''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
 +
 
 +
 
 +
<font color="red">'''@Importante:'''</font> 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).
 +
 
 +
 
 +
===<u><font color="Blue"> DescargarXml: </font></u>===
 +
 
 +
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.
 +
 
 +
<u><center><pre>Id|Código|CUFE|Mensaje|Resultado </pre></center></u>
 +
 
 +
===<u> <font color="Blue">DescargarPDF:</font> </u>===
 +
 
 +
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.
 +
 
 +
<u><center><pre>Id|Código|CUFE|Mensaje|Resultado </pre></center></u>
 +
 
 +
'''''Ejemplo:'''''
 +
 
 +
01|200|9929|Se retorna folios restantes.|Procesado
 +
 
 +
===<u><font color="Blue"> EnvioCorreo:</font> </u>===
 +
 
 +
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.<br />
 +
String correoElectronico: Dirección de correo a donde se desea reenviar el documento.<br />
 +
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.<br />
 +
 
 +
'''''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.
 +
 
 +
<u><center><pre> Id|Código|Mensaje|Resultado </pre></center></u>
 +
 
 +
'''''Ejemplo:'''''
 +
 
 +
01|200|Se ha enviado el email de manera correcta.|Procesado
 +
 
 +
 
 +
===<u><font color="Blue"> Envio de Adjuntos: </font></u>===
 +
 
 +
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”
 +
 
 +
{| class="wikitable" style="margin: auto;"
 +
|-
 +
! style="background:#e9e9e9; text-align:center;"|N°
 +
! style="background:#e9e9e9; text-align:center;"|Nombre
 +
! style="background:#e9e9e9; text-align:center;"|Requerido
 +
! style="background:#e9e9e9; text-align:center;"|Tipo|Long|Formato
 +
! style="background:#e9e9e9; text-align:center;"|Descripción
 +
|- valign="center"
 +
| 1
 +
| Identificador
 +
| SI
 +
| N|2
 +
| Valor fijo “05”
 +
|-
 +
| 2
 +
| Parámetro Adjunto
 +
| SI
 +
| N|2
 +
| Parámetro Adjunto Ver tabla 1
 +
|-
 +
|}
 +
<br />
 +
 
 +
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:
 +
 
 +
{| class="wikitable" style="margin: auto;"
 +
|-
 +
! style="background:#e9e9e9; text-align:center;"|N°
 +
! style="background:#e9e9e9; text-align:center;"|Nombre
 +
! style="background:#e9e9e9; text-align:center;"|Requerido
 +
! style="background:#e9e9e9; text-align:center;"|Tipo|Long|Formato
 +
! style="background:#e9e9e9; text-align:center;"|Descripción
 +
|- valign="center"
 +
| 1
 +
| Identificador
 +
| SI
 +
| <nowiki>N|2</nowiki>
 +
| Valor fijo “05”
 +
|-
 +
| 2
 +
| Número de Documento
 +
| SI
 +
| <nowiki>AN|..20</nowiki>
 +
| Número de la Factura Electrónica a la cual se asocian los archivos adjuntos.
 +
|-
 +
| 3
 +
| Enviar
 +
| SI
 +
| <nowiki>N|1</nowiki>
 +
| 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
 +
| <nowiki>AN|..4</nowiki>
 +
| Extensión del archivo que se desea adjuntar. Valores aceptados: png bmp jpg pdf doc docx xls xlsx ppt pptx.
 +
|-
 +
| 5
 +
| Nombre
 +
| SI
 +
| <nowiki>AN|..50</nowiki>
 +
| Nombre del documento que se desea adjuntar (sin la extensión).
 +
|-
 +
| 6
 +
| Tipo
 +
| SI
 +
| <nowiki>N|1</nowiki>
 +
| Indicar si el documento es Representación gráfica: 2- Anexo
 +
|-
 +
| 7
 +
| Email
 +
| SI
 +
| <nowiki>Array<string></nowiki>
 +
| 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.
 +
|-
 +
|}
 +
<br />
 +
 
 +
Ejemplo para emitir documento con un archivo adjunto en diferentes archivos .txt de la información del comprobante:
 +
 
 +
<center>'''Archivo1.txt (correspondiente al documento a emitir) '''</center>
 +
[[Archivo:Archivo1txt.png|centro|Archivo1txt]]
 +
 
 +
'''''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:
 +
 
 +
<u><center><pre>01|200|VALF162|a1a3283d31e284c3d77326a5efa2e2a05a45f2c034c2d66649371bda7239d73703e42e8b1c9420bae6e1dae90cf88ab5|2019-09-17 12:42:52
 +
| Documento pendiente por Adjuntos. |Procesado|True|593b52129119d248c3b1466f5db7f8168b13c279|fv00205192210161900000162.xml|CUFE-SHA384</pre></center></u>
 +
 
 +
<font color="red">'''@Importante:'''</font> 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:
 +
 
 +
<center>'''Archivo2.txt (correspondiente al adjunto a enviar al momento de la emisión del documento fiscal)) '''</center>
 +
[[Archivo:Archivo2txt.png|centro|Archivo2txt]]
 +
 
 +
'''''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:
 +
 
 +
<u><center><pre>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
 +
</pre></center></u>
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Parámetro adjunto.
 +
! text-align:center;"|Código
 +
! text-align:center;"|Descripción
 +
|- valign="center"
 +
|-
 +
|adjuntos=0
 +
|
 +
*No se admiten adjuntos.
 +
*Se genera la representación gráfica estándar por parte de la plataforma.
 +
*Se envía el XML y la representación gráfica estándar por el canal correspondiente al Adquiriente  si el campo notificar está en “SI”.
 +
|-
 +
|adjuntos=1
 +
|
 +
*Se admiten adjuntos
 +
*El campo email es requerido y el campo notificar en “SI”.
 +
*Se genera la representación gráfica estándar por parte de la plataforma.
 +
*Se envía el XML, la representación gráfica estándar generada y los demás adjuntos por el canal correspondiente al Adquiriente.
 +
|-
 +
|adjunto=10
 +
|
 +
*No se admiten adjuntos.
 +
*No se genera la representación gráfica estándar por parte de la plataforma.
 +
*Se envía el XML sin la representación gráfica estándar, por el canal correspondiente al Adquiriente si el campo notificar está en “SI”.
 +
|-
 +
|adjuntos=11
 +
|
 +
*Se admiten adjuntos
 +
*El campo email es requerido y el campo notificar en “SI”
 +
*No se genera la representación gráfica estándar por parte de la plataforma.
 +
*Se envía el XML sin la representación gráfica estándar y los demás adjuntos por el canal correspondiente al Adquiriente. (Uno de los adjuntos puede ser la representación gráfica personalizada por el ERP).
 +
|-
 +
|}
 +
 
 +
===<u> <font color="Blue">GenerarContenedor:</font> </u>===
 +
 
 +
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.
 +
 
 +
<u><center><pre> Id|código|fechaDocumento|mensaje|resultado </pre></center></u>
 +
 
 +
'''''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'''
 +
 
 +
<includeonly>=</includeonly>== <font color="Blue">'''CATÁLOGO DE ERRORES DE RESPUESTA DEL SERVICIO WEB'''</font>==<includeonly>=</includeonly>
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método Enviar.
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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
 +
|
 +
*Ejm: El campo {nombre del campo} es obligatorio
 +
*Ejm: El campo {nombre del campo} debe ser numérico.
 +
*Ejm: El cliente No posee Folios Disponibles
 +
:(Debe enviar xml-request para su análisis) 
 +
|-
 +
|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
 +
|
 +
*La longitud del campo Token [empresa/password] no cumple con el rango permitido.
 +
*El campo Token [empresa/password] solo debe tener números y letras
 +
|-
 +
|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.
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método EstadoDocumento
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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.
 +
|-
 +
|}
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método EnvioCorreo
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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.
 +
|-
 +
|}
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método DescargaPDF
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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.
 +
|-
 +
|}
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método DescargaXML
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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.
 +
|-
 +
|}
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método GenerarContenedor
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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.
 +
|-
 +
|}
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método FoliosRestantes
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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
 +
|-
 +
|}
 +
 
 +
{| class="wikitable" "style="text-align:center;"
 +
|+ Método CargarAdjuntos
 +
! text-align:center;"|Códigos Genéricos
 +
! text-align:center;"|Resultado
 +
! text-align:center;"|Código de Respuesta
 +
! text-align:center;"|Mensaje
 +
|- valign="center"
 +
|-
 +
|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
 +
|
 +
*[Sección del Error]El campo {nombre del campo} debe tener un valor del catálogo.
 +
*[Sección del Error]El campo {nombre del campo} es requerido.
 +
*[Sección del Error]El campo {nombre del campo} debe ser un {tipo de datos} de {tamaño} {numérico/alfanumérico}.
 +
|-
 +
|}
 +
 
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
 
 +
<center>'''<big>[[Archivo:Copyright.png|100px|sinmarco|centro|Copyright]]<font color="Blue">THE FACTORY HKA COLOMBIA</font></big>
 +
<br>Copyright © 2016 The Factory HKA. Todos los derechos reservados.</center>
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<br>
 +
 
 +
 
 +
{{clear}}
 +
<!--
 +
-->

Revisión actual del 16:49 29 mar 2022

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:

Configuración Api IntTfhkaFel21
ConfiguracionApi

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:


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).

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


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”

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:

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 Email 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:

Archivo1.txt (correspondiente al documento a emitir)
Archivo1txt

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:

Archivo2.txt (correspondiente al adjunto a enviar al momento de la emisión del documento fiscal))
Archivo2txt

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
Parámetro adjunto.
Código Descripción
adjuntos=0
  • No se admiten adjuntos.
  • Se genera la representación gráfica estándar por parte de la plataforma.
  • Se envía el XML y la representación gráfica estándar por el canal correspondiente al Adquiriente si el campo notificar está en “SI”.
adjuntos=1
  • Se admiten adjuntos
  • El campo email es requerido y el campo notificar en “SI”.
  • Se genera la representación gráfica estándar por parte de la plataforma.
  • Se envía el XML, la representación gráfica estándar generada y los demás adjuntos por el canal correspondiente al Adquiriente.
adjunto=10
  • No se admiten adjuntos.
  • No se genera la representación gráfica estándar por parte de la plataforma.
  • Se envía el XML sin la representación gráfica estándar, por el canal correspondiente al Adquiriente si el campo notificar está en “SI”.
adjuntos=11
  • Se admiten adjuntos
  • El campo email es requerido y el campo notificar en “SI”
  • No se genera la representación gráfica estándar por parte de la plataforma.
  • Se envía el XML sin la representación gráfica estándar y los demás adjuntos por el canal correspondiente al Adquiriente. (Uno de los adjuntos puede ser la representación gráfica personalizada por el ERP).

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

Método Enviar.
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
  • Ejm: El campo {nombre del campo} es obligatorio
  • Ejm: El campo {nombre del campo} debe ser numérico.
  • Ejm: El cliente No posee Folios Disponibles
(Debe enviar xml-request para su análisis)
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
  • La longitud del campo Token [empresa/password] no cumple con el rango permitido.
  • El campo Token [empresa/password] solo debe tener números y letras
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.

Método EstadoDocumento
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.
Método EnvioCorreo
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.
Método DescargaPDF
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.
Método DescargaXML
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.
Método GenerarContenedor
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.
Método FoliosRestantes
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
Método CargarAdjuntos
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
  • [Sección del Error]El campo {nombre del campo} debe tener un valor del catálogo.
  • [Sección del Error]El campo {nombre del campo} es requerido.
  • [Sección del Error]El campo {nombre del campo} debe ser un {tipo de datos} de {tamaño} {numérico/alfanumérico}.





Copyright
THE FACTORY HKA COLOMBIA

Copyright © 2016 The Factory HKA. Todos los derechos reservados.