Manual de usuario API IntTfhkaFel21 - Indice Manual Integración Directa

De tfhkacolwiki
Ir a la navegación Ir a la búsqueda

API IntTfhkaFel21

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 librería

Versión:

PARA SABER LA VERSIÓN DEL API INTTFHKAFEL21, PUEDE EJECUTAR EL SIGUIENTE COMANDO DESDE CONSOLA DEL SISTEMA:

  • IntTfhkaFel.exe version (Windows)
  • ./IntTfhkaFel version (Linux)

En el presenta manual se describen las funcionalidades disponibles del API IntfhkaFel21 que pone a disposición del desarrollador las funciones del Servicio Web de Integración de The Factory HKA Colombia SAS, dichas funciones se listan a continuación:


FoliosRestantes:

Permite consultar la cantidad de folios. Los valores de la consulta son almacenados en el archivo Resultado.txt.

Comando:

  • IntTfhkaFel21.exe FoliosRestantes (Windows)
  • ./IntTfhkaFel21 FoliosRestantes (Linux)

Parámetros:Ninguno

Retorno:

  • Código
  • Cantidad de folios restantes
  • Mensaje
  • Resultado

Resultado.txt:

Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio. 

Id|Código|FoliosRestantes|Mensaje|Resultado

Ejemplo:

01|200|9929|Se retorna folios restantes.|Procesado


EstadoDocumento:

Permite consultar el estado de un documento. Los valores de la consulta son almacenados en el archivo Resultado.txt.

Comando:

  • IntTfhkaFel21.exe EstadoDocumento PRUE100 (Windows)
  • ./IntTfhkaFel21 EstadoDocumento PRUE100 (Linux)

Parámetros:String numeroDocumento: Numero del documento a consultar

Retorno: Mensaje en ventana del sistema

  • aceptacionFisica
  • acuseComentario
  • acuseEstatus
  • acuseResponsable
  • acuseRespuesta
  • ambiente
  • cadenaCufe
  • código
  • consecutivo
  • cufe
  • descripcionDocumento
  • descripcionEstatusDocumento
  • entregaMetodoDIAN
  • esValidoDIAN
  • estatusDocumento
  • fechaAceptacionDIAN
  • fechaDocumento
  • mensaje
  • mensajeDocumento
  • poseeAdjuntos
  • poseeRepresentacionGrafica
  • resultado
  • tipoCufe
  • tipoDocumento
  • trackID

Resultado.txt:

Campos separados por el carácter pipe “|”. El campo Id indica si la información corresponde a los datos generales sobre el estado del documento consultado (ID 01) o al historial de entregas del mismo (ID 01B). 

01|aceptacionFisica|ambiente|cadenaCufe|código|consecutivo|cufe|descripcionDocumento|descripcionEstatusDocumento|entregaMetodoDIAN|esValidoDIAN|estatusDocumento|fechaDocumento|mensaje
|mensajeDocumento|poseeAdjuntos|poseeRepresentacionGrafica|resultado|tipoCufe|tipoDocumento|trackID|acuseComentario|acuseEstatus|acuseResponsable|acuseRespuesta|fechaAceptacionDIAN01B
|LeidoEmailIPAddress|LeidoEstatus|LeidoFecha|canalDeEntrega|email|entregaEstatus|entregaEstatusDescripcion|entregaFecha|fechaProgramada|mensajePersonalizado|nitProveedorReceptor
|recepcionEmailComentario|recepcionEmailEstatus|recepcionEmailFecha|recepcionEmailIPAddress|telefono

NOTA: Se genera una línea con identificador 01B por cada email informado en el identificador 01A al momento de la emisión del documento.

Ejemplo:

01|False|2|F7PR2352020-06-0500:00:00-05:001003.0001190.57040.00030.001193.5790039012612345678unaclavetecnicacualquiera2|200|F7PR235|db2a48e3724480c071adeb455eb29f97e54814766366d80ab4a772b2648e95d90628fa5c573dd9a9be6e5dfe339b1b81|Factura de Venta Nacional|Procesado Correctamente|NoEnvioDIAN|True|0|2020-06-05 00:00:00-05:00|Se retornan datos de la Factura.|Procesado Correctamente|True|True|Exitoso|CUFE-SHA384|01|db2a48e3724480c071adeb455eb29f97e54814766366d80ab4a772b2648e95d90628fa5c573dd9a9be6e5dfe339b1b81||0||0|2020-06-05 21:39:35-05:00 01B||||0|email1@thefactoryhka.com|0|Send|2020-06-05 12:00:00+00:00||Mensaje de Correo Electrónico entregado exitosamente.|12345789||0|||5555555 01B||||0|email2@thefactoryhka.com|0|Send|2020-06-05 12:00:00+00:00||Mensaje de Correo Electrónico entregado exitosamente.|12345789||0|||5555555


@Importante: El string del código QR al consultar el estado del documento, se almacena en el archivo string_QR.txt (en caso de que el escenario sea EXITOSO, en caso contrario se indica mensaje de Error en la ejecución del método).


DescargarXml:

Permite descargar un documento en formato XML. Los valores de la consulta son almacenados en el archivo Resultado.txt y el archivo XML es creado en la carpeta donde se ejecuta la librería.

