Funcionalidad de la API

Factus API Desktop para aplicaciones Desktop, es una librería desarrollada en C++ (COM) para sistemas operativos Windows de 32 y 64 bits. Esta disponible para Windows XP, Windows Vista, Windows 7, Windows 8 y Windows 8.1 en 32 y 64 bits.

Gráfico de clases

Factus expone los siguientes objetos:

Comprobante, es el objeto principal que contiene la información del comprobante electrónico(Boletas, Facturas, Notas de Crédito y Notas de Débito), contiene información de cabecera, participantes, totales y objetos como Items, Impuestos, Documentos de Referencia, Montos Adicionales, Propiedades Adicionales y Atributos personalizados.

Participante, es el objeto que es usado para identificar al emisor y cliente(Receptor), este objeto no necesita ser inicializado y se usa de la siguiente forma: comprobante.Emisor.TipoIdentidad = “6” y comprobante.Cliente.TipoIdentidad = “6”. Contiene datos obligatorios y opcionales.

• Item,
• Impuesto,
• DescuentoCargo,
• MontoAdicional,
• PropiedadAdicional,
• DocumentoReferencia,

Respuesta, este objeto es devuelto al invocar al método Generar(), contiene información como resultado de la generación del comprobante electrónico, cuando el código de error es cero, la generación fue correcta en caso contrario indica el error y mensaje de error. Por otro lado devuelve información sobre la ubicación del archivo XML generado, la firma, el hash y la imagen del código de barra.

A continuación mostramos un ejemplo en sintaxis C#, una factura con 1 item en el que registramos la glosa de monto en letras y la base imponible según especificación de la SUNAT.

Para utilizar Factus COM el primer paso es instanciar la clase principal Comprobante(Hay ejemplos para otros lenguajes):

            Factus.Comprobante c = new Factus.Comprobante();
 

Identificamos los datos básicos del comprobante como el tipo de comprobante, en nuestro ejemplo al ser Factura se colocará “01”. (Según Documentación SUNAT – Tipos de documento)
El campo serie correlativo es el número asignado por el Emisor, este campo es el identificador único del comprobante.
Colocamos también la fecha de emisión del comprobante en formato YYYY-MM-DD.
Registramos el tipo de moneda del comprobante.

            c.TipoComprobante = “01”;
            c.SerieCorrelativo = “F001-101”; 
            c.FechaEmision = “2015/01/01”; 
            c.TipoMoneda = "PEN"; 
 

Lo siguiente que haremos, es instanciar la clase Participante, ya que aquí colocaremos los datos tanto del Emisor como del Cliente.

Colocamos el numero del tipo de documento del Emisor, según Documentación SUNAT (Catalogo Nro.6).(Ver Documentación SUNAT)

Procedemos a llenar los demás campos del Emisor:

(Según Catalogo Nro.13 Documentación SUNAT.) (Ver relación de UBIGEO para Lima)

            c.Emisor.TipoIdentidad = “6”;
            c.Emisor.NumeroIdentidad = “20543314529”;
            c.Emisor.NombreComercial = “ComplexLess”;
            c.Emisor.RazonSocial = “ComplexLess S.A.C.”;
            c.Emisor.Ubigeo =  "150141”;
            c.Emisor.Pais = "PE";
            c.Emisor.Departamento = "Lima”;
            c.Emisor.Provincia = “Lima”;
            c.Emisor.Distrito = “Surquillo”;
            c.Emisor.Direccion = “Av. Aramburu 856 Of. 302”;
 

Ya habiendo registrado los datos del emisor, instanciamos la clase Participante nuevamente, para poder registrar los datos del Cliente.

Colocamos el numero del tipo de documento del Cliente, en este caso para el Documento Nacional de Identidad (DNI), se colocará “1” (Según Catalogo Nro.6 Documentación SUNAT)

Procedemos a llenar los demás campos del Cliente:

