meta data de esta página
Ejemplo en lenguaje CSharp
Tiene como objetivo ejemplificar el proceso de conexión, acceso y uso de las propiedades y métodos ofrecidos por el Servicio Web de Integración de TFHKA a través del lenguaje de programación C Sharp (C#) de la plataforma .Net. /
Independientemente del tipo de proyecto C# con el cual se trabaje: Consola, Winforms o WPF, lo más importante es establecer los pasos necesarios para realizar una integración exitosa.
Criterios a tomar en cuenta:
- Establecer una referencia al Servicio Web de Integración de TFHKA
- Instanciar el objeto a través del cual se tendrá acceso a los métodos del Servicio Web de TFHKA.
- Construir / Armar el objeto Documento Electrónico (Factura) que se desea enviar al Servicio Web de Integración de TFHKA, a través de los objetos respectivos.
- Enviar el documento al Servicio Web de Integración de TFHKA para su procesamiento.
- Recibir y procesar la respuesta del Servicio Web de TFHKA en nuestro proyecto, según sea requerido.
Pasos para realizar la integración:
PASO 1: Agregar una nueva Referencia de Servicio en su proyecto, utilizando la URL del Servicio Web de Integración de TFHKA referida en este documento.
PASO 2: Crear una instancia del objeto 'ServiceCliente' del Servicio Wed de Integración de TFHKA, previamente referenciado.
PASO 3: Construir el Documento Electrónico a enviar, en base a los objetos provistos por el Servicio Web de Integración de TFHKA.
PASO 4: Enviar el Documento Electrónico construído en el paso anterior al Servicio Web de Integración de TFHKA, utilizando los Tokens de Empresa y Password indicados en este documento.
(el Servicio Web procesará su solicitud según las especificaciones de la DGI y retornará de inmediato los resultados).
PASO 5: Recibir y procesar la respuesta del Servicio Web de Integración de TFHKA.
IMPORTANTE: El Documento procesado será almacenado en la NUBE para que pueda ser consultado en cualquier momento según sea requerido.
Para mayor información y detalles sobre el proceso, puede consultar el Manual de Integración de TFHKA
PASO 1: Agregar referencia de servicio con la URL del servicio web de integración de TFHKA
Incluir lo siguiente:
using System;
using EjemploIntegraciondirectaCSharp.TfhkaPaWebService;
namespace EjemploIntegraciondirectaCSharp
{
class DemoIntCSharpTfhka
{
- En el Explorador de Soluciones de VisualStudio, haga click con el botón derecho del mouse sobre el nombre de su Proyecto.
- Seleccione la opción “Agregar → Referencia de servicio… ”.
- En la ventana desplegada, ingrese la siguiente URL en el campo 'Dirección:'.
URL del Servicio Web de Integración de TFHKA: https://demoemision.thefactoryhka.com.pa/ws/obj/v1.0/Service.svc
- Haga click sobre el botón “Ir” y espere a que descargue la información del Servicio Web
- Coloque la siguiente identificación en el campo “Espacio de nombres:”.
Identificación de la Referencia: “TfhkaPaWebService”
(Dicho nombre es referencial, pero no obligatorio. El nombre de identificación utilizado debe ser incluido en la sección de Usos de este archivo)
IMPORTANTE: Para que el ejemplo funcione correctamente es necesario agregar la Referencia Web a través de la opción “Agregar Referencia de servicio…”, lo cual generará el archivo “Reference.cs” donde se crearán las clases y objetos requeridos por el 'Data Contract' del SOAP Service.
TOKENS requeridos por el Servicio Web de Integración de TFHKA para enviar documentos electrónicos, así como para utilizar otros métodos disponibles
public const string tokenEmpresa = ""; /// Token empresa suministrado por el personal de soporte de TFHKA
public const string tokenPassword = ""; /// Token empresa suministrado por el personal de soporte de TFHKA
static void Main(string[] args)
{
try
{
PASO 2: Crear una instancia del objeto 'ServiceClient' del servicio web de integración de TFHKA
A traves de esta instancia tendremos acceso a los métodos públicos disponibles
(En este ejemplo, sólo utilizaremos el método 'Enviar'; puede observar todos los métodos disponibles a través del Examinador de objetos de VisualStudio)
ServiceClient webService = new ServiceClient();
Consola.mensaje("\r\n - EJEMPLO DE INTEGRACIÓN DIRECTA C# TFHKA - \r\n", 1, 0, 0);
String numero = "";
while (numero == "")
{
Consola.mensaje(" Introduzca el Número de Documento Electrónico a enviar:\r\n", 0, 2, 0);
numero = Console.ReadLine();
}
PASO 3: Construir el documento electrónico a enviar al servicio web de integración de TFHKA
Para mayor información y detalles sobre el proceso, puede consultar el Manual de Integración de TFHKA
En este ejemplo utilizaremos Clases, Atributos y Métodos creados con la finalidad de organizar mejor la estructura del archivo y del cuerpo de código fuente en general.
Sin embargo, esta estructura no es obligatoria. El desarrollador puede utilizar su propio estilo, siempre y cuando logre acceder y establecer los valores requeridos para los diferentes objetos que sub-componen al objeto DocumentoElectrónico.
DocumentoElectronico documento = Factura.armarFactura(numero);
PASO 4: Enviar el documento electrónico construido en el paso 3 al servicio web de integración de TFHKA
Se requiere crear un objeto de tipo EnviarResponse en el cual será utilizado para almacenar la respuesta del Servicio Web
Se utiliza el método Enviar provisto por el Servicio Web, incluyendo como parámetros los tokens de empresa y password referidos anteriormente, así como el documento construido en paso 2
EnviarResponse respuestaWebService = new EnviarResponse();
Consola.mensaje("\r\n Enviando el Documento...", 2, 0, 0);
respuestaWebService = webService.Enviar(tokenEmpresa, tokenPassword, documento);
PASO 5: Recibir y procesar la respuesta del servicio web de integración de TFHKA
La respuesta del Servicio Web de TFHKA será enviada inmediatamente.
En este ejemplo, la respuesta del Servicio Web se muestra a través de la consola.
En caso de recibir una respuesta positiva para el envío del Documento Electrónico (código 200), los detalles serán mostrados a través de la página de Consulta de Facturas por Qr en su navegador de Internet.
La respuesta del Servicio Web de TFHKA incluye: código de la respuesta, resultado, mensaje, cufe y Qr, entre otros. (ver el Examinador de Objetos de VisualStudio)
Consola.mensaje("\r\n RESPUESTA: " + respuestaWebService.codigo + ". " + respuestaWebService.resultado + ". " + respuestaWebService.mensaje, 0, 0, 0);
if (respuestaWebService.codigo == "200")
{
Consola.mensaje("\r\n Ahora, podrá observar el documento enviado en su navegador de internet.\r\n Presione cualquier tecla para mostrar la Consulta de Facturas por Qr y Finalizar.", 3, 0, 1);
System.Diagnostics.Process.Start(respuestaWebService.qr);
}
else {
Consola.mensaje("\r\n Presione cualquier tecla para Finalizar...", 0, 0, 1);
}
}
catch (Exception ex)
{
Consola.mensaje("\r\n Se ha producido un error..." + "\r\n " + ex.Message + "\r\n Presione cualquier tecla para Finalizar...", 0,0,1);
}
}
}
Clases para armar el documento electrónico y elementos componentes, en base a los objetos provistos por el servicio web
La definición de estas clases no es obligatoria ni requerida, pero sirven para ordenar la estructura de este documento y mostrar paso a paso la incorporación de los diferentes objetos que componen el objeto Documento Electrónico.
public class Factura
{
public static DocumentoElectronico factura = new DocumentoElectronico();
public static DocumentoElectronico armarFactura(string numero)
{
Consola.mensaje("\r\n Armando el Documento Electrónico:", 3, 0, 0);
//DATOS REFERENCIALES CON FINES DE PRUEBA
//Consultar Manual de Integracion TFHKA para ver detalles precisos
factura.codigoSucursalEmisor = "0000";
factura.tipoSucursal = "1";
// Datos de la Transacción
DatosFactura datos = new DatosFactura();
datosTransaccion datosFactura = datos.crearDatosFactura(numero);
factura.datosTransaccion = datosFactura;
Consola.mensaje("\r\n - Añadidos Datos de la Transacción...", 5, 0, 0);
// Datos de los Productos / Items
factura.listaItems = new listaItems();
factura.listaItems.Add(Producto.crearItem());
Consola.mensaje("\r\n - Añadidos los Items / Productos...", 5, 0, 0);
// Datos de los Totales y Sub-Totales
factura.totalesSubTotales = Totales.generarTotales();
Consola.mensaje("\r\n - Añadidos los Totales y Sub-Totales...", 5, 0, 0);
Consola.mensaje("\r\n Documento Listo !!! ...", 4, 0, 0);
return factura;
}
}
public class Cliente
{
public static cliente cliente = new cliente();
public static cliente crearCliente()
{
//DATOS REFERENCIALES CON FINES DE PRUEBA
//Consultar Manual de Integracion TFHKA para ver detalles precisos
cliente.tipoClienteFE = "01";
cliente.tipoContribuyente = "2";
cliente.numeroRUC = "155596713-2-2015";
cliente.digitoVerificadorRUC = "59";
cliente.razonSocial = "FE general";
cliente.direccion = "Av. Balboa";
cliente.codigoUbicacion = "1-2-3";
cliente.corregimiento = "Guabito";
cliente.distrito = "Changuinola";
cliente.provincia = "Bocas del Toro";
cliente.telefono1 = "997-8243";
cliente.telefono2 = "";
cliente.telefono3 = "";
cliente.correoElectronico1 = "fep@gmail.com";
cliente.pais = "PA";
cliente.paisOtro = "";
return cliente;
}
}
public class DatosFactura
{
public static datosTransaccion datosFactura = new datosTransaccion();
public datosTransaccion crearDatosFactura(string num)
{
//DATOS REFERENCIALES CON FINES DE PRUEBA
//Consultar Manual de Integracion TFHKA para ver detalles precisos
datosFactura.tipoEmision = "01";
datosFactura.tipoDocumento = "01";
datosFactura.numeroDocumentoFiscal = num;
datosFactura.puntoFacturacionFiscal = "001";
//Debe establecerse el formato solicitado para la fecha de emisión "yyyy-MM-ddTHH:mm:ss-05:00"
var fechaEmision = Convert.ToDateTime(DateTime.Today.ToString("dd-MM-yyyy")).ToString("yyyy-MM-ddTHH:mm:ss-05:00");
datosFactura.fechaEmision = fechaEmision;
datosFactura.naturalezaOperacion = "01";
datosFactura.tipoOperacion = "1";
datosFactura.destinoOperacion = "1";
datosFactura.formatoCAFE = "1";
datosFactura.entregaCAFE = "1";
datosFactura.envioContenedor = "1";
datosFactura.procesoGeneracion = "1";
datosFactura.tipoVenta = "1";
datosFactura.informacionInteres = "Prueba de Información de interés";
//Datos del Cliente
datosFactura.cliente = Cliente.crearCliente();
Consola.mensaje("\r\n - Añadidos Datos del Cliente...", 5, 0, 0);
return datosFactura;
}
}
public class Producto
{
public static Item item = new Item();
public static Item crearItem()
{
//DATOS REFERENCIALES CON FINES DE PRUEBA
//Consultar Manual de Integracion TFHKA para ver detalles precisos
item.descripcion = "Cuadernos";
item.codigo = "T";
item.unidadMedida = "und";
item.cantidad = "2.00";
item.fechaFabricacion = "2020-12-25";
item.unidadMedidaCPBS = "cm";
item.precioUnitario = "69.00";
item.precioUnitarioDescuento = "0.00";
item.precioAcarreo = "1.01";
item.precioSeguro = "12.01";
item.precioItem = "138.00";
item.valorTotal = "171.72";
item.codigoGTIN = "0";
item.cantGTINCom = "0.99";
item.codigoGTINInv = "0";
item.cantGTINComInv = "1.00";
item.tasaITBMS = "03";
item.valorITBMS = "20.70";
item.tasaISC = "0.00";
item.valorISC = "0.00";
item.codigoCPBS = "1410";
return item;
}
}
public class Totales
{
public static totalesSubTotales TotalesSubTotales = new totalesSubTotales();
public static totalesSubTotales generarTotales()
{
//DATOS REFERENCIALES CON FINES DE PRUEBA
//Consultar Manual de Integracion TFHKA para ver detalles precisos
TotalesSubTotales.totalPrecioNeto = "138.00";
TotalesSubTotales.totalITBMS = "20.70";
TotalesSubTotales.totalISC = "0.00";
TotalesSubTotales.totalMontoGravado = "20.70";
TotalesSubTotales.totalDescuento = "";
TotalesSubTotales.totalAcarreoCobrado = "";
TotalesSubTotales.valorSeguroCobrado = "";
TotalesSubTotales.totalFactura = "171.72";
TotalesSubTotales.totalValorRecibido = "171.72";
TotalesSubTotales.vuelto = "0.00";
TotalesSubTotales.tiempoPago = "1";
TotalesSubTotales.nroItems = "1";
TotalesSubTotales.totalTodosItems = "171.72";
TotalesSubTotales.listaFormaPago = new listaFormaPago();
FormaPago formaPago1 = new FormaPago();
formaPago1.formaPagoFact = "02";
formaPago1.valorCuotaPagada = "171.72";
formaPago1.descFormaPago = "";
TotalesSubTotales.listaFormaPago.Add(formaPago1);
return TotalesSubTotales;
}
}
Clase para mostrar los mensajes por consola
public class Consola
{
//CLASE SÓLO CON FINES ESTÉTICOS PARA LA PRESENTACIÓN DE MENSAJES AL USUARIO A TRAVÉS DE LA CONSOLA. NO OBLIGATORIA
public static void mensaje(string mensaje, int colorInicio, int colorFin = 0, int leer = 0)
{
//Se establece color de la línea actual
switch (colorInicio)
{
case 1:
Console.ForegroundColor = ConsoleColor.Cyan;
break;
case 2:
Console.ForegroundColor = ConsoleColor.Yellow;
break;
case 3:
Console.ForegroundColor = ConsoleColor.Gray;
break;
case 4:
Console.ForegroundColor = ConsoleColor.Green;
break;
case 5:
Console.ForegroundColor = ConsoleColor.Blue;
break;
case 6:
Console.ForegroundColor = ConsoleColor.Red;
break;
default:
Console.ForegroundColor = ConsoleColor.White;
break;
}
//Se muestra el Mensaje indicado
Console.WriteLine(mensaje);
//Se establece color de la línea siguiente
switch (colorFin)
{
case 1:
Console.ForegroundColor = ConsoleColor.Cyan;
break;
case 2:
Console.ForegroundColor = ConsoleColor.Yellow;
break;
case 3:
Console.ForegroundColor = ConsoleColor.Gray;
break;
case 4:
Console.ForegroundColor = ConsoleColor.Green;
break;
case 5:
Console.ForegroundColor = ConsoleColor.Blue;
break;
case 6:
Console.ForegroundColor = ConsoleColor.Red;
break;
default:
Console.ForegroundColor = ConsoleColor.White;
break;
}
if (leer == 1)
{
//Se espera por la pulsación de una tecla para continuar
Console.ReadKey();
}
}
}
#endregion
}