Dirección URL

La dirección base de la api esta en

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

El uso de HTTPS es obligatorio, no se puede acceder a la API a través de HTTP.

 

Dirección URL para el servicio de pruebas

Durante el desarrollo de la aplicación, se recomienda utilizar la API de pruebas, que te permitirá utilizar la API en su totalidad pero sin consumir facturas reales. Todo el servicio es idéntico al servicio normal, la diferencia es que las facturas generadas no serán timbradas y no serán reconocidas por el SAT.

La dirección url para el ambiente de pruebas está en

http://test.facturagorila.com/v1/api/

 

Para usar la api de pruebas necesitas registrar un usuario nuevo. Los datos registrados en el sitio normal son independientes al sitio de pruebas, puedes crear un usuario identico al sitio de normal, o bien usar datos falsos.

Para registrar a un usuario de pruebas accede a la siguiente url

http://test.facturagorila.com/

Una vez que registras un usuario, es necesario que complementes toda la documentación, de otra forma no podrás hacer las pruebas de emision de facturas.

Una vez que completas el registro del usuario, accede a la sección de Aplicaciones y registra una aplicación. Esta aplicación solo será usable en el ambiente de pruebas. Solo necesitas registar una vez la aplicación, con alguno de tus usuarios de pruebas, pero puedes registrar multiples usuarios de pruebas, conforme lo requieras. Durante el registro del usuario, se define si quieres que sea CBB o CFDI, si se planea hacer una aplicación para usuarios en general, se recomiendad probar con ambos métodos.

Con el usuario y tu aplicación registrada podrás ya podrás empezar a usar la API según se detalla en esta documentación. Lo mas importante es que las facturas generadas, no serán válidas y no tendrán ningun costo, lo que te permitirá probar y cometer todos los errores que necesites.

Nomenclatura

  1. Aplicación cliente: es el software que se conecta a la API de Factura Gorila.
  2. Usuario: Es la persona que utiliza la Aplicación cliente.
  3. Punto de la API: Es una url o una parte del servicio

 

Formatos de Peticiones

Todos los pedidos a la API pueden ser en XML o en JSON y se envían en HTTP GET, POST, PUT o DELETE, dependiendo si se va a leer, insertar un nuevo elemento o a actualizar uno ya existente o borrarlo.

  • El contenido debe de estar en codificación UTF-8
  • Los nombres de las propieades están escritos sin acento y no son sensibles a mayúsculas y minúsculas

Ejemplo de una petición:

{
   "Tipo":"Producto",
   "IDsImpuestosAplica":"5,3",
   "Descripcion":"Mouse touch",
   "Clave":"719927293",
   "UnidadDeMedidaId":1,
   "Precio":2184.000000
}

Formato de Respuestas

Todas las respuestas se obtienen en XML o JSON y se entregan con un código de estado 200 o 204. La aplicación cliente puede definir el encabezado “Accept” de HTTP para indicar que tipo de respuesta desea obtener:

Accept: application/xml

O bien para JSON:

Accept: application/json

Por defecto se retorna XML, pero se recomienda que se defina explícitamente ya que este comportamiento puede cambiar en un futuro.

 

En caso de error

Si ocurre algún problema al procesar la petición se entrega la respuesta con un código de error además de un mensaje sobre los múltiples problemas ocurridos. Cada punto del servicio implementa mensajes distintos, se puede consultar la documentación específica de cada obtener más detalles.

 

Direcciones REST y operaciones CRUD

CRUD es el acrónimo de Crear, Obtener, Actualizar y Borrar (en inglés: Create, Read, Update and Delete) y consiste en las 4 operaciones básica de una base de datos. La API de Factura Gorila tiene soporte para las operaciones CRUD que son accedidas a través de direcciones estilo REST.

 

Direcciones

Las direcciones de acceso siguen casi el mismo patrón, solo cambia en la dirección el tipo de elemento que se desea acceder. Por ejemplo, las direcciones del servicio para los Conceptos serían:

Accion

Método HTTP

URL

Obtener una lista GET /api/Conceptos
Obtener un elemento GET /api/Conceptos/{id}
Obtener lista filtrada GET /api/Conceptos?param1=algo
Crear un nuevo elemento POST /api/Conceptos
Actualizar un elemento PUT /api/Conceptos/{id}
Borrar un elemento DELETE /api/Conceptos/{id}

La parte de “{id}” se reemplaza por el identificador único del elemento.

Las direcciones sería similares para Facturas o Clientes, solo habria que cambiar en la url el tipo de elemento que se desea.

Algunas partes del servicio no tienen disponible todas las operaciones, ya sea porque son datos de solo lectura o porque son datos que no se permite actualizar o borrar. Para detalles consultar cada punto del servicio para ver que operaciones si están disponibles.

 

Métodos HTTP

La API implementa diferentes métodos de HTTP, dependiendo de lo que necesita hacer hay que seleccionar el método correcto al hacer peticiones a la API.

Método GET

Las peticiones por GET sirven para poder hacer consultas de datos. Los datos retornado varía dependiendo de punto consultado. Todos los puntos de la API implementan al menos el método GET.

Método POST

Las peticiones por POST se espera recibir un grupo de valores para poder crear un nuevo objeto en base de datos. No todos los puntos de la API implementan el método POST.

Método PUT

Las peticiones por PUT se espera recibir un grupo de valores para poder actualizar un objeto existente en la base de datos. No todos los puntos de la API implementan el método PUT.

Método DELETE

Las peticiones por DELETE se utiliza para borrar un objeto en particular.

 

Objeto Consulta

Todos los puntos que retornan una lista de resultados están envueltos en un objeto de Tipo Consulta, que incluye los datos solicitados, y además, incluye otra información útil para procesar estos datos, como el numero total de resultados esperados o el numero de página actual. Si quieres saber mas sobre el objeto Consulta, visita la sección de Tipos de datos.