• Numero identidad cliente: Numero de identidad del cliente.
• Razón Social cliente: Razón Social del cliente.
• País cliente: Código del país del cliente.
• Distrito cliente: Distrito del cliente.
• Dirección cliente: Dirección detallada del cliente.

            c.Cliente.Tipoidentidad = "1"; 
            c.Cliente.NumeroIdentidad = “09574547”;
            c.Cliente.RazonSocial = "SUNAT";
            c.Cliente.Pais = "PE";
            c.Cliente.Distrito = "San Isidro";
            c.Cliente.Direccion = "Av los Sauces 321 Lince";
  

Luego de haber registrado al Emisor y al Cliente, procedemos a registrar los campos de los Items. Como se sabe, una Factura puede contener varios items, para este ejemplo solo añadiremos un item.

Para esto, procedemos a instanciar la clase Item.

            Factus.Item it = c.NuevoItem(); 
 

En este caso el campo id se registra de manera correlativa de acuerdo al numero de ítems que posea el comprobante.

Como en el caso anterior, completamos los campos del item: Cantidad, Descripción, Código del Producto, Precio Unitario, Base Imponible, Tipo precio e Impuesto Total de cada Ítem.

          
            it.Id = “1”;
            it.Cantidad = 10;
            it.Descripcion = ”Televisor LG Full HD “;
            it.CodigoProducto = "10234";
            it.PrecioUnitario = 11.80;
            it.BaseImponible = 118.00
            it.TipoPrecio = "01";
            it.TotalImpuesto = ”18.00”;
 

Antes de que vayamos a agregar el item a nuestra Factura, tenemos que tener en cuenta que cada Item, posee un impuesto, asi que:

Instaciaremos la clase Impuesto:

            Factus.Impuesto imp = it.NuevoImpuesto();
 

Procedemos a registrar los campos del impuesto por item, en este caso supongamos que el item tenga como tipo de impuesto a “IGV”. En este caso como es “IGV” se registra el campo Id = “VAT” , el campo Nombre_ = “IGV” y para este caso SunatId = “1000”.(Ver Catalogo Nro. 5 SUNAT para mayor información).
Hay que tener en cuenta de que un item puede poseer varios impuestos, pero en este caso añadiremos un impuesto como ejemplo:

            imp.Id = “VAT”;
            imp.Nombre = “IGV”;
            imp.SunatId = “1000”;
            imp.BaseImponible = 100.00;
            imp.TotalImpuesto = 18.00;
            imp.Porcentaje = 18;
 

Después de haber registrado los campos agregamos el impuesto del ítem asi:

            it.AgregarImpuesto(imp);
 

Cada Item tendrá un Descuento o un Cargo adicional en la Factura, aquí también cada item puede poseer varios cargos o descuentos según se decida aplicar, entonces:

Procedemos a instanciar la clase DescuentosCargos:

            Factus.DescuentoCargo desCarIt = it.NuevoDescuentoCargo();
 

Y registramos los campos, donde:
IdCd es el identificador de los descuentos o cargos según se registre en el comprobante.
MontoCd es el monto de los descuentos o cargos según sea el caso.

            desCarIt.IdCd = 1;  /* Para Cargos: id = 1, y para Descuentos: id = 2 */
            desCarIt.MontoCd= 180.20;
 

Agregamos el descuento o cargo del ítem:

            it.AgregarDescuentoCargo(desCarIt);
 

Finalmente procedemos a agregar este Ítem con el impuesto y Descuento o cargo del mismo.

            c.AgregaItem ( it );
 

Una vez registrado los impuestos de cada Ítem , se sabe que tambien existe un impuesto a nivel general en la factura, para esto vamos a registrar el Impuesto General.
Debemos recordar que pueden existir tambien varios impuestos a nivel general en la Factura, para este ejemplo añadiremos uno sólo.

Instanciamos la clase Impuesto (Impuesto General)

            Comprobante.Impuesto impG = new Comprobante.Impuesto();
 

Y registramos los campos, donde:
Como en el ejemplo se calcularon los items con “IGV” entonces, se registra el campo Id = “VAT”, el campo Nombre = “IGV” y SunatId = “1000”.(Ver Catalogo Nro. 5 SUNAT para mayor información).
El campo TotalImpuesto es la suma de los impuestos individuales de cada Ítem.

            impG.Id = ”VAT”;
            impG.SunatId = ”1000”;
            impG.Nombre = ”IGV”;
            impG.TotalImpuesto = 72.0;
 

