Para poder crear un factura, es necesario tener previamente al menos un cliente y un concepto.

La vida de una factura

Factura Gorila tiene un control integral que cubre toda la vida de una factura, desde su concepción, hasta el pago o cancelación de la misma.

El flujo de estados es:

Ciclo de vida de una factura

Estado Borrador

Cuando una factura es Borrador, existe los datos pero no es una factura válida como tal. Este estado es útil cuando se quiere guardar el progreso de una factura sin crearla. De Borrador se puede cambiar a estado Creada, pero no viceversa. Las facturas en este estado si pueden ser actualizadas. Estas facturas son ignoradas durante la generación de reportes y en los cálculos de facturación reciente.
Las facturas en Estado borrador no se retornan al consultar los datos de Facturas a menos que, se incluya “estado=borrador” en el query de la consulta.

Estado Creada

Una factura Creada esta timbrada y es válida ante el SAT. Las facturas en estado Creada ya no pueden ser editadas, pasan a ser de solo lectura.

Estado Enviada

Una factura pasa a Enviada cuando se le exige a la API que envie la factura Creada al cliente a través del parámetro EnviarAlCliente. En caso de no ser enviada desde la API, la factura nunca tendrá este estado.

Estado Pagada

El estado Pagada ocurre cuando la suma acumulada de todos los Pagos a una Factura es igual al valor total de la Factura. Se puede asumir que una factura en estado Creada o Enviada no ha sido pagada. Si el usuario no registra sus pagos correctamente, entonces la factura nunca verá este estado. Desde este estado, solo se puede cambiar a Cancelada.

Estado Cancelada

Cuando el usuario decide cancelar una factura, esta factura pasa a ser inválida ante el SAT. Tanto Factura Gorila como el SAT dejan un registro de la factura que existió y ahora es Cancelada. Una factura Cancelada dejan de formar parte del total de la Facturación Reciente pero si son incluidas en los Reportes de Facturas y en el Resumen de Facturas (Véase sección de Reportes). Todos los pagos realizados para una factura cancelada tambien son eliminados.

De este estado, la factura ya no puede cambiar de estado.

 

Obtener la lista de Facturas

Petición

El listado de facturas se obtiene en la siguiente url por método GET

https://app.facturagorila.com/v1/api/facturas/

Se pueden utilizar los siguientes parámetros:

  • p: es el número de página deseado empezando por 0 (cero)
  • epp: el número de elementos por página
  • fechainicio: Busca las facturas creadas desde una fecha hasta hoy. El formáto es dd-MM-yyyy
  • fechafinal: Busca las facturas creadas antes de una fecha en particular. El formáto es dd-MM-yyyy
  • estado: Puede ser “Borrador”, “Creada”, “Enviada”, “Pagada” y “Cancelada”
  • rfc: Filtro de las facturas para cierto cliente
  • sucursalid: identificador único de la sucursal para filtrar facturas de cierta sucursal (véase objeto Usuario)

Este punto no retorna las Facturas marcadas como borrador a menos que se incluya el parámetro “estado” igual a “Borrador”. Esto significa que no es posible ver las facturas Borrador junto con el resto de las facturas válidas en una sola consulta.

Ejemplo (JSON):

