Peticiones a la API

URL de API

La URL del servicio API de Aplazame se encuentra disponible en https://api.aplazame.com.

Cabeceras

GET /orders HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com
Parámetro Tipo Requerido Descripción
Accept string si Especifica la versión de la API de Aplazame y el tipo de dato esperado
Authorization string si Tipo y clave de acceso

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Aplazame-Media-Type: aplazame.v1

OAuth2 es un estandard abierto de autorizacion definido en la RFC 6749.

OAuth2 es más sencillo que OAuth1 y proporciona mayor nivel de seguridad.

Versionado

Se utiliza la cabecera Accept tanto para indicar la versión de la API, el formato (y el módo de pruebas)

GET /orders HTTP/1.1
Accept: application/vnd.aplazame.v1+(json|xml)
Authorization: Bearer api_private_key
Host: api.aplazame.com

Aunque Aplazame soporta el versionado mediante URL (p.e. https://api.aplazame.com/v1/orders), se considera buena práctica usar la cabecera Accept en la petición para especificar el tipo y el formato esperado de la respuesta de la API.

Si no se indica la versión de la API, se aplicará más reciente. Esto no es aconsejable ya que una nueva versión podría dejar obsoleto alguna propiedad.

Tipos de formato soportados

Cabecera Versión Formato esperado Valor
Accept 1 json application/vnd.aplazame.v1+json
Accept 1 xml application/vnd.aplazame.v1+xml

Decimales

$ if ((`bc <<< "12.50!=1250"`)); then echo "beep beeeeeeep!!!"; fi

Errores

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
X-Aplazame-Media-Type: aplazame.v1

{
  "error": {
    "fields": {
      "articles": [
        "This field is required."
      ]
    },
    "message": "API validation error",
    "type": "ApiValidationException"
  }
}

Listado de códigos de error devueltos por la API.

Código Error Significado
400 Bad Request Si hay algún error en los datos enviados
401 Unauthorized No se ha enviado el token (public/private key) o el que se ha enviado no es válido
403 Forbidden Aún siendo válido el token, la operación puede ser rechazada por permisos.
404 Not Found No se ha encontrado el objeto o recurso.
405 Method Not Allowed El método no está disponible para la url indicada (GET/POST/...)
406 Not Acceptable La cabecera Accept no es válida ver cabeceras
408 Request timeout Ha expirado el tiempo máximo de espera para la petición.
409 Conflict Indica que se ha producido un conflicto con la petición, su significado depende del contexto.
415 Unsupported Media Type No hay soporte para el tipo indicado por la cabecera 'Content-Type'
429 Too Many Requests Se están recibiendo demasiadas peticiones.
500 Internal Server Error Error en el servidor de la API, esto puede ser un fallo en la implementación, un problema puntual de la red, etc.
503 Service Unavailable Fuera de servicio por mantenimiento.

Paginación

GET /orders?page=2 HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Aplazame-Media-Type: aplazame.v1

{
  "cursor": {
    "after": 3,
    "before": 1
  },
  "paging": {
    "count": 314,
    "next": "https://api.aplazame.com/orders?page=3",
    "previous": "https://api.aplazame.com/orders?page=1"
  },
  "results": []
}
Parámetro Tipo Descripción
cursor object Puntero de paginación
paging object Estado de paginación
results collection Listado de tiendas

Desglose: cursor

Parámetro Tipo Descripción
after integer Índice de la página anterior.
before integer Índice de la página siguente.

Desglose: paging

Parámetro Tipo Descripción
count integer Número de elementos devueltos.
next URL URL de la API a la siguente página de resultados.
previous URL URL de la API a la página anterior de resultados.

Filtros

Los filtros en las consultas de listados se indican mediante parámetros de la URL. El formato de cada parametro está compuesto por la entidad, el tipo de búsqueda y el valor a buscar.

GET /orders?propiedad-busqueda=valor

En el siguente ejemplo, la petición devolverá todos los pedidos cuyo id comienze por 'e791f'. Si se omite el tipo de concordancia, se usará exact.

GET /orders?id-startswith=e791f HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com

Si se especifican varios filtros, el resultado devolverá la combinación aditiva de ellos.

GET /orders?id-startswith=e791f&id-endswith=4ff4g HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com

Búsqueda de texto

Término Uso Descripción
exact name-exact=AplaZame Coincidencia exacta
iexact name-iexact=aplazame Coincidencia exacta no sensible a mayúsculas/minúsculas
regex name-regex=^[A-Z].*$ Expresión regular sensible a mayúsculas/minúsculas.
iregex name-iregex=^[a-z].*$ Expresión regular no sensible a mayúsculas/minúsculas.
contains name-contains=plaZa Contiene la cadena especificada no sensible a mayúsculas/minúsculas
icontains name-icontains=plaza Contiene la cadena especificada.
startswith name-startswith=Apla Comienza por la cadena especificada.
istartswith name-istartswith=apla Comienza por la cadena especificada no sensible a mayúsculas/minúsculas.
endswith name-endswith=Zame Termina por la cadena especificada.
iendswith name-iendswith=zame Termina por la cadena especificada no sensible a mayúsculas/minúsculas.
in name-in=AplaZame,Aplazar Coincide con alguna de las opciones separadas por comas.
search name-search=Ap Cadena de texto a buscar

Por fecha

GET /orders?confirmed-week_day=monday HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com
Término Uso Descripción
year created-year=2015 Fechas cuyo año coincida con el indicado.
month created-month=10 Fechas cuyo mes coincida con el indicado.
week_day created-week_day=monday Día de la semana, las opciones son:
monday, tuesday, wednesday, thursday, friday, saturday, sunday
day created-day=2 Fechas cuyo día del mes coincida con el indicado.
hour created-hour=14 Fechas cuya hora coincida con la indicada.

Nulo

Término Uso Descripción
isnull confirmed-isnull=yes Filtrar por campos nulos, si O no

Rangos de valores

GET /orders?confirmed-gte=2015-10-02T18:15:45.101838Z HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com
Término Uso Descripción
exact total_amount-exact=10000 Valor exacto
gt total_amount-gt=8000 Mayor qué
gte total_amount-gte=10000 Mayor o igual que
lt total_amount-lt=12000 Menor que
lte total_amount-lte=10000 Menor o igual que