API Requests

API URL

The URL of Aplazame’s API service is available at https://api.aplazame.com.

HTTP Headers

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");

Parameter	Type	Required	Description
Accept	string	Yes	Specifies the Aplazame API version and the datatype expected.
Authorization	string	Yes	Type and access key.

Response

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

OAuth2 is an open standard for authorisation defined in RFC 6749.

OAuth2 is easier to work with than OAuth1 and provides much better security.

Versioning

The Accept header is used to indicate the API version, expected content type (and sandbox mode).

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')

Although versioning via URL is currently allowed (e.g. https://api.aplazame.com/v1/orders), it is better practice to use the Accept header in the request to specify the type and format of the API service response.

If the API version is not indicated in the header or via URL, the latest version of the API will be activated. Since a new version of the API can deprecate certain fields, it is recommended you always specify the API version

Format types allowed

Header	Version	Expected format	Value
Accept	1	json	application/vnd.aplazame.v1+json
Accept	1	xml	application/vnd.aplazame.v1+xml

Decimals

tip

All amounts related to taxes, discounts and prices will be formatted as an integer including two decimal places (i.e. amounts in cents). For example, if an item has a price of €12.50 should be formatted as an integer 1250.

shell

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

python

assert(12.50 != 1250)

Errors

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

List of error codes returned by the API.

Code	Error	Meaning
400	Bad Request	If the data have not been correctly validated.
401	Unauthorized	If the token (public/private key) is not sent in the request or is wrong.
403	Forbidden	If you do not have permission to do this operation.
404	Not Found	If the object or the resource is not found.
405	Method Not Allowed	You tried to access with an invalid method (GET/POST/...).
406	Not Acceptable	The Accept header is invalid see headers.
408	Request timeout	The server timed out waiting for the request.
409	Conflict	Indicates that the request could not be processed because of a conflict in the request.
415	Unsupported Media Type	There is no support for the content type indicated in the Content-Type header.
429	Too Many Requests	If multiple simultaneous requests are made.
500	Internal Server Error	Error in the API server. This may be caused by an implementation error, a temporary network issue, etc. Please try again later.
503	Service Unavailable	Temporarily offline for maintenance. Please try again later.

Pagination

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});

Response

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": []
}

Parameter	Type	Description
cursor	object	Pagination cursor object
paging	object	Pagination status
results	collection	List of stores

cursor

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

Parameter	Type	Description
after	integer	Index of the previous page.
before	integer	Index of the next page.

paging

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

Parameter	Type	Description
count	integer	Number of items found.
next	URL	API URL (endpoint) to the next page of results.
previous	URL	API URL (endpoint) to the previous page of data.

Filters

The filters of the list queries are indicated in the URL parameters. The parameter format is comprised of the entity, lookup type and value.

GET /orders?propiedad-busqueda=valor

In the following example, the request will return all orders whose id starts with 'e791f'. If the match type is omitted, exact will be used.

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");

If various filters are specified, the result will return a combination of all of them.

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

Text search

Term	Usage	Description
exact	name-exact=AplaZame	Exact match.
iexact	name-iexact=aplazame	Case-insensitive* exact match.
regex	name-regex=^[A-Z].*$	Case-sensitive regular expression.
iregex	name-iregex=^[a-z].*$	Case-insensitive regular expression.
contains	name-contains=plaZa	String containing a case-insensitive value.
icontains	name-icontains=plaza	String containing a case-sensitive value.
startswith	name-startswith=Apla	String starts with specified value.
istartswith	name-istartswith=apla	String starting with case-insensitive value.
endswith	name-endswith=Zame	String ending with value.
iendswith	name-iendswith=zame	String ending with case-insensitive value.
in	name-in=AplaZame,Aplazar	Matches any of the comma-separated values.
search	name-search=Ap	String search value.

By date

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");

Term	Usage	Description
year	created-year=2015	Dates whose year matches the value entered.
month	created-month=10	Dates whose month matches the value entered.
week_day	created-week_day=monday	Day of the week; the choices are: monday, tuesday, wednesday, thursday, friday, saturday, sunday.
day	created-day=2	Dates whose day matches the value entered.
hour	created-hour=14	Dates whose time matches the value entered.

Nulo

Term	Usage	Description
isnull	confirmed-isnull=yes	Filter by null fields, yes OR no

Value ranges

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");

Term	Usage	Description
exact	total_amount-exact=10000	Exact value.
gt	total_amount-gt=8000	Greater than.
gte	total_amount-gte=10000	Greater than or equal to.
lt	total_amount-lt=12000	Less than.
lte	total_amount-lte=10000	Less than or equal to.