{
   "TotalResultados":2,
   "CantidadPorPagina":10,
   "TotalDePaginas":1,
   "PaginaActual":0,
   "TipoDatoResultado":"Factura",
   "Resultados":[
      {
         "Serie":"C",
         "Folio":504,
         "FacturaId":1179,
         "RegimenFiscalId":22,
         "SucursalId":49,
         "ClienteId":84,
         "DireccionId":785,
         "Fecha":"2013-03-06T18:41:56",
         "MetodoDePagoId":-1,
         "NumeroDeCuenta":"No Identificado",
         "Moneda":"MXN",
         "Conceptos":[
            {
               "Index":-1,
               "Descripcion":"Articulo con ISR",
               "Cantidad":1.0000,
               "ConceptoId":114,
               "Concepto":{
                  "ConceptoId":114,
                  "Descripcion":"Articulo con ISR",
                  "Clave":"ISR",
                  "Precio":100.00,
                  "Tipo":"Producto",
                  "UnidadDeMedida":"Pieza",
                  "UnidadDeMedidaId":1,
                  "IDsImpuestosAplica":"2"
               },
               "PrecioUnitario":1.000,
               "SubTotal":1.0000000
            }
         ],
         "NotasDelCliente":"",
         "TipoDeCambio":1.0000,
         "TotalFactura":0.9000,
         "TotalImpuestos":-0.1000,
         "CondicionesDePago":"Pago en una sola exhibición",
         "CodigoBidimensionalId":-1,
         "CorreosAEnviarFactura":"",
         "EsBorrador":false,
         "EnviarAlCliente":false,
         "Etiquetas":"",
         "EstadoFactura":"Pagada",
         "NombreCliente":"Test Nombre 2",
         "PorcentajeDescuento":0.0,
         "EtiquetaDescuento":"Descuento",
         "MotivoDescuento":null
      },
      {
         "Serie":"C",
         "Folio":503,
         "FacturaId":1178,
         "RegimenFiscalId":22,
         "SucursalId":49,
         "ClienteId":83,
         "DireccionId":784,
         "Fecha":"2013-03-06T18:41:29",
         "MetodoDePagoId":-1,
         "NumeroDeCuenta":"No Identificado",
         "Moneda":"MXN",
         "Conceptos":[
            {
               "Index":-1,
               "Descripcion":"Libreta Pofesional 100 hojas",
               "Cantidad":1.0000,
               "ConceptoId":108,
               "Concepto":{
                  "ConceptoId":108,
                  "Descripcion":"Libreta Pofesional 100 hojas",
                  "Clave":"0002",
                  "Precio":1.67,
                  "Tipo":"Producto",
                  "UnidadDeMedida":"Pieza",
                  "UnidadDeMedidaId":1,
                  "IDsImpuestosAplica":"3,3,7"
               },
               "PrecioUnitario":1.670,
               "SubTotal":1.6700000
            }
         ],
         "NotasDelCliente":"",
         "TipoDeCambio":1.0000,
         "TotalFactura":2.3881,
         "TotalImpuestos":0.7181,
         "CondicionesDePago":"Pago en una sola exhibición",
         "CodigoBidimensionalId":-1,
         "CorreosAEnviarFactura":"",
         "EsBorrador":false,
         "EnviarAlCliente":false,
         "Etiquetas":"",
         "EstadoFactura":"Creada",
         "NombreCliente":"Test Nombre 1_",
         "PorcentajeDescuento":0.0,
         "EtiquetaDescuento":"Descuento",
         "MotivoDescuento":null
      }
   ]
}

 

Obtener una Factura

Petición

Conociendo el id de la factura (Factura.FacturaId), se puede consultar por metodo get en la siguiente url:

https://app.facturagorila.com/v1/api/facturas/{id}

Respuesta

Ejemplo (JSON):

{
   "Serie":"C",
   "Folio":504,
   "FacturaId":1179,
   "RegimenFiscalId":22,
   "SucursalId":49,
   "ClienteId":84,
   "DireccionId":785,
   "Fecha":"2013-03-06T18:41:56",
   "MetodoDePagoId":-1,
   "NumeroDeCuenta":"No Identificado",
   "Moneda":"MXN",
   "Conceptos":[
      {
         "Index":-1,
         "Descripcion":"Articulo con ISR",
         "Cantidad":1.0000,
         "ConceptoId":114,
         "Concepto":{
            "ConceptoId":114,
            "Descripcion":"Articulo con ISR",
            "Clave":"ISR",
            "Precio":100.00,
            "Tipo":"Producto",
            "UnidadDeMedida":"Pieza",
            "UnidadDeMedidaId":1,
            "IDsImpuestosAplica":"2"
         },
         "PrecioUnitario":1.000,
         "SubTotal":1.0000000
      }
   ],
   "NotasDelCliente":"",
   "TipoDeCambio":1.0000,
   "TotalFactura":0.9000,
   "TotalImpuestos":-0.1000,
   "CondicionesDePago":"Pago en una sola exhibición",
   "CodigoBidimensionalId":-1,
   "CorreosAEnviarFactura":"",
   "EsBorrador":false,
   "EnviarAlCliente":false,
   "Etiquetas":"",
   "EstadoFactura":"Pagada",
   "NombreCliente":"Test Nombre 2",
   "PorcentajeDescuento":0.0,
   "EtiquetaDescuento":"Descuento",
   "MotivoDescuento":null
}

 

Insertar una Factura

Petición

Se hace una peticion por POST a la siguiente url:

https://app.facturagorila.com/v1/api/facturas/

