Peticiones a la API

URL de API

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

Cabeceras HTTP

http

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

shell

$ curl "https://api.aplazame.com/orders" \
    -H "Accept: application/vnd.aplazame.v1+json" \
    -H "Authorization: Bearer api_private_key"

python

import aplazame_sdk

client = aplazame_sdk.Client('api_private_key', ctype='json', version='1')

response = client.orders()

PHP

use Aplazame\Api\Client as AplazameClient;

$aplazameClient = new AplazameClient("https://api.aplazame.com", AplazameClient::ENVIRONMENT_PRODUCTION, "api_private_key");
$result = $aplazameClient->get("/orders");

C#

using Aplazame.Api;

Client client = new Client("https://api.aplazame.com", Client.EnvironmentProduction, "api_private_key");
dynamic result = client.Get("/orders");

Parámetro	Tipo	Requerido	Descripción
Accept	string	Sí	Especifica la versión de la API de Aplazame y el tipo de dato esperado.
Authorization	string	Sí	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 modo de pruebas).

http

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

shell

$ curl "https://api.aplazame.com/orders" \
    -H "Accept: application/vnd.aplazame.v1+json" \
    -H "Authorization: Bearer api_private_key"

$ curl "https://api.aplazame.com/orders" \
    -H "Accept: application/vnd.aplazame.v1+xml" \
    -H "Authorization: Bearer api_private_key"

python

import aplazame_sdk

client = aplazame_sdk.Client('api_private_key', version='1')

client = aplazame_sdk.Client('api_private_key', ctype='xml')

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	Version	Formato esperado	Valor
Accept	1	json	application/vnd.aplazame.v1+json
Accept	1	xml	application/vnd.aplazame.v1+xml

Decimales

tip

Es importante tener en cuenta que para las unidades monetarias, comisiones y descuentos se usan enteros, de modo que las cantidades que envían son céntimos. Por ejemplo, "12.50 €"‚ se envía como 1250.

shell

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

python

assert(12.50 != 1250)

Errores

Bad request

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"
  }
}

Unauthorized

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

{
  "error": {
    "message": "Authentication credentials were not provided.",
    "type": "UnauthorizedException"
  }
}

Not Found

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

{
  "error": {
    "fields": {
      "order__id": "145000006"
    },
    "message": "Object not found",
    "type": "ObjectNotFoundException"
  }
}

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

http

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

Not Found

$ curl "https://api.aplazame.com/orders?page=2" \
    -H "Accept: application/vnd.aplazame.v1+json" \
    -H "Authorization: Bearer api_private_key"

python

import aplazame_sdk

client = aplazame_sdk.Client('api_private_key')

response = client.orders(page=2)

# Build a URL query string from a dictionary
response = client.orders({
  'page': 2
})

PHP

use Aplazame\Api\Client as AplazameClient;

$aplazameClient = new AplazameClient("https://api.aplazame.com", AplazameClient::ENVIRONMENT_PRODUCTION, "api_private_key");
$result = $aplazameClient->get("/orders", ["page" => 2]);

C#

using Aplazame.Api;

Client client = new Client("https://api.aplazame.com", Client.EnvironmentProduction, "api_private_key");
dynamic result = client.Get("/orders", new {page => 2});

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.

cursor

"cursor": {
  "after": 3,
  "before": 1
}

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

paginación

"paging": {
  "count": 314,
  "next": "https://api.aplazame.com/orders?page=3",
  "previous": "https://api.aplazame.com/orders?page=1"
}

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.

http

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

shell

$ curl "https://api.aplazame.com/orders?id-startswith=e791f" \
    -H "Accept: application/vnd.aplazame.v1+json" \
    -H "Authorization: Bearer api_private_key"

python

response = client.orders({
  'id-startswith': 'e791f'
})

PHP

use Aplazame\Api\Client as AplazameClient;

$aplazameClient = new AplazameClient("https://api.aplazame.com", AplazameClient::ENVIRONMENT_PRODUCTION, "api_private_key");
$result = $aplazameClient->get("/orders", ["id-startswith" => "e791f"]);

C#

using Aplazame.Api;

Client client = new Client("https://api.aplazame.com", Client.EnvironmentProduction, "api_private_key");
dynamic result = client.Get("/orders?id-startswith=e791f");

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

http

GET /orders?confirmed-week_day=monday HTTP/1.1
Accept: application/vnd.aplazame.v1+json
Authorization: Bearer api_private_key
Host: api.aplazame.com

shell

$ curl "https://api.aplazame.com/orders?confirmed-week_day=monday" \
    -H "Accept: application/vnd.aplazame.v1+json" \
    -H "Authorization: Bearer api_private_key"

python

response = client.orders({
  'confirmed-week_day': 'monday'
})

PHP

use Aplazame\Api\Client as AplazameClient;

$aplazameClient = new AplazameClient("https://api.aplazame.com", AplazameClient::ENVIRONMENT_PRODUCTION, "api_private_key");
$result = $aplazameClient->get("/orders", ["confirmed-week_day" => "monday"]);

C#

using Aplazame.Api;

Client client = new Client("https://api.aplazame.com", Client.EnvironmentProduction, "api_private_key");
dynamic result = client.Get("/orders?confirmed-week_day=monday");

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

http

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

shell

$ curl "https://api.aplazame.com/orders?confirmed-gte=2015-10-02T18:15:45.101838Z" \
    -H "Accept: application/vnd.aplazame.v1+json" \
    -H "Authorization: Bearer api_private_key"

python

response = client.orders({
  'confirmed-gte': '2015-10-02T18:15:45.101838Z'
})

PHP

use Aplazame\Api\Client as AplazameClient;

$aplazameClient = new AplazameClient("https://api.aplazame.com", AplazameClient::ENVIRONMENT_PRODUCTION, "api_private_key");
$result = $aplazameClient->get("/orders", ["confirmed-gte" => "2015-10-02T18:15:45.101838Z"]);

C#

using Aplazame.Api;

Client client = new Client("https://api.aplazame.com", Client.EnvironmentProduction, "api_private_key");
dynamic result = client.Get("/orders?confirmed-gte=2015-10-02T18:15:45.101838Z");

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.