Listar, filtrar y ordenar registros desde la API
Para ilustrar cómo listar registros a través de la API de FacturaScripts, utilizaremos el recurso de impuestos, que contiene un número reducido de elementos. Para ello, realiza una consulta de tipo GET a la siguiente URL:
http://localhost:8000/api/3/impuestos
Este listado está limitado a 50 elementos por defecto y comienza desde el primer elemento. Para obtener más o menos registros de golpe, puedes usar los parámetros ?limit=50&offset=0.
📖 Paginación
Para recibir más resultados, es necesario indicar desde qué elemento deseas continuar recibiendo datos. En este ejemplo, obtendremos 50 elementos comenzando desde el 1 (saltando el primer elemento, que es el 0):
http://localhost:8000/api/3/impuestos?offset=1
Ejemplos de paginación
Partiendo de los parámetros offset y limit, podemos estructurar la paginación de la siguiente manera (con un límite de 3 elementos por página):
- Página 1:
?offset=0&limit=3- devolverá los elementos 0, 1 y 2. - Página 2:
?offset=3&limit=3- devolverá los elementos 3, 4 y 5. - Página 3:
?offset=6&limit=3- devolverá los elementos 6, 7 y 8.
🔎 Filtros
Puedes aplicar varios filtros al listado para obtener solo los resultados que cumplan con ciertos criterios. Para ello, basta con agregar el parámetro filter[nombre_columna]=valor a tu consulta.
🔎 Filtrado por codimpuesto
Para obtener todos los registros con el valor IVA21 en codimpuesto:
http://localhost:8000/api/3/impuestos?filter[codimpuesto]=IVA21🔎 Filtrado por codimpuesto y tipo
Se pueden usar varios filtros a la vez, así que para obtener todos los registros con el valor IVA21 en codimpuesto y el valor 1 en tipo, usaríamos esta url:
http://localhost:8000/api/3/impuestos?filter[codimpuesto]=IVA21&filter[tipo]=1🔎 Filtrar por iva
Para obtener todos los registros con un valor de iva superior a 8 usaremos esta url:
http://localhost:8000/api/3/impuestos?filter[iva_gt]=8🔎 Filtrar mayor que, menor, distinto, etc
Los filtros aplican por defecto el operador =, es decir, buscan coincidencias exactas, pero puedes usar otros operadores añadiendo un sufijo al nombre de la columna. Aquí tienes algunos ejemplos:
filter[tasaconv_gt]=2->tasaconvmayor que 2.filter[tasaconv_gte]=2->tasaconvmayor o igual que 2.filter[tasaconv_lt]=2->tasaconvmenor que 2.filter[tasaconv_lte]=2->tasaconvmenor o igual que 2.filter[tasaconv_neq]=2->tasaconvdistinto de 2.filter[descripcion_like]=PESO->descripcióncontienePESO.
Es decir, si quieres obtener todos los productos cuya referencia contenga pez, debes usar el filtro filter[referencia_like]=pez
🔎 Combinar filtros
Por defecto, cada filtro se aplica con una operación AND, lo que significa que se deben cumplir todos los filtros para que un registro sea devuelto. Sin embargo, puedes cambiar esto a OR. Por ejemplo, para obtener un listado de todas las divisas que contengan PESO en su descripción O QUE su tasaconv sea mayor que 2:
http://localhost:8000/api/3/divisas?filter[descripcion_like]=PESO&filter[tasaconv_gt]=2&operation[tasaconv_gt]=OR⬇️ Ordenación
Para obtener todos los registros que contengan en descripcion la palabra PESOS, ordenados por coddivisa de forma descendente, utiliza la siguiente consulta:
http://localhost:8000/api/3/divisas?filter[descripcion_like]=PESOS&sort[coddivisa]=DESCDel mismo modo que se pueden combinar filtros, también se pueden combinar ordenaciones, por ejemplo por precio y stock:
http://localhost:8000/api/3/productos?sort[precio]=ASC&sort[stockfis]=DESC🔢 Total de registros
En la respuesta de la API, el campo X-Total-Count en la cabecera te proporciona el número total de registros de la consulta, sin aplicar límites ni desplazamientos. Esto es útil para saber, por ejemplo:
- El total de productos disponibles si estás realizando una consulta sobre productos.
- El total de productos de la familia X si estás consultando los productos específicos de esa familia.