Diferencia entre revisiones de «Manual de usuario API IntTfhkaFel21»
(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>== | + | <includeonly>=</includeonly>== <font color="Blue"> Objetivo </font> ==<includeonly>=</includeonly> |
− | + | <br> | |
− | + | 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. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | [[ | + | <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
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:
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”
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 |
|
Copyright © 2016 The Factory HKA. Todos los derechos reservados.