Comando:

  • IntTfhkaFel21.exe DescargarXML PRUE100 (Windows)
  • ./IntTfhkaFel21 DescargarXML PRUE100 (Linux)

Parámetros: String numeroDocumento: Numero del documento a consultar

Retorno: Mensaje en ventana del sistema

  • Código
  • Cufe
  • Mensaje
  • Resultado

Resultado.txt:

Campos separados por el carácter porcentaje “%”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio. 

Id|Código|CUFE|Mensaje|Resultado


DescargarPDF:

Permite descargar la representación gráfica de un documento. Los valores de la consulta son almacenados en el archivo Resultado.txt y el archivo PDF es creado en la carpeta donde se ejecuta la librería.

Comando:

  • IntTfhkaFel21.exe DescargarPDF PRUE100 (Windows)
  • ./IntTfhkaFel21 DescargarPDF PRUE100 (Linux)

Parámetros: String numeroDocumento: Numero del documento a consultar

Retorno: Mensaje en ventana del sistema

  • Código
  • Cufe
  • Mensaje
  • Resultado

Resultado.txt:

Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio. 

Id|Código|CUFE|Mensaje|Resultado

Ejemplo:

01|200|9929|Se retorna folios restantes.|Procesado


EnvioCorreo:

Permite reenviar el correo que se emite cuando se genera un documento. Si se indica un correo, entonces reenvía el XML y la Representación Gráfica a dicha dirección. En caso de que se desee reenviar un documento previamente emitido con adjuntos (parámetro adjuntos del método Enviar en ‘1’ u ‘11’ al momento de la emisión de dicho documento), se debe indicar el parámetro de adjuntos del método en ‘1’, el envío de éste es opcional. La respuesta se almacena en Resultado.txt.

Comando:

  • IntTfhkaFel21.exe EnvioCorreo PRUE100,email@dominio.com (Windows)
  • ./IntTfhkaFel21 EnvioCorreo PRUE100,email@dominio.com (Linux)

Parámetros:

String numeroDocumento: Numero del documento.
String correoElectronico: Dirección de correo a donde se desea reenviar el documento.
String adjuntos: 0 -> No reenviar los adjuntos anexos en la emisión del documento. 1 -> Reenvía los adjuntos anexos en la emisión del documento.

Retorno: Mensaje en ventana del sistema, donde se detalla:

  • Código
  • Mensaje
  • Resultado

Resultado.txt:

Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio. 

 Id|Código|Mensaje|Resultado

Ejemplo:

01|200|Se ha enviado el email de manera correcta.|Procesado


Enviar:

Función utilizada para la creación del documento electrónico (factura, nota de crédito o débito). La respuesta del servicio se almacena en Resultado.txt.

Comando:

  • IntTfhkaFel21.exe Enviar Factura.txt)
  • ./IntTfhkaFel21 Enviar Factura.txt

Parámetros:

String rutaArchivo: Nombre o ruta de acceso al documento de texto que contiene los datos de la factura, nota de crédito o débito de acuerdo a la estructura descrita en el Val. Previa - Layout Archivo Plano (TXT) - Emisión.

Retorno: Mensaje en ventana del sistema

  • Código
  • Consecutivo del Documento
  • CUFE
  • Fecha Respuesta
  • Fecha Aceptacion DIAN
  • Mensaje
  • Resultado
  • EsValidoDian
  • Hash
  • Nombre
  • Tipo CUFE

Resultado.txt:

Campos separados por el carácter pipe “|”. El campo Id hace referencia a que el servicio consumido fue el de Emisión (01), los demás campos son propios de la respuesta de servicio.
La respuesta del método Enviar adicional al identificador 01 contiene, identificadores adicionales, los cuales son:

  • 01A -> mensajesValidacion: Validaciones TFHKA + XSLT DIAN (Demo y Producción)
  • 01B -> reglasNotificacionDIAN: Notificaciones DIAN (Producción)
  • 01C -> reglasValidacionDIAN: Rechazos DIAN (Producción)
 Id|Código|Consecutivo del Documento|CUFE|Fecha Respuesta|Mensaje|Resultado|EsValidoDian|Hash|Nombre|Tipo CUFE|fechaAceptacionDIAN

Ejemplo:

Exitoso: 01|200|F7PR253|67e4be70066fad97dc79cd2996d857f464775de10579b2ea990a9803c71156623fa52ee5bf24c4a33a293aeacd3f4fde|2020-06-08 13:11:35-05:00|El documento se envió correctamente.|Procesado|True|7bdce37568845f5c64c5826fb572503931f37217|fv09003901260162000000253.xml|CUFE-SHA384|2020-06-08 23:11:34-05:00

Con Error: 01|109|||2019-09-15 01:59:04|El documento no superó las validaciones.||False|||| 01A|El campo obligaciones debe tener un valor del catálogo.

@Importante: El string del código QR al consultar el estado del documento, se almacena en el archivo string_QR.txt (en caso de que el escenario sea EXITOSO, en caso contrario se indica mensaje de Error en la ejecución del método).

Obtenido de «http://felcowiki.thefactoryhka.com.co/index.php?title=Manual_de_usuario_API_IntTfhkaFel21_-_Indice_Manual_Integración_Directa&oldid=1581»