Agregamos el impuesto general de la factura.

            c.AgregarImpuesto ( impG );
 

Al igual que los impuestos, también existen los Descuentos/Cargos a nivel general en la factura. (Pueden existir varios descuentos o cargos en la factura a nivel general).

Instanciamos la clase DescuentosCargos

            Comprobante.DescuentosCargos desCarG = new Comprobante.DescuentosCargos();                                                            

Y registramos los campos, donde:
IdCd es el identificador de los descuentos o cargos según se registre en el comprobante.
MontoCd es el monto de los descuentos o cargos según sea el caso.

            desCarG.IdCd = 2;         /*  Para Cargos: id = 1, y paraDescuentos: id = 2  */
            desCarG.MontoCd= 202.30;
 

Y se procede a agregar el descuento o cargo general en el Comprobante.

            c.AgregarDescuento ( desCarG );
 

A continuación instanciamos la clase Monto adicional

             Comprobante.MontoAdicional monto = new Comprobante.MontoAdicional();
 

Y registramos los campos:

MontoAdicional tiene como campos a ID, en este caso se coloca el Id = “1001” que es el identificador para el Total valor de venta por Operación Gravada con el IGV(Ver catalogo Nro. 14 Documentación SUNAT).
Y luego se procede a colocar el Nombre del monto adicional, Monto Referencial, Importe total, Porcentaje y Monto total.

             monto.ID =  “1001”;
             monto.Nombre = “Monto adicional 1 ”;
             monto.MontoReferencial =  20.00;
             monto.ImporteTotal =  18.00;
             monto.Porcentaje = 18.00;
             monto.MontoTotal =  100.00; 
 

Al completar los campos, se procede a registrar el Monto Adicional al comprobante.

            c.AgregarMontoAdicional ( monto );
 

Instanciamos la clase PropiedadAdicional
(Donde puede registrarse informacion de cualquier tipo).

             Comprobante.PropiedadAdicional propiedad = new Comprobante.PropiedadAdicional();                               

Y registramos los campos:

La clase PropiedadAdicional tiene como campos a ID , Nombre y Valor.
En este ejemplo se coloca en ID = “9999” que concierne a “Otros”. (Según Documentación SUNAT), luego se coloca el Nombre y el Valor del concepto adicional.

             propiedad.ID = “9999”;
             propiedad.Nombre  = “Propiedad Adicional 1”;
             propiedad.Valor = “Valor de propiedad adicional”;
  

Registramos la propiedad adicional en el comprobante.

              c.AgregarPropiedadAdicional ( propiedad );
 

Instanciamos la clase DocumentoReferencia
(Podemos añadir un documento de referencia a nuestra factura, por ejemplo, una Guía de Remisión).

          Comprobante.DocumentoReferencia documento = new Comprobante.DocumentoReferencia();
 

Y registramos los campos, donde:
Id es el numero del documento de referencia.
TipoDocumento es el código del tipo de documento de referencia.(Ver catalogo Nro. 01 Documentación SUNAT).
Fecha es la fecha del documento de referencia.
DescripcionTipoDocumento es la descripción del documento que se esta añadiendo como referencia.

              documento.Id = "0044423"
              documento.Fecha = "2015/03/10"
              documento.TipoDocumento = "09"
              documento.DescripcionTipoDocumento = "Guía de remisión"
 

Agregamos el documento de referencia a la factura

             c.AgregarDocumentoReferencia( documento );
 

Ya registrado los campos anteriores mencionados, se procede a registrar las cantidades totales de la factura como muestra a continuacion:

Importe total de cargos aplicados al total de la factura. <pre class="prettyprint">

        c.TotalCargos = "130.50"; 

</pre>

Total de los descuentos aplicados al total de la factura <pre class="prettyprint">

        c.TotalDescuento = "34.20"; 

</pre>

Importe total de los impuestos aplicados en la factura <pre class="prettyprint">

        c.TotalImpuesto = "34.20"; 

</pre>