Se requieren los siguientes datos:

  • RegimenFiscalId
  • SucursalId
  • ClienteId
  • DireccionId
  • Fecha
  • MetodoDePagoId
  • NumeroDeCuenta
  • Moneda
  • TipoDeCambio
  • CondicionesDePago
  • CodigoBidimencionalId
  • CorreosAEnviarFactura
  • EsBorrador
  • EnviarAlCliente
  • Conceptos
  • PorcentajeDescuento
  • EtiquetaDescuento
  • MotivoDescuento
  • NotasDelCliente

Ejemplo (JSON)

{
   "RegimenFiscalId":22,
   "TipoDeCambio":"1.000000",
   "MetodoDePagoId":1,
   "DireccionId":780,
   "FacturaId":0,
   "Conceptos":[
      {
         "PrecioUnitario":"1.670000",
         "SubTotal":"1.670000",
         "Index":0,
         "Descripcion":"Libreta Pofesional 100 hojas",
         "Cantidad":"1.000000",
         "ConceptoId":108
      }
   ],
   "EnviarAlCliente":0,
   "CodigoBidimensionalId":0,
   "CondicionesDePago":"Pago en una sola exhibición",
   "TotalImpuestos":"0.450900",
   "Moneda":"MXN",
   "Folio":0,
   "ClienteId":13,
   "NombreCliente":"Test1 Test1 Test1 Pacheco",
   "PorcentajeDescuento":"0.000000",
   "EsBorrador":0,
   "SucursalId":49,
   "TotalFactura":"2.120900",
   "Fecha":"2013-03-13T16:25:55"
}

Respuesta

Se retorna el objeto recién insertado. Además se incluye en el HTTP header Location una url al elemento recién insertado.

Ejemplo:

{
   "Serie":"C",
   "EtiquetaDescuento":"Descuento",
   "NotasDelCliente":"",
   "RegimenFiscalId":22,
   "MotivoDescuento":null,
   "MetodoDePagoId":1,
   "CodigoBidimensionalId":-1,
   "TotalFactura":2.3881,
   "TotalImpuestos":0.7181,
   "Folio":507,
   "SucursalId":49,
   "EstadoFactura":"Creada",
   "Moneda":"MXN",
   "Etiquetas":"",
   "Fecha":"2013-03-13T16:25:55",
   "ClienteId":13,
   "FacturaId":1184,
   "NumeroDeCuenta":"",
   "Conceptos":[
      {
         "PrecioUnitario":1.67,
         "SubTotal":1.67,
         "Index":-1,
         "Descripcion":"Libreta Pofesional 100 hojas",
         "Cantidad":1,
         "Concepto":{
            "UnidadDeMedidaId":1,
            "Tipo":"Producto",
            "UnidadDeMedida":"Pieza",
            "IDsImpuestosAplica":"3,3,7",
            "Descripcion":"Libreta Pofesional 100 hojas",
            "Clave":"0002",
            "Precio":1.67,
            "ConceptoId":108
         },
         "ConceptoId":108
      }
   ],
   "CondicionesDePago":"Pago en una sola exhibición",
   "DireccionId":780,
   "CorreosAEnviarFactura":"",
   "EsBorrador":false,
   "NombreCliente":"Test1 Test1 Test1 Pacheco",
   "TipoDeCambio":1,
   "PorcentajeDescuento":0,
   "EnviarAlCliente":false
}

 

Enviar factura al cliente

Para enviar la factura inmediatamente luego de ser creada se utiliza la propiedad EnviarAlCliente con valor “true”. La API se encargará de crear la factura y enviarla al correo electrónico del cliente.
Opcionalmente, la aplicación cliente puede descargar la factura creada (ver detalles a continuación) y enviarla por sus propios medios.

 

Re-enviar una factura luego de ser Creada

Si se desea que Factura Gorila envie la factura a un cliente, o alguna otro correo luego de ser creada, se ofrece un punto de servicio para poder hacer el reenvío del documento si que la aplicación cliente tenga que manejar los archivos directamente.

Petición

Se hace una peticion a la siguiente url por metodo GET

https://app.facturagorila.com/v1/api/facturaenviar/{id}

Se debe incluir como parámetros en query:

  • emails: Es la lista de correos a las que se desea enviar la factura separadas por comas

 

Respuesta

Se retorna un código HTTP 200 en caso de éxito.

 

Actualizar una Factura

Petición

