...
Instructions
| Sommaire | ||
|---|---|---|
|
POST {url}/localtrac/login | ||||||
|---|---|---|---|---|---|---|
The authentication is used to obtain a valid token that your application will use to connect to any routes of the API. The token has a shelf life of 15 minutes starting at the moment of acquisition, after which it must be re-acquired. When you use the token in a request, you are connected on behalf of the the user provided during the authentication and are restricted to the limitation of this user (see users roles and their permissions). | ||||||
Request | ||||||
Headers | ||||||
Accept | application/json | |||||
Content-type | application/json | |||||
Body | ||||||
| ||||||
username | Username of the user to connect on behalf-of | |||||
password | Password of the user | |||||
Response (200) - Success | ||||||
Headers | ||||||
Content-type | application/json | |||||
Cache-Control | no-cache,private | |||||
Body | ||||||
| ||||||
success | Token has been acquired | |||||
token | The token to use within the Authorization header for the request | |||||
Response (401,503) - Authorized access | ||||||
Headers | ||||||
Content-type | application/json | |||||
Cache-Control | no-cache,private | |||||
Connection | close | |||||
Body | ||||||
| ||||||
code | Error codes:
| |||||
| Developer-friendly description of the code of error. Ex: “Invalid credential provided” | |||||
Locations
...
GET {url}/localtrac/locations
...
Request
...
Query
...
p (optionnal)
...
<int> Page to return
...
Headers
...
Authorization
...
<token> obtained during the Authentication
...
Accept
...
application/json
...
Response (200) - Success
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
[
{
"uuid": <(string) uuid of the location>,
"name": <(string) Name of the location or business>,
"address": <(string) Compressed address)>,
"storecode": <(string) Unique store code>,
"active": <(bool) Location active/inactive)>
},
<...>
] |
...
uuid
...
LOCALTRAC unique identifier (uuid) of the location. This is the uuid you should use for any further request that requires a <location_uuid> within the url.
...
name
...
Name of the location in the language (locale) of the location based on the language field in LOCALTRAC. If the location does not have a name, it will return the Business name.
If the location has no language (locale), the French version is returned by default.
...
address
...
One liner address of the location.
...
storecode
...
External id given by the client when the location was created or when imported in LOCALTRAC from a directory.
...
active
...
Boolean value representing the status of the location, true for active and false for inactive. When a location is set as inactive, it is not monitored within any directories.
...
GET {url}/localtrac/location/<location_uuid>
...
This route returns all location “Information” fields, with the exception of schedule related information.
...
Request
...
Headers
...
Authorization
...
<token> obtained during the Authentication
...
Accept
...
application/json
...
Response (200) - Success
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body (Example)
This example is a fake location generated by our test system.
...
| Bloc de code | ||
|---|---|---|
| ||
{
"uuid": "b11f9a4b-2b50-3e65-ae90-42fcef743ace",
"storeCode": "GV86170S47S60498U6YSU595",
"name": {
"en_CA": "D'Amore, Deckow and Kozey #540",
"fr_CA": "D'Amore, Deckow and Kozey #540"
},
"address": {
"address1": "77421 Route Sylvie, St-Augustin-des-Pins, ON T1T 7R3",
"address2": "",
"city": "Saint-Manon-du-Ha! Ha!",
"state": "ON",
"country": "CA",
"zipcode": "H5M9T4",
"lat": "-69.56438",
"long": "-68.360965"
},
"description": {
"fr_CA": "Eligendi ducimus sit totam aperiam ex est aliquid ut. Suscipit sit sint necessitatibus totam sequi. Et hic fugit dolore voluptas. Deleniti assumenda sunt sed maiores sunt distinctio.",
"en_CA": "Iste qui quia expedita sed. Ipsam quis fuga ex occaecati. Est reiciendis est neque corporis quia."
},
"communication": {
"contactEmail": "mueller.tianna@wunsch.info",
"primaryPhone": "(810) 594-0448",
"secondaryPhones": [
"(810) 555-5215"
],
"fax": ""
},
"urls": {
"website": "http:\/\/www.herman.com\/molestiae-illo-quia-hic-ducimus\/D%27Amore%2C+Deckow+and+Kozey+%23540",
"facebook": "https:\/\/www.facebook.com\/754553701341",
"twitter": "https:\/\/twitter.com\/909074187486",
"linkedin": "https:\/\/www.linkedin.com\/181822059751",
"instagram": "https:\/\/www.instagram.com\/myloftssalonstudios\/306493669050",
"youtube": "https:\/\/www.youtube.com\/channel\/302619054339",
"pinterest": "https:\/\/www.pinterest.ca\/piscinestrevi\/37867198515",
"tripadvisor": "https:\/\/www.tripadvisor.ca\/893155122501"
},
"payments": {
"cash": true,
"interact": true,
"visa": true,
"mastercard": false,
"americanExpress": true,
"paypass": true
},
"active": true
} |
...
uuid
...
LOCALTRAC unique identifier (uuid) of the location. This is the uuid you should use for any further request that requires a <location_uuid> within the url.
...
storecode
...
External id given by the client when the location was created or when imported in LOCALTRAC from a directory.
...
name
...
Array of all the location name translations. Each row of the sub array is an associative value of <locale> : <name>.
We currently only support <locale> fr_CA and en_CA.
...
address
...
Array containing the full address.
...
description
...
Array of all the location descriptions. Each row of the sub array is an associative value of <locale> : <description>.
We currently only support <locale> fr_CA and en_CA.
...
communication
...
An associative array for the location contact information.
Supported keys:
contactEmail: primary email address
primaryPhone: primary phone
secondaryPhones: An array of alternative phones. Please note that we currently only accept 2 secondary phones due to directory restrictions
fax: fax number
...
urls
...
An associative array for websites and social media URLs.
Supported keys:
website: Main website of the company or location
facebook
twitter
linkedin
instagram
youtube
pinterest
tripadvisor
...
payments
...
An associative array of payment methods. The value is a Boolean, true when payment method is accepted or false when it’s not.
Supported keys:
cash
interact
visa
mastercard
americanExpress
paypass
...
active
...
Boolean value representing the status of the location, true for active and false for inactive. When a location is set as inactive, it is not monitored within any directories.
...
Response (403) - Forbidden access
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"message": "You do not have the required permission to obtain this resource: location(<(string) uuid of the location>)"
} |
...
POST|PUT {url}/localtrac/location
...
A POST|PUT on this route indicates that you want to create a new location.
Each sub key (name, address, description, communication, urls, …) can be updated individually. Any sub key not provided will be ignored and will remain unchanged.
...
Request
...
Headers
...
Authorization
...
<token> obtained during the Authentication
...
Accept
...
application/json
...
Content-Type
...
application/json
...
Body (Example)
This example is a fake location generated by our test system.
...
| Bloc de code | ||
|---|---|---|
| ||
{
"business": "UUID of the business"
"locale": "Either fr_CA, en_CA or en_US"
} |
...
name (optionnal)
...
Array of all the location name translations. Each row of the sub array is an associative value of <locale> : <name>.
We currently only support <locale> fr_CA and en_CA.
...
address (optionnal)
...
Array containing the full address.
...
Response (200) - Success
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"uuid": "UUID of the newly created Location"
} |
...
Response (400) - Validation Error
This scenario happens if you sent any content who fails the minimum validation process. For instance, providing a wrong business uuid or an empty one would lead to the following result
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"message": "Provided data contains error(s). See each entry in [errors]",
"errors": {
"business": "This value should not be blank."
}
} |
...
message
...
Always the same error message, indicating that an error happened during the validation process
...
errors
...
An associative array where the key represents the logical path to the data in error and the value represents the error found with the given data.
If a key contains “.” character, this means nested array. In the case of an array without keys, the logical number would be taken (ex: communication.secondaryPhones.1 would represent the first entry provided in secondaryPhones)
...
Response (403) - Forbidden access
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"message": "You do not have the required permission to obtain this resource: location(<(string) uuid of the location>)"
} |
...
POST {url}/localtrac/location/<location_uuid>
...
A POST on this route indicates that you want to update the location fields.
Each sub key (name, address, description, communication, urls, …) can be updated individually. Any sub key not provided will be ignored and will remain unchanged.
...
Request
...
Headers
...
Authorization
...
<token> obtained during the Authentication
...
Accept
...
application/json
...
Content-Type
...
application/json
...
Body (Example)
This example is a fake location generated by our test system.
...
| Bloc de code | ||
|---|---|---|
| ||
{
"name": {
"en_CA": "D'Amore, Deckow and Kozey #540",
"fr_CA": "D'Amore, Deckow and Kozey #540"
},
"address": {
"address1": "77421 Route Sylvie, St-Augustin-des-Pins, ON T1T 7R3",
"address2": "",
"city": "Saint-Manon-du-Ha! Ha!",
"state": "ON",
"country": "CA",
"zipcode": "H5M9T4",
"lat": "-69.56438",
"long": "-68.360965"
},
"description": {
"fr_CA": "Eligendi ducimus sit totam aperiam ex est aliquid ut. Suscipit sit sint necessitatibus totam sequi. Et hic fugit dolore voluptas. Deleniti assumenda sunt sed maiores sunt distinctio.",
"en_CA": "Iste qui quia expedita sed. Ipsam quis fuga ex occaecati. Est reiciendis est neque corporis quia."
},
"communication": {
"contactEmail": "mueller.tianna@wunsch.info",
"primaryPhone": "(810) 594-0448",
"secondaryPhones": [
"(810) 555-5215"
],
"fax": "(111) 111-1111"
},
"urls": {
"website": "http:\/\/www.herman.com\/molestiae-illo-quia-hic-ducimus\/D%27Amore%2C+Deckow+and+Kozey+%23540",
"facebook": "https:\/\/www.facebook.com\/754553701341",
"twitter": "https:\/\/twitter.com\/909074187486",
"linkedin": "https:\/\/www.linkedin.com\/181822059751",
"instagram": "https:\/\/www.instagram.com\/myloftssalonstudios\/306493669050",
"youtube": "https:\/\/www.youtube.com\/channel\/302619054339",
"pinterest": "https:\/\/www.pinterest.ca\/piscinestrevi\/37867198515",
"tripadvisor": "https:\/\/www.tripadvisor.ca\/893155122501"
},
"payments": {
"cash": true,
"interact": true,
"visa": true,
"mastercard": false,
"americanExpress": true,
"paypass": true
},
"schedules": {
"sunday": [
{
"start": "null",
"end": "null"
}
],
"monday": [
{
"start": "02:00",
"end": "23:00"
}
],
"tuesday": [
{
"start": "02:00",
"end": "23:59"
}
],
"wednesday": [],
"thursday": [],
"friday": [
{
"start": "08:00",
"end": "23:00"
}
],
"saturday": [
{
"start": "08:00",
"end": "23:00"
}
]
}
} |
...
name (optionnal)
...
Array of all the location name translations. Each row of the sub array is an associative value of <locale> : <name>.
We currently only support <locale> fr_CA and en_CA.
...
address (optionnal)
...
Array containing the full address.
...
description (optionnal)
...
Array of all the location descriptions. Each row of the sub array is an associative value of <locale> : <description>.
We currently only support <locale> fr_CA and en_CA.
...
communication (optionnal)
...
An associative array for the location contact information.
Supported keys:
contactEmail: primary email address
primaryPhone: primary phone
secondaryPhones: An array of alternative phones. Please note that we currently only accept 2 secondary phones due to directory restrictions
fax: fax number
...
urls (optionnal)
...
An associative array for websites and social media URLs.
Supported keys:
website: Main website of the company or location
facebook
twitter
linkedin
instagram
youtube
pinterest
tripadvisor
...
payments (optionnal)
...
An associative array of payment methods. The value is a Boolean, true when payment method is accepted or false when it’s not.
Supported keys:
cash
interact
visa
mastercard
americanExpress
paypass
...
Schedules (optionnal)
...
An associative array where each key is one day of the week. The value of each key is a range of opening hours with “start” and “end” key for each period within a day. The sub array allows multiple values since a day can be opened and closed multiple times per day.
If nothing is provide for a day, this means the day is closed
If array with “start: null” and “end: null” is provided, this means the day is closed
If “start: HH:ii” and “end: HH:ii” is provided, this interval will be considered open. Multiple interval can be provided.
...
Response (200) - Success
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"name": "Name updated",
"address": "Address updated",
"description": "Description updated",
"communication": "Communication updated",
"urls": "Urls updated",
"payments": "Payments updated"
} |
...
Response (400) - Validation Error
This scenario happens if you sent any content who fails the minimum validation process. For instance, providing a wrong zip code would lead to the following result
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"message": "Provided data contains error(s). See each entry in [errors]",
"errors": {
"address.zipcode": "This value is not valid."
}
} |
...
message
...
Always the same error message, indicating that an error happened during the validation process
...
errors
...
An associative array where the key represents the logical path to the data in error and the value represents the error found with the given data.
If a key contains “.” character, this means nested array. In the case of an array without keys, the logical number would be taken (ex: communication.secondaryPhones.1 would represent the first entry provided in secondaryPhones)
...
Response (403) - Forbidden access
...
Headers
...
Content-type
...
application/json
...
Cache-Control
...
no-cache,private
...
Body
...
| Bloc de code | ||
|---|---|---|
| ||
{
"message": "You do not have the required permission to obtain this resource: location(<(string) uuid of the location>)"
} |
Schedules / Schedule Exception
GET {url}/localtrac/locations/<location_uuid>/schedules | ||||||
|---|---|---|---|---|---|---|
This route will return the list of the location’s regular opening hours. If one day is different (abnormal), use Schedule Exceptions instead. | ||||||
Request | ||||||
Headers | ||||||
Authorization | <token> obtained during the Authentication | |||||
Accept | application/json | |||||
Response (200) - Success | ||||||
Headers | ||||||
Content-type | application/json | |||||
Cache-Control | no-cache,private | |||||
Body | ||||||
| ||||||
<day> | Each row represents a day of the week. This row contains an array of intervals representing the opening hours of that day.
| |||||
GET {url}/localtrac/locations/<location_uuid>/scheduleexceptions | ||||||
This route will return the list of special opening hours (exceptions) where the opening hours of the location differ from the regular opening hours. | ||||||
Request | ||||||
Query | ||||||
p | <int> Page to obtain | |||||
Headers | ||||||
Authorization | <token> obtained during the Authentication | |||||
Accept | application/json | |||||
Response (200) - Success | ||||||
Headers | ||||||
Content-type | application/json | |||||
Cache-Control | no-cache,private | |||||
Body | ||||||
| ||||||
<day> | Each row represent a specific day where the opening hours differ from the regular opening hours. This row contains an array of intervals representing the opening hours of that day. | |||||
POST {url}/localtrac/locations/<location_uuid>/scheduleexceptions | ||||||
This route will add/update the schedule exception for each given day provided. | ||||||
Request | ||||||
Headers | ||||||
Authorization | <token> obtained during the Authentication | |||||
Accept | application/json | |||||
Content-Type | application/json | |||||
Body | ||||||
| ||||||
Response (200) - Success | ||||||
Headers | ||||||
Content-type | application/json | |||||
Cache-Control | no-cache,private | |||||
Body | ||||||
| ||||||
Response (400) - Validation Error | ||||||
Headers | ||||||
Content-type | application/json | |||||
Cache-Control | no-cache,private | |||||
Body | ||||||
| ||||||
message | Always the same message of error, indicating that an error happened during the validation process | |||||
errors | An associative array where the key represents the logical path to the data in error and the value represents the error found with the given data. If a key contains “.” character, this means nested array. In the case of an array without keys, the logical number would be taken. | |||||