DonDemand API maneja múltiples compañías de forma independiente una de otras. Al conectarse con el API, es importante mantener identificada la compañía a la cual desea conectarse.
URL del API a utilizar. Cuenta con un entorno de Pruebas y un entorno de Producción.
https://ondemand-api.manzanares.com.vehttps://api.simgulary.ioPara efectos de la documentación, los Request toman como base la URI completa incluyendo la versión de API. Es decir, se debe concatenar lo siguiente anttes de cada ruta:
{host}/api/{version}/
{info} Ejemplo de Request en entorno de Pruebas:
GET https://ondemand-api.manzanares.com.ve/api/v3/companies/3
En el entorno de pruebas, se utiliza companyId=3
Se utiliza Json Web Token (JWT) para usuarios autenticados. Tras el login, se obtine un JWT para identificar el usuario en los request posteriores al API. El token debe ser agregado como cabecera para los EndPoints que lo necesiten.
Se debe incluir una cabecera en cada request HTTP que necesite autenticación con el fin de identificar al usuario en el servidor.
{info} Agregar la cabecera
Authorization: Bearer <token>en los request que necesiten autenticación.
Existen múltiples tipos de datos manejados en el API. Para efectos de la documentación, se utilizarán nombres para representar algunos de ellos:
{año}-{mes}-{día} {horas}-{minutos}-{segundos}. Ejemplos: 2019-12-31 23:59:59,
2019-01-01 09:01:00{info} Todos los modelos poseen un atributo
id, que representa un identificador único.
Algunos valores son almacenados en un formato específico, o realizando una conversión de datos específicas. Esos valores se detallan a continuación:
price_e2 y se utiliza para representar
precios. El valor en cuestión se encuentra multiplicado por 10 elevado a la 2, o 10^2. Por
ejemplo, si se obtiene double total = 45.661, entonces long price_e2 = (long) (45.661 * 100) = 4566. El resultado es almacenado como entero de 64 bits, y todos los posibles decimales son
truncados. Para obtejer el valor real para mostrar en pantalla, es necesario realizar la operación
inversa double real_price = price_e2 / 100.0 => real_price = 4566 / 100.0 = 45.66. Es
importante almacenar el resultado en una variable de 64 bits.latitude_e6 y se utiliza para representar
coordenadas angulares. El valor en cuestión se encuentra multiplicado por 10 elevado a la 6, o
10^6. Por ejemplo, si se obtiene latitude = 12.5486927, entonces latitude_e6 = (12.5486927 * 1000000) = 12548692. El resultado es almacenado como entero de 32 bits, y todos los
posibles decimales son truncados. Para obtejer el valor real para mostrar en
pantalla, es necesario realizar la operación inversa double latitude = latitude_e6 / 1000000.0 =>
latitude = 12548692 / 1000000.0 = 12.548692.Las respuestas globales pueden ser generadas en cualquier request del API. Esto significa que no dependen de ningún request en específico, y deben ser manejadas en todos los request del lado del cliente.
Los EndPoint de tipo Lista pueden soportar paginación. Es decir, todos ellos soportan una variedad de parámetros especificados a continuación.
{
"limit" : "integer|min:0",
"sort_by": "string",
"page" : "integer|min:1",
"search" : "string"
}limit (opcional): Cantidad de elementos a mostrar por página. El valor mímimo permitido es 5.
Si el valor suministrado es menor al mínimo, se toma el valor mínimo para la paginación. Si este
parámetro es omitido, el valor por defecto es limit=10. Sin embargo, si se especifica limit=0,
el API devuelve una respuesta sin paginación, es decir, la paginación es desactivada.
sort_by (opcional): Columna por la cual ordenar los datos en el paginador. Además, se puede
especificar el orden (ascendente o descendente) separado con una coma. Por ejemplo:
sort_by=updated_at ordena los datos por la columna updated_at de forma ascendente
(equivalente a sort_by=updated_at,asc). Si este parámetro es omitido, el valor por defecto es:
sort_by=id,desc.
page (opcional): Número de página a mostrar. Si este parámetro es omitido, el valor por
defecto es: page=1
search (opcional): Algunos modelos soportan filtro de contenido. Éste parámetro produce una
búsqueda en el contenido de los elementos y devuelve los datos cuyo contenido contenga el valor
suministrado. La comparación se realiza con iLike %<search_value>%.
{info} Se pueden utilizar parámetros que correspondan a atributos del modelo llamados filtros avanzados, los cuales se describen en Filtros avanzados.
Ninguno{primary} Ejemplo de respuesta de requests con paginación
{
"current_page" : 1,
"data" : ["{object1}", "{object2}", "..."],
"first_page_url": "<url>",
"from" : 1,
"last_page" : 1,
"last_page_url" : "<url>",
"next_page_url" : "<url>|null",
"path" : "<url>",
"per_page" : 5,
"prev_page_url" : "<url>|null",
"to" : 1,
"total" : 1
}last_page (inclusive).per_page == 15, en la página 1 encontramos los elementos
del 1 al 15 (inclusive), en la página 2 encontramos los elementos del 16 al 30 y así sucesivamente.
Sin embargo, en la última página, es posible que no existan suficientes elementos para llenar toda
la página, lo cual puede ser validado con los demás atributos del paginador.per_page == 15, en la página 1 from == 1, en la página 2
from == 16 y así sucesivamente.per_page == 15 en una lista de 40 elementos, en la página 1
to == 15, en la página 2 to == 30. Sin embargo, en la última página (página 3 del ejemplo), no
existen suficientes elementos para llenar toda la página. En dado caso, el valor de este atributo
coincide con la posición del último elemento: to == 40. Además se puede calcular la cantidad de
elementos en la página aplicando: count = 1 + to - from.last_page == 1. La cantidad de páginas depende
del valor per_pageLa paginación soporta filtros avanzados por columna, los cuales son inclusivos entre sí. Esto permite utilizar las siguientes condiciones en las columnas de los modelos:
mode=all indica que no se debe omitir
ningún elemento, lo que provoca que incluso los elementos eliminados con soft-delete sean
mostrados. Por otra parte, mode=deleted muestra únicamente los elementos eliminados con
soft-delete. Si el modelo no soporta soft-delete, éste parámetro no funciona.{columna} se refiere
al atributo del modelo, como id, updated_at, etc. El {operador} se utiliza para realizar la
comparación, y el elemento se agrega al paginador si se cumple que el {valor} utilizando el
{operador} es true. Por ejemplo: age=25 agrega al paginador sólo los elementos cuyo atributo
age tenga un valor igual a 25 age == 25. Se pueden utilizar otros operadores, age=>25 agrega
sólo los elementos cuyo atributo age tenga un valor mayor a 25 age > 25. Los operadores
soportados son: =, <, >, <=, >=, <>, !=, <=>, like, like binary, not like,
ilike, &, |, ^, <<, >>, rlike, regexp, not regexp, ~, ~\*, !~, !~\*,
similar to, not similar to, not ilike, ~~\*, !~~\*, between, flag. Ejemplos
adicionales: age=between 25,40 (elementos cuyo valor age se encuentran entre 25 y 40
(inclusive); age=flag 1,0 aplica la condición: (age & 1) == 0, lo cual devuelve los elementos
cuyo age es par.Nota: Puedes acceder a columnas de modelos en cascada, por ejemplo, si queremos obtener los clientes
con órdenes del 1/1/2020, podemos especificar companies/3/clients?order.updated_at=2020-01-01. Se
utiliza . o - para indicar una columna en cascada.
Prepara el endpoint para que contenga en su respuesta, las relaciones especificadas.
Por ejemplo, la clase Order contiene la relación Order-Client, se puede solicitar al API una Orden
con su respectivo Client agregando with=client. Si se desea, puedes especificar carga de
relaciones en cascada con . o -: with=client-account, y más de una relación separada por
comas: with=client.account,providers.account