Se hace una peticion por metodo PUT a la siguiente url

https://app.facturagorila.com/v1/api/facturas/{id}

Solo se puede actualizar una factura, que haya sido marcada como borrador. Una factura en cualquiera otro de los estados ya no puede ser editada.

Se requieren los siguientes datos:

  • RegimenFiscalId
  • SucursalId
  • ClienteId
  • DireccionId
  • Fecha
  • MetodoDePagoId
  • NumeroDeCuenta
  • Moneda
  • TipoDeCambio
  • CondicionesDePago
  • CodigoBidimencionalId
  • CorreosAEnviarFactura
  • EsBorrador
  • EnviarAlCliente
  • Conceptos
  • PorcentajeDescuento
  • EtiquetaDescuento
  • MotivoDescuento
  • NotasDelCliente

Respuesta

Se obtiene un código HTTP 200 en caso de éxito, o un 400 (Bad request) en caso de error.

 

Facturas borrador

Factura gorila permite a los usuarios crear facturas borrador. Básicamente, lo que se hace es guardar en base de datos pero sin procesarla, ni enviarla al cliente. La aplicación cliente puede aprovechar esta característica para guardar en el servidor datos de facturas incompletas.
Implementar en control de facturas borrador en realidad es opcional, ya que podría ser sustituido por una base de datos local, sin embargo, sería práctico que pudieras comenzar una factura, digamos por ejemplo, en un dispositivo móvil y la termines de llenar y enviar desde el sitio web.

Para crear una factura en borrador, es necesario poner Factura.Borrador a “true”.

 

Cancelar una Factura

No es posible borrar una factura, pero es posible marcarla como cancelada. La cancelación es el último estado posible para una factura.

Petición

Se hace una peticion por método GET a la siguiente url:

https://app.facturagorila.com/v1/api/facturacancelar/{id}

Se requiere en el query se incluya:

  • motivo: Es una descripción corta que explica por que se canceló la factura

Respuesta

Un codigo HTTP 200 en caso de exito.

 

Descargar una factura

La factura electrónica puede ser uno o dos archivos dependiendo del tipo de facturación:

  • CBB: Este método de facturación solo consta de un archivo PDF
  • CFDI: Consta de un archivo PDF y XML. El PDF es sólo una representación del contenido en el archivo XML, la factura en si, es el archivo XML.

Factura Gorila permite a sus usuarios cambiar de modo a CBB a CFDI, pero no viceversa. Esto da como resultado que, aunque un usuario esté usando CFDI actualmente, existan facturas viejas que no tengan el XML porque fueron creadas con CBB. La aplicación cliente debe estar preparada para el caso en el que el archivo XML sea vacio.

En importante recalcar, que en el método CFDI, la factura consta de los 2 archivos, el XML y el PDF, así pues, si una aplicación cliente desea proveer el servicio de envío o descarga de facturas, debe de incluir ambos archivos y no sólo el PDF.

Descargar PDF

Conociendo el id de la factura, se puede decargar el PDF en la siguiente url por método GET

https://app.facturagorila.com/v1/api/facturapdf/{id}

El archivo PDF sólo puede ser descargado siempre y cuando el Id sea válido y que la factura no esté marcada como borrador (Factura.EsBorrador es igual a “true”)

 

Decargar XML

Conociendo el id de la factura, se puede decargar el XML en la siguiente url por método GET

https://app.facturagorila.com/v1/api/facturaxml/{id}

El archivo XML sólo existe cuando la factura es de tipo CFDI. La aplicación cliente puede usar la propiedad Usuario.UsaCodigoBidimensional para identificar si debería o no intentar descargar el archivo XML, si Usuario.UsaCodigoBidimensional  es igual a “true”, entonces es seguro que ninguna factura tiene archivo XML, sin embargo, si Usuario.UsaCodigoBidimensional  es igual a “false” es posible que la factura si tenga un archivo XML.

Las facturas marcadas como borrador no tienen un XML. Aunque haya sido marcada como cancelada, aun es posible descargar el XML.

 

Descargar el PDF y el XML de una factura cancelada

Una vez que la factura ha sido cancelada, continúa estando disponible el servicio de descarga de los archivos de PDF y XML. La única diferencia es que el PDF se genera ligeramente distinto a cuando la factura no era cancelada. Si la aplicación cliente tiene implementado algún cache o repositorio de archivos, se recomienda descargar el PDF de nuevo después de cancelar.