Use of Query Strings

Query strings allow you to make GET requests to Tilby's APIs, filtering and ordering only the desired results.

For example, you can request all sales created by a specific date or a customer who has a specific email address. Or you can limit and sort the results.

The use is extremely simple and is highly recommended to improve integration efficiency.

Query Strings can be used in order to query GET API. Only APIs that returns multiple object can accept query string.

You can not use Query Stings with

POST / PUT request
GET request refered to spiecified entity such as /v2/name_entity/:id_entity.

Pagination

To improve the efficiency of the integrations, the Tilby APIs return paginated content. Using pagination and the correct number of results per page will allow you to achieve efficient integrations.

Pagination can be set using three query string parameters:

pagination: boolean if it is set with true pagination is enabled
per_page: integer it's the maximum number of elements that can be returned (limit in sql)
page: integer it's the number of page that must be returned (offset)

If Pagination is not set by default the maximum elements that can be returned is: 1000

Example

GET /v2/items?pagination=true&page=0&per_page=10 HTTP/1.1
Accept: application/json
Authorization: Bearer your_token
Host: api.scloby.com

curl --request GET \
  --url 'https://api.scloby.com/v2/items?pagination=true&page=0&per_page=10' \
  --header 'Authorization: Bearer your_token'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.scloby.com/v2/sales');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'pagination' => 'true',
  'page' => '0',
  'per_page' => '10'
]));

$request->setHeaders([
  'Authorization' => 'Bearer your_token'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

PropertyName query

If you need to get results based on a property's scheme you can add one or more attribute to search like this: name_property=value_to_search. It's important that the property is present in the schema of the entity. You can consult the list of available fields in each API.

if you need to check a not null value you can use this format to query the api: name_property=notnull

It's possibile to search nested attributes. You can do that in this way: name_object_property.name_property_nested = value.

Example:

You need to get all the open orders, created by your external integration, that belong to a specific customer_id = 1 . You can do it by setting query string like this: external_id=notnull&status=open&order_customer.id=1

GET /v2/orders?external_id=1234&status=open&order_customer.id=1&pagination=true&page=0&per_page=10 HTTP/1.1
Accept: application/json
Authorization: Bearer your_token
Host: api.scloby.com

curl --request GET \
  --url 'https://api.scloby.com/v2/orders?external_id=1234&status=open&order_customer.id=1&pagination=true&page=0&per_page=10' \
  --header 'Authorization: Bearer your_token'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.scloby.com/v2/orders');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'external_id' => '1234',
 	'status' => 'open',
  'order_customer.id' => 1,
  'pagination' => 'true',
  'page' => '0',
  'per_page' => '10'
]));

$request->setHeaders([
  'Authorization' => 'Bearer your_token'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

PropertyName_like

If you need to search for partial text of a paramter you can use 'like' query string. The sintaxt is propertyName+ "_"+ like.
It's important that the property is present in the schema of the entity. You can consult the list of available fields in each API.

Example

If you need to search orders that begins with the text: "Tilby Order" you can use this query string: name_like=partial_text

GET /v2/orders?name_like=Tilby%20Order&pagination=true&page=0&per_page=10 HTTP/1.1
Accept: application/json
Authorization: Bearer your_token
Host: api.scloby.com

curl --request GET \
  --url 'https://api.scloby.com/v2/orders?name_like=Tilby%20Order&pagination=true&page=0&per_page=10' \
  --header 'Authorization: Bearer your_token'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.scloby.com/v2/orders');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'name_like' => 'Tilby Order',
  'pagination' => 'true',
  'page' => '0',
  'per_page' => '10'
]));

$request->setHeaders([
  'Authorization' => 'Bearer your_token'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

PropertyName_max and PropertyName_since

Use _max when you want any results that is lower than the value.

Use _since when you want any results that is greater than the value.

If you use both the result will be between the values.

You can consult the list of available fields in each API.

Example

If you need all the sales closed in a specifc range of time you can use closed_at_max and closed_at_since to get all the results in that range.

GET /v2/sales?closed_at_since=2022-07-29T00%3A00%3A00Z&closed_at_max=2022-07-29T23%3A59%3A59Z&pagination=true&page=0&per_page=10 HTTP/1.1
Accept: application/json
Authorization: Bearer your_token
Host: api.scloby.com

curl --request GET \
  --url 'https://api.scloby.com/v2/sales?closed_at_since=2022-07-29T00%3A00%3A00Z&closed_at_max=2022-07-29T23%3A59%3A59Z&pagination=true&page=0&per_page=10' \
  --header 'Authorization: Bearer your_token'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.scloby.com/v2/sales');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'closed_at_max' => '2022-07-29T23:59:59Z',
  'pagination' => 'true',
  'page' => '0',
  'per_page' => '10',
  'closed_at_since' => '2022-07-29T00:00:00Z'
]));

$request->setHeaders([
  'Authorization' => 'Bearer your_token'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Order results

API results can be ordered by descendent or ascendent order using one of the parameters's entity scheme. You can consult the list of available fields in each API.

descedent : orderby_desc = propertyName
ascendent: orderby_asc = propertyName

Example:

If you want to get sales ordered by their closing time, you have to consider the parameter closed_at. Closed_at is set when the sale has been closed otherwise is null. So you need to order using this field and to ensure to not checking null values, you need to set also a query parameter check: closed_at = notnull

GET /v2/sales?pagination=true&per_page=10&page=0&orderby_desc=closed_at&closed_at=notnull HTTP/1.1
Accept: application/json
Authorization: Bearer your_token
Host: api.scloby.com

curl --request GET \
  --url 'https://api.scloby.com/v2/sales?orderby_asc=closed_at&closed_at=notnull&pagination=true&page=0&per_page=10' \
  --header 'Authorization: Bearer your_token'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.scloby.com/v2/sales');
$request->setRequestMethod('GET');
$request->setQuery(new http\QueryString([
  'orderby_desc' => 'closed_at'
  'closed_at' => 'notnull',
  'pagination' => 'true',
  'page' => '0',
  'per_page' => '10',
  
]));

$request->setHeaders([
  'Authorization' => 'Bearer your_token'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();