Importe total a pagar <pre class="prettyprint">

        c.ImporteTotal = "3024.20"; 

</pre>

Podemos agregar a nuestra factura otros atributos de tipo monetario, entonces:

Invocamos al método Otro Atributo

El método AgregarOtroAtributo tiene como parámetros el ID = “1000” (Ver catalogo Nro. 15 Documentación SUNAT), y el Valor, en este caso la Glosa expresado en letras el monto total de la Factura. (Tengamos en cuenta que en este método pueden agregarse varios atributos)

              c.AgregarOtroAtributo ( “1000” ,  
                                      “TRES MIL VEINTE Y CUATRO CON 20/100 NUEVOS SOLES”);
 

Después de haber terminado con la asignación de valores de los campos de la Factura se usará el método Generar.

Para esto, instanciamos la clase Respuesta

              Respuesta r;      
 

Este método genera el comprobante y lo devuelve en un objeto tipo Respuesta.

Llamamos al método Generar.

              r = c.Generar();
 

El objeto Respuesta contiene los siguientes atributos:

• CodigoError
• MensajeError
• ArchivoPDF417
• ArchivoXML
• Hash
• ResultadoFirma

Esto puede ser utilizado de la siguiente forma:

        If (r.CodigoError = 0 ) 
            MessageBox.Show(r.ArchivoPDF417)      /* Muestra ruta del PDF471 */
            MessageBox.Show(r.ArchivoXML)         /* Muestra ruta del XML */
            MessageBox.Show(r.Hash)                 /* Muestra valor del Hash */
            MessageBox.Show(r.ResultadoFirma)     /* Muestra valor de la Firma */

        Else
            MsgMessageBox.Show(r.MensajeError) /* Muestra mensaje en caso de presentar un error */
              
        End If
 

En este ejemplo evaluamos:
Si CodigoError es igual a cero, quiere decir que no hay error por lo tanto el atributo MensajeError vendrá vacío, pero los otros atributos tendrán valores como se describe a continuación:

Devuelve una cadena de caracteres, que indica la ruta donde se guardó el archivo PDF417 como imagen en formato PNG (La ruta siempre será la que tenga mayor permiso para escritura, por defecto será el directorio Documentos).

Ejemplo:

  
C:\Users\Admin\Documents\20543314529_01_F001-101.PNG
 

Este atributo es el más importante, ya que nos entrega la ruta de la imagen en formato PNG que debemos agregar a la representación impresa del comprobante como se muestra en la siguiente imagen de ejemplo:

Devuelve una cadena de caracteres, que indica la ruta donde se guardó el archivo XML que tendrá de acuerdo a la especificación de la SUNAT.

Ejemplo:

            C:\Users\Admin\Documents\20543314529_01_F001-101.XML
 

Devuelve el valor de la cadena resumen calculado del archivo XML en una cadena de caracteres. Según la especificación de la SUNAT este valor se puede imprimir en la representación impresa del comprobante en vez de utilizar la imagen PDF417.

Ejemplo:

oXaHY4FXt643ktMb2xEEmrFW5jA=
 

Ejemplo de una representación impresa con Hash:

Devuelve el valor de la firma digital calculada del archivo XML y utilizando el certificado digital asignado al emisor, en cadena de caracteres.

Ejemplo:

              LsNuE0mHnAtQsx5h5ZdWSOnvo3MCtcYfnc34BNsmBj3h+19At3ib5xeGcHt
              +ZT+Q4vZ/UGP9/fwFCMvtvpXu4zQMcYLIIqIkY4qTXGe/QBu5YG/1xZxCIQMc
              4cIhPV0unWt/dKwz5Yp4PgjgNr0+eVxQ7LNVSLFwj1aQ9YA3xtIEE/8U6K2UYv
              DI0HaKZelpnMjyoQn1l6u13+krt7226pwbjo4R/v/0x6wby5PVFrvsu88gEIXDoD
              rX6u1p2rpCAva3E0mzWWYSJvoE8AM1a/KkGt0LcMQ5ZrqHvKOTxYtR/VLurZs
              ylOZxJkWVTX3Y+oqp4jcdwgPsm1zK8DihQA==