FileVirtuelle Public API
FileVirtuelle is a web application that remove the need to wait in a line. It gives a digital ticket (by sending a text or an email) and call the customer back when his/her turn is close. The FileVirtuelle API gives you access to the core functionalities, so that you can easily develop new clients.
General ¶
Forewords
To get access to the API, you should get in touch with us. You find the email address in www.filevirtuelle.com.
We also provide a Git repository with an example of how to use the API (it’s in Javascript for Node.js). You can access the repo here.
Security and Authentication ¶
When your account is created, you receive an API key and an API secret (standard procedure). The security of the API is based on a HMAC-SHA1 signature and the use of a timestamp to avoid man in the middle attack to replay a previous request.
To do so, we ask our users to use two different headers:
-
Authorization header composed of api_key:signature.
-
X-FV-TIMESTAMP header composed of the current unix timestamp in milliseconds.
How do I compute the signature
Follow this simple procedure:
-
Concatenate the HTTP verb, the URI and the timestamp into a single string.
-
Sign the previous string with your API secret using HMAC-SHA1.
-
Produce a hexadecimal digest.
-
You have your signature.
Let’s take an example: you are requesting /prequalification/5693afe606c3c0b5bc68eaf0. This a GET request and the current unix timestamp in ms is 1471254540335.
Your concatenation is therefore:
var concat = "GET" + "/api/public/v2/prequalification/5693afe606c3c0b5bc68eaf0" + "1471254540335";Now the full example in Javascript (Node.JS):
const crypto = require('crypto');
var concat = "GET" + "/api/public/v2/prequalification/5693afe606c3c0b5bc68eaf0" + "1471254540335";
var api_secret = "7632da295ad6d11a44a75390a0b8fb12ffd24"
var sign = crypto.createHmac('sha1', api_secret).update(concat).digest('hex');
//sign will be 5542b8b446f2203978b7d0549140cbf168de81f5 Now the full example in PHP:
$concat = 'GET' . '/api/public/v2/prequalification/5693afe606c3c0b5bc68eaf0' . '1471254540335';
$api_secret = '7632da295ad6d11a44a75390a0b8fb12ffd24';
$sign = hash_hmac('sha1', $concat, $api_secret);How do I make a real request
Providing that you have computed the signature and that you have the timestamp, this is fairly easy. Let’s say, your API key is bfa3e803-217e-4f00 and your API secret is 7632da295ad6d11a44a75390a0b8fb12ffd24.
A cURL request could be issued like this:
curl -XGET --header "Authorization: bfa3e803-217e-4f00:5542b8b446f2203978b7d0549140cbf168de81f5" --header "X-FV-TIMESTAMP: 1471254540335" "https://fv.filevirtuelle.com/api/public/v2/prequalification/5693afe606c3c0b5bc68eaf0"Using superagent in Node.JS:
const request = require('superagent');
request
.get('https://fv.filevirtuelle.com/api/public/v2/prequalification/5693afe606c3c0b5bc68eaf0')
.set('X-FV-TIMESTAMP', '1471254540335')
.set('Authorization', 'bfa3e803-217e-4f00:5542b8b446f2203978b7d0549140cbf168de81f5')
.set('Accept', 'application/json')
.end(function(err, res){
if (err || !res.ok) {
alert('Oh no! error');
} else {
alert('yay got ' + JSON.stringify(res.body));
}
});Which errors may I receive
For each endpoint, you get the complete list of possible errors (including authentication errors). See the endpoints for more details.
Restrictions ¶
Headers
When you are sending requests to the API, you need to provide the header Content-Type and set it to application/json.
SMS restrictions
Depending on which alphabet you are using, this leads to the maximum individual short message sizes of 160 7-bit characters, 140 8-bit characters, or 70 16-bit characters. More characters mean more texts.
As FileVirtuelle does not have unlimited text messages (we are charged for it) nor emails, when you are in testing phases, you have a fair use of 10 text messages and 50 emails. When both fair uses reache 0, you will be able to use registration by name but not by phone number nor by email address (see “Add customer to the queue” in the Queue section for more details).
Right management
When you have an API key and an API secret, you have access to the API. However, some routes may be restricted as well as some organizations (see organizations for more details) and some suborganizations (see suborganizations for more details).
We distinguish four types of access:
- Create access (POST): you have access to create a given entity (e.g. devices, suborganizations, prequalifications, …).
- Read access (GET): you have access to read a given entity (e.g. devices, suborganizations, prequalifications, …).
- Update access (PUT): you have access to update a given entity (e.g. devices, suborganizations, prequalifications, …).
- Delete access (DELETE): you have access to delete a given entity (e.g. devices, suborganizations, prequalifications, …).
Furthermore, you may have restrictions on which entitiesyou have access to.
Finally, if you are using the API too much (many requests per seconds) you can get locked out.
To get all your API rights, you can use the following request.
Limited number of requests per minute
You can send at most max_hits requests per minute, then you get a 429 error called RateLimitExceeded. You need to wait until the next minute to be able to continue working with the API. If you send too many requests for too many minutes, you might get banned for an unlimited amount of time. BE AWARE!
For more details on max_hits, see the /api_info route below.
Get API information ¶
Get API informationGET/api_info
Example URI
200Headers
Content-Type: application/jsonBody
{
"access": {
"rights": {
"device": {
"c": true,
"r": true,
"u": false,
"d": false
},
"organization": {
"c": true,
"r": true
}
},
"filter": {
"organizations": {
"whitelist": [],
"blacklist": []
},
"suborganizations": {
"whitelist": [],
"blacklist": []
}
}
},
"name": "FileVirtuelle",
"key": "bfa3e803217e97ed5f64174",
"testing": false,
"fairuse": {
"email": 45,
"sms": 7,
"max_hits": 420
},
"urls": {
"next": "https://myorg.com/notify/next_customer",
"processed": ""
}
}Response Parameters
- name
string(optional)Name of the API holder.
- key
string(optional)API key.
- testing
boolean(optional)API in testing mode.
- fairuse
object(optional)- sms
number(optional)SMS Fair Use (see SMS restrictions for details).
number(optional)Email Fair Use (see SMS restrictions for details).
- max_hits
number(optional)Max number of requests per minute.
- access
object(optional)- rights
string(optional)- filter
string(optional)
417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Search Engine ¶
Search Engine
Each GET request comes with a search engine that you can use to restrict search to specific entities and properties inside those entities.
Forging queries
To make a query, you use the querystring with the parameter search: organizations?search=QUERY (QUERY should be replaced by your query).
Boolean logic
Queries are composed of a list of key, operator, value:
-
keyrepresents the field in the json response. For instance, fororganizationsa field can bename,coloroneorcolortwo. -
valuerepresents the value that needs to be matched. For instance, fororganizationsthe value ofnamecan beDarty. -
operatorrepresents an operator.
| Operator | Signification | URI encoding |
|---|---|---|
| = | Check for equality | %3D |
| < | Check for less than | %3C |
| > | Check for greater than | %3E |
| <= | Check for less than or equal | %3C%3D |
| >= | Check for greater than or equal | %3E%3D |
| != | Check for inequality | !%3D |
Each element in the list can be composed with two types of boolean operator:
&meaning AND, escaped as%26|meaning OR, escaped as%7C
Let’s take an example, I looking for organizations running by the name Darty or Nikon:
The query will be:
name=Darty|name=Nikon
And the path will be (with the correct escaping): /organizations?search=name%3DDarty%7Cname%3DNikon
Projection
Every GET routes come with the ability to restrict the response to certain fields, which is called a projection.
NB: We advise you to ALWAYS restrict your GET requests to the fields you want.
Let’s take an example using the list of organizations. By default, you access organizations through the subpath /organizations. If you want to restrict the fields you want, just add the list of fields, like this /organizations/name,colorone. Same goes when accessing certain entities: organization/592e9ab3ed982e4f91c535a2.
NB: You can also filter out the fields you do not want using the - sign such as /organizations/-name,-colortwo which will not display the name of the organization and the secondary color.
To restrict to nested objects only, you need to use the dot notation something.inner_object.
WARNING: Be careful, MongoDB does NOT support mixing inclusion and exclusion (e.g -name,colorone), so you need to choose what you want, or you get an error right away.
The responses will be:
Get Organizations with a projection ¶
Get Organizations with a projectionGET/organizations/name,colorone
Example URI
200Headers
Content-Type: application/jsonBody
[
{
"_id": "592e9ab3ed982e4f91c535a2",
"colorone": "#E60019",
"name": "Darty"
},
{
"_id": "5a6ee589b3bde31910651710",
"colorone": "#FFDE00",
"name": "Nikon"
}
]Response Parameters
- _id
string(required)Unique ID of the organization.
- name
object(required)Name of the organization.
- colorone
string(required)Hexadecimal representation of the main color used in the graphic charter of the organization.
Get an Organization with a projection ¶
Get an Organization with a projectionGET/organization/592e9ab3ed982e4f91c535a2/name,colorone
Example URI
200Headers
Content-Type: application/jsonBody
{
"_id": "592e9ab3ed982e4f91c535a2",
"colorone": "#E60019",
"name": "Darty"
}Response Parameters
- _id
string(required)Unique ID of the organization.
- name
object(required)Name of the organization.
- colorone
string(required)Hexadecimal representation of the main color used in the graphic charter of the organization.
Organizations ¶
Organization
An organization is a group of suborganizations. For a company with multiple stores an organization is the company itself. The organization does not hold a lot of information, because, for flexibility, all the information are kept on the suborganization side.
Get Organization ¶
Get OrganizationGET/organization/{oid}
Get information about an organization with a given ID.
Example URI
- oid
hexadecimal(required)Unique ID of the organization.
200Headers
Content-Type: application/jsonBody
{
"_id": "5693bcd506c3c0b5bc68eaf1",
"name": "Apple",
"logo": "/img/customers/img.png",
"colorone": "#000000",
"colortwo": "#FFFFFF"
}Response Parameters
- _id
string(required)Unique ID of the organization.
- name
object(required)Name of the organization.
- logo
string(required)Relative URL to organization’s logo.
- colorone
string(required)Hexadecimal representation of the main color used in the graphic charter of the organization.
- colortwo
string(required)Hexadecimal representation of the second color used in the graphic charter of the organization.
422When the organization does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidOrganization",
"message": "Invalid organization. Check the ID."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Get all organizations ¶
Get all organizationsGET/organizations
Get all organizations you have access to.
Example URI
200Headers
Content-Type: application/jsonBody
[
{
"_id": "5693bcd506c3c0b5bc68eaf1",
"name": "Apple",
"logo": "/img/customers/img.png",
"colorone": "#000000",
"colortwo": "#FFFFFF"
}
]Response Parameters
- _id
string(required)Unique ID of the organization.
- name
object(required)Name of the organization.
- logo
string(required)Relative URL to organization’s logo.
- colorone
string(required)Hexadecimal representation of the main color used in the graphic charter of the organization.
- colortwo
string(required)Hexadecimal representation of the second color used in the graphic charter of the organization.
417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Suborganizations ¶
Suborganization
A suborganization can be viewed as a part of an organization. For an organization such as Apple, a suborganization will be an Apple Store. A suborganization defines a number of useful parameters such as SMS texts, email texts, time before calling a customer back, and so on.
Get Suborganization ¶
Get SuborganizationGET/suborganization/{sid}
Get information about a suborganization with a given ID.
Example URI
- sid
hexadecimal(required)Unique ID of the suborganization.
200Headers
Content-Type: application/jsonBody
{
"_id": "57be88e6da119ee36dcd0084",
"name": "Apple Hausmann",
"organization": "592e9ab3ed982e4f91d535b2",
"email": {
"activated": false,
"subject_wait": {
"FR": ""
},
"subject_go": {
"FR": ""
},
"subject_comeback": {
"FR": ""
},
"subject_screen": {
"FR": ""
},
"subject_meeting": {
"FR": ""
},
"wait": {
"FR": ""
},
"go": {
"FR": ""
},
"comeback": {
"FR": ""
},
"screen": {
"FR": ""
},
"meeting": {
"FR": ""
},
"provider": "",
"sender": "",
"prefix": "",
"suffix": ""
},
"sms": {
"activated": true,
"default_code": "FR",
"provider": "nexmo",
"sender": "Darty",
"extras": [],
"wait": {
"FR": "Vous avez le numéro {customer.ticket}. Nous vous enverrons un SMS dès que votre tour approchera. Explorez le magasin en attendant d'etre averti."
},
"go": {
"FR": "Bienvenue, votre numéro est le {customer.ticket} ! Restez à proximité de l'Espace Services, nous allons nous occuper de vous."
},
"comeback": {
"FR": "C'est bientot votre tour. Rejoignez l'Espace Services et consultez l'écran d'attente."
},
"screen": {
"FR": ""
},
"meeting": {
"FR": "Bonjour, votre rendez-vous est prévu à {customer.mt_str} et votre numéro de passage dans la file est le {customer.ticket}."
},
"prefix": "",
"suffix": ""
},
"store_code": "907029",
"langs": [
"FR"
],
"floating_desks": true,
"screen_sms": false,
"meeting_sms": false,
"undigital": true,
"redirect_desks": true,
"tz": "Europe/Paris",
"call_by_people": true,
"tbm": 10,
"ptc": 2,
"ttc": 10,
"css_template": "apple",
"meeting": {
"meeting_on_machine": true,
"block": 10,
"expired": 10,
"activated": true,
"provider": "affluences",
"pull": false,
"pull_interval": 0
},
"alerts": {},
"vibrator": {
"provider": "syscall",
"activated": true
},
"extra_codes": {
"codeX": {}
},
"block_desks": {
"activated": false
},
"display": {}
}Response Parameters
- _id
string(required)Identifier assigned by MongoDB
- name
string(required)Name of the suborganization
- organization
string(required)Organization’s id
object(required)- activated
boolean(optional)Activate emails
- subject_wait
object(optional)- FR
string(optional)Subject of the email when a customer needs to wait (may be in multiple languages)
- subject_go
object(optional)- FR
string(optional)Subject of the email sent when a customer should not wait (may be in multiple languages)
- subject_comeback
object(optional)- FR
string(optional)Subject of the email sent when a customer needs to come back (may be in multiple languages)
- subject_screen
object(optional)- FR
string(optional)Subject of the email sent when a customer is called by a desk (may be in multiple languages)
- subject_meeting
object(optional)- FR
string(optional)Subject of the email sent when a customer checks in and has an appointment (may be in multiple languages)
- wait
object(optional)- FR
string(optional)Body of the email sent when a customer should wait (may be in multiple languages)
- go
object(required)- FR
string(optional)Boyd of the email sent when a customer should not wait (may be in multiple languages)
- comeback
object(optional)- FR
string(optional)Body of the email sent when a customer should come back (may be in multiple languages)
- screen
object(optional)- FR
string(optional)Body of the email sent when a customer is called by a desk (may be in multiple languages)
- meeting
object(required)- FR
string(optional)Body of the email sent when a customer has an appointment and checks in (may be in multiple languages)
- provider
string(optional) Default: sendgridEmail’s provider
- sender
string(optional)Email’s sender
- prefix
string(optional)Automatically added string prefix when customer enters her email address
- suffix
string(optional)Automatically added suffix when customer enters her email address
- sms
object(required)- activated
boolean(optional)Activate texts
- default_code
string(optional)Default country code to automatically derived country calling codes
- provider
string(optional)Texts’ provider
- sender
string(optional)Sender
- extras
array(optional)- wait
object(optional)- FR
string(optional)Text sent when a customer needs to wait (may be in multiple languages)
- go
object(optional)- FR
string(optional)Text sent when a customer should not wait (may be in multiple languages)
- comeback
object(optional)- FR
string(optional)Text sent when a customer needs to come back (may be in multiple languages)
- screen
object(optional)- FR
string(optional)Text sent when a customer is called by a desk (may be in multiple languages)
- meeting
object(required)- FR
string(optional)Text sent when a customer has an appointment and checks in
- prefix
string(optional)Automatically added prefix when customer enters her phone number
- suffix
string(optional)Automatically added suffix when a customer enters her phone number
- store_code
string(optional)External suborganization ID (may be needed by some external API)
- langs
array(required)- floating_desks
boolean(optional)Allow desk to be closed
- screen_sms
boolean(optional)Send a text (or email) when a customer is called by a desk
- meeting_sms
boolean(optional)Send a text (or email) when a customer has an appointment and checks in
- undigital
boolean(optional)Allow customers to register with their (first)name
- redirect_desks
boolean(optional)Allow prequalifications to be redirected when a desk is closed
- tz
string(required)Timezone of the suborganization
- call_by_people
boolean(optional) Default: truePrefer to based comeback text (or email) on number of people instead of remaining time to wait
- tbm
integer(required)A customer has an appointment at 4:00pm. He checks in at 3:30pm. If nobody is waiting, a desk can call this customer X minutes before the due time
- ptc
integer(required) Default: 2Number of remaining people before the current customer to call him/her back
- ttc
integer(required) Default: 10Remaining number of minutes before calling the current customer back
- css_template
string(required)CSS Template for ticket machine, desk and screen
- meeting
object(required)- meeting_on_machine
boolean(optional)Allow customer to make a new appointment directly on the ticket machine
- block
integer(optional)TBA
- expired
integer(optional)Delay (in minutes) after which the appointment is considered expired
- activated
boolean(optional)Activate appointment integration
- provider
string(optional)Appointment provider
- pull
boolean(optional)Pull appointments from provider at regular interval
- pull_interval
integer(optional)Number of milliseconds between which we pull appointments from the provider servers
- alerts
object(optional)- vibrator
object(required)- provider
string(optional)Provider of vibrating pagers
- activated
boolean(optional)Activate pager integration
- extra_codes
object(optional)- codeX
object(optional)
- block_desks
object(optional)- activated
boolean(optional)
- display
object(optional)
422When the suborganization does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidSuborganization",
"message": "Invalid suborganization. Check the ID."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Get all suborganizations ¶
Get all suborganizationsGET/suborganizations
Get all suborganizations.
Example URI
200Headers
Content-Type: application/jsonBody
[
{
"_id": "57be88e6da119ee36dcd0084",
"name": "Apple Hausmann",
"organization": "592e9ab3ed982e4f91d535b2",
"email": {
"activated": false,
"subject_wait": {
"FR": ""
},
"subject_go": {
"FR": ""
},
"subject_comeback": {
"FR": ""
},
"subject_screen": {
"FR": ""
},
"subject_meeting": {
"FR": ""
},
"wait": {
"FR": ""
},
"go": {
"FR": ""
},
"comeback": {
"FR": ""
},
"screen": {
"FR": ""
},
"meeting": {
"FR": ""
},
"provider": "",
"sender": "",
"prefix": "",
"suffix": ""
},
"sms": {
"activated": true,
"default_code": "FR",
"provider": "nexmo",
"sender": "Darty",
"extras": [],
"wait": {
"FR": "Vous avez le numéro {customer.ticket}. Nous vous enverrons un SMS dès que votre tour approchera. Explorez le magasin en attendant d'etre averti."
},
"go": {
"FR": "Bienvenue, votre numéro est le {customer.ticket} ! Restez à proximité de l'Espace Services, nous allons nous occuper de vous."
},
"comeback": {
"FR": "C'est bientot votre tour. Rejoignez l'Espace Services et consultez l'écran d'attente."
},
"screen": {
"FR": ""
},
"meeting": {
"FR": "Bonjour, votre rendez-vous est prévu à {customer.mt_str} et votre numéro de passage dans la file est le {customer.ticket}."
},
"prefix": "",
"suffix": ""
},
"store_code": "907029",
"langs": [
"FR"
],
"floating_desks": true,
"screen_sms": false,
"meeting_sms": false,
"undigital": true,
"redirect_desks": true,
"tz": "Europe/Paris",
"call_by_people": true,
"tbm": 10,
"ptc": 2,
"ttc": 10,
"css_template": "apple",
"meeting": {
"meeting_on_machine": true,
"block": 10,
"expired": 10,
"activated": true,
"provider": "affluences",
"pull": false,
"pull_interval": 0
},
"alerts": {},
"vibrator": {
"provider": "syscall",
"activated": true
},
"extra_codes": {
"codeX": {}
},
"block_desks": {
"activated": false
},
"display": {}
}
]Response Parameters
- _id
string(required)Identifier assigned by MongoDB
- name
string(required)Name of the suborganization
- organization
string(required)Organization’s id
object(required)- activated
boolean(optional)Activate emails
- subject_wait
object(optional)- FR
string(optional)Subject of the email when a customer needs to wait (may be in multiple languages)
- subject_go
object(optional)- FR
string(optional)Subject of the email sent when a customer should not wait (may be in multiple languages)
- subject_comeback
object(optional)- FR
string(optional)Subject of the email sent when a customer needs to come back (may be in multiple languages)
- subject_screen
object(optional)- FR
string(optional)Subject of the email sent when a customer is called by a desk (may be in multiple languages)
- subject_meeting
object(optional)- FR
string(optional)Subject of the email sent when a customer checks in and has an appointment (may be in multiple languages)
- wait
object(optional)- FR
string(optional)Body of the email sent when a customer should wait (may be in multiple languages)
- go
object(required)- FR
string(optional)Boyd of the email sent when a customer should not wait (may be in multiple languages)
- comeback
object(optional)- FR
string(optional)Body of the email sent when a customer should come back (may be in multiple languages)
- screen
object(optional)- FR
string(optional)Body of the email sent when a customer is called by a desk (may be in multiple languages)
- meeting
object(required)- FR
string(optional)Body of the email sent when a customer has an appointment and checks in (may be in multiple languages)
- provider
string(optional) Default: sendgridEmail’s provider
- sender
string(optional)Email’s sender
- prefix
string(optional)Automatically added string prefix when customer enters her email address
- suffix
string(optional)Automatically added suffix when customer enters her email address
- sms
object(required)- activated
boolean(optional)Activate texts
- default_code
string(optional)Default country code to automatically derived country calling codes
- provider
string(optional)Texts’ provider
- sender
string(optional)Sender
- extras
array(optional)- wait
object(optional)- FR
string(optional)Text sent when a customer needs to wait (may be in multiple languages)
- go
object(optional)- FR
string(optional)Text sent when a customer should not wait (may be in multiple languages)
- comeback
object(optional)- FR
string(optional)Text sent when a customer needs to come back (may be in multiple languages)
- screen
object(optional)- FR
string(optional)Text sent when a customer is called by a desk (may be in multiple languages)
- meeting
object(required)- FR
string(optional)Text sent when a customer has an appointment and checks in
- prefix
string(optional)Automatically added prefix when customer enters her phone number
- suffix
string(optional)Automatically added suffix when a customer enters her phone number
- store_code
string(optional)External suborganization ID (may be needed by some external API)
- langs
array(required)- floating_desks
boolean(optional)Allow desk to be closed
- screen_sms
boolean(optional)Send a text (or email) when a customer is called by a desk
- meeting_sms
boolean(optional)Send a text (or email) when a customer has an appointment and checks in
- undigital
boolean(optional)Allow customers to register with their (first)name
- redirect_desks
boolean(optional)Allow prequalifications to be redirected when a desk is closed
- tz
string(required)Timezone of the suborganization
- call_by_people
boolean(optional) Default: truePrefer to based comeback text (or email) on number of people instead of remaining time to wait
- tbm
integer(required)A customer has an appointment at 4:00pm. He checks in at 3:30pm. If nobody is waiting, a desk can call this customer X minutes before the due time
- ptc
integer(required) Default: 2Number of remaining people before the current customer to call him/her back
- ttc
integer(required) Default: 10Remaining number of minutes before calling the current customer back
- css_template
string(required)CSS Template for ticket machine, desk and screen
- meeting
object(required)- meeting_on_machine
boolean(optional)Allow customer to make a new appointment directly on the ticket machine
- block
integer(optional)TBA
- expired
integer(optional)Delay (in minutes) after which the appointment is considered expired
- activated
boolean(optional)Activate appointment integration
- provider
string(optional)Appointment provider
- pull
boolean(optional)Pull appointments from provider at regular interval
- pull_interval
integer(optional)Number of milliseconds between which we pull appointments from the provider servers
- alerts
object(optional)- vibrator
object(required)- provider
string(optional)Provider of vibrating pagers
- activated
boolean(optional)Activate pager integration
- extra_codes
object(optional)- codeX
object(optional)
- block_desks
object(optional)- activated
boolean(optional)
- display
object(optional)
422When the organization does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidOrganization",
"message": "Invalid organization. Check the ID."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Devices ¶
Device
A device is of three types:
- Ticket machine where a customer can register him/herself.
- Desk where a shop assistant can call the next registered customer.
- Screen where the ticket number is displayed along with the desk number.
This reflects the real devices that can exist in a store. Ticket machines can register customers whereas desks can only call the next customer. With this in mind, when you are using the /register or /next endpoints you need to give the right type of device in order for the system to accept the request.
A device is also tied to the prequalifications (see Prequalification section for more details). A ticket machine may display only certain prequalifications and some desk may handle only certain types of requests (= certain prequalifications).
A desk may also be opened or closed. It exists several types of closing reasons:
- Long-term closing.
- Small pause during the day.
- Long-term closing with customers’ redirection (= a desk is closed but every requests he is handling is redirected to other desks).
These parameters help the system accurately predict the waiting time for each customer. As a matter of fact, when only two desks are opened, the queue will be dequeued less frequently than when four desks are.
Get Device ¶
Get DeviceGET/device/{did}
Get information about a device with a given ID.
Example URI
- did
hexadecimal(required)Unique ID of the device.
200Headers
Content-Type: application/jsonBody
{
"_id": "597394dfd51ec3d9149455bf",
"organization": "592e9ab3ed982e4f91c645b2",
"suborganization": "",
"name": "Conseiller 1",
"hostname": "D2D2",
"mac": "AC:AF:B9:37:CB:46",
"type": "desk",
"template": "5969349f2c867a1ce23d661c",
"autosink": false,
"html_name": {
"FR": "Conseiller 1"
},
"orientation": {
"FR": ""
},
"html_orientation": {
"FR": ""
},
"pause": {
"timestamp": "2018-06-01T05:59:21.371Z",
"duration": 0
},
"status": {
"pre_close": false,
"redirect": false,
"pause": false,
"open": true
},
"system": {
"ask_before_closing": false
},
"notifications": {
"text": {
"activated": false
}
}
}Response Parameters
- _id
string(required)Identifier assigned by MongoDB
- organization
string(required)Organization this device is linked to
- suborganization
string(required)Suborganization this device is linked to
- name
string(required)Name of the device
- hostname
string(required)Hostname to identify the device inside an organization
- mac
string(required)MAC address of the device
- type
string(required)Type of the device
- template
string(required)UI Template of the device
- autosink
boolean(optional)Only when type is ‘desk’. Set to ‘true’, desk acts as a robot able to call customers automatically. This is used for statistic purposes when using informational prequalifications
- html_name
object(required)- FR
string(optional)HTML name of the device (to be displayed on the frontend. May be in multiple languages)
- orientation
object(optional)- FR
string(optional)Plain-text position of the device in-store (e.g. first floor, on the basement, …)
- html_orientation
object(optional)- FR
string(optional)HTML position of the device in-store (e.g. first floor, on the basement, …)
- pause
object(required)- timestamp
string(optional)Beginning of the pause (ISO 8601 UTC time)
- duration
integer(optional)Pause duration (in minutes)
- status
object(optional)- pre_close
boolean(optional)Close the desk, but do not prevent the desk for calling customers. If all desks are in pre-close mode, the ticket machines displayed a message saying that the store is going to close soon
- redirect
boolean(optional)Close the desk and redirect every prequalifications that it handles to other desks
- pause
boolean(required)Close the desk for a small pause
- open
boolean(optional)Set to true if desk is opened
- system
object(optional)- ask_before_closing
boolean(optional)Force the desk to display a message before closing the window
- notifications
object(optional)- text
object(optional)- activated
boolean(optional)Display a notification when a new customer registers (if activated)
422When the device does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDevice",
"message": "Invalid device. Check the ID"
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Get all devices ¶
Get all devicesGET/devices
Get all devices
Example URI
200Headers
Content-Type: application/jsonBody
[
{
"_id": "597394dfd51ec3d9149455bf",
"organization": "592e9ab3ed982e4f91c645b2",
"suborganization": "",
"name": "Conseiller 1",
"hostname": "D2D2",
"mac": "AC:AF:B9:37:CB:46",
"type": "desk",
"template": "5969349f2c867a1ce23d661c",
"autosink": false,
"html_name": {
"FR": "Conseiller 1"
},
"orientation": {
"FR": ""
},
"html_orientation": {
"FR": ""
},
"pause": {
"timestamp": "2018-06-01T05:59:21.371Z",
"duration": 0
},
"status": {
"pre_close": false,
"redirect": false,
"pause": false,
"open": true
},
"system": {
"ask_before_closing": false
},
"notifications": {
"text": {
"activated": false
}
}
}
]Response Parameters
- _id
string(required)Identifier assigned by MongoDB
- organization
string(required)Organization this device is linked to
- suborganization
string(required)Suborganization this device is linked to
- name
string(required)Name of the device
- hostname
string(required)Hostname to identify the device inside an organization
- mac
string(required)MAC address of the device
- type
string(required)Type of the device
- template
string(required)UI Template of the device
- autosink
boolean(optional)Only when type is ‘desk’. Set to ‘true’, desk acts as a robot able to call customers automatically. This is used for statistic purposes when using informational prequalifications
- html_name
object(required)- FR
string(optional)HTML name of the device (to be displayed on the frontend. May be in multiple languages)
- orientation
object(optional)- FR
string(optional)Plain-text position of the device in-store (e.g. first floor, on the basement, …)
- html_orientation
object(optional)- FR
string(optional)HTML position of the device in-store (e.g. first floor, on the basement, …)
- pause
object(required)- timestamp
string(optional)Beginning of the pause (ISO 8601 UTC time)
- duration
integer(optional)Pause duration (in minutes)
- status
object(optional)- pre_close
boolean(optional)Close the desk, but do not prevent the desk for calling customers. If all desks are in pre-close mode, the ticket machines displayed a message saying that the store is going to close soon
- redirect
boolean(optional)Close the desk and redirect every prequalifications that it handles to other desks
- pause
boolean(required)Close the desk for a small pause
- open
boolean(optional)Set to true if desk is opened
- system
object(optional)- ask_before_closing
boolean(optional)Force the desk to display a message before closing the window
- notifications
object(optional)- text
object(optional)- activated
boolean(optional)Display a notification when a new customer registers (if activated)
417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Prequalifications ¶
Prequalification
A prequalification is something a given store (= a suborganization) is providing to its customers. For instance, customer services or product repair, and so on. A prequalification allows the customer to choose why s/he wants to get into the waiting line. A prequalification comes with an average time (in minutes) of processing, so that FileVirtuelle can compute the overall waiting time for a customer. A prequalification is available in multiple languages, depending on the settings of the suborganization.
Get Prequalification ¶
Get PrequalificationGET/prequalification/{prid}
Get information about a prequalification with a given ID.
Example URI
- prid
hexadecimal(required)Unique ID of the prequalification.
200Headers
Content-Type: application/jsonBody
{
"_id": "59629f5a3a6c9973b2185c21",
"suborganization": "57be88e6da119ee36dcd0084",
"subtitle": {
"FR": ""
},
"header": {
"EN": "Welcome!"
},
"orientation": {
"EN": ""
},
"html_name": {
"EN": "I have<br />an appointment"
},
"name": {
"EN": "No Appointment"
},
"subheader": {
"EN": "Do you have an appointment?"
},
"machines": [],
"desks": [],
"screens": [],
"prequalifications": [],
"prioritize": false,
"notify": false,
"default": false,
"root": true,
"prm": false,
"meeting": false,
"waiting": 0,
"machine_order": 1,
"desk_order": 3,
"trigger": ""
}Response Parameters
- _id
string(optional)Identifier assigned by MongoDB
- suborganization
string(required)ID of the suborganization this prequalification is linked to
- subtitle
object(optional)- EN
string(optional)Small text displayed below the HTML name of the prequalification (used on the ticket machines only in multiple languages)
- header
object(required)- EN
string(optional)Header displayed on the screen showing this prequalification (used on the ticket machines only in multiple languages)
- orientation
object(optional)- EN
string(optional)Deprecated for now
- html_name
object(required)- EN
string(optional)HTML name of the prequalification (used on the frontend only in multiple languages)
- name
object(required)- EN
string(optional)Plain-text name of the prequalification (in multiple languages)
- subheader
object(optional)- EN
string(optional)Header displayed below the current header (used on the ticket machines only in multiple languages)
- machines
array(required)- desks
array(required)- screens
array(required)- prequalifications
array(required)- prioritize
boolean(optional)Prioritize this prequalification
- notify
boolean(optional)Notify desks when customers choose the prequalification
- default
boolean(optional)Default prequalification (internal stuff, at least one prequalification for each suborganization needs to be the default)
- root
boolean(optional)Root prequalification in the hierarchy (first level)
- prm
boolean(optional)Person with reduced mobility prequalification (needs to be displayed a certain way to conform with law)
- meeting
boolean(optional)Prequalification linked to appointments
- waiting
integer(required)Estimated number of minutes it takes to handle this prequalification
- machine_order
integer(required)Display order in ticket machine
- desk_order
integer(required)Display order on desk
- trigger
string(optional)Part of the templating system (internal stuff)
422When the prequalification does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidPrequalification",
"message": "Invalid prequalification. Check the ID."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Get all prequalifications ¶
Get all prequalificationsGET/prequalifications
Get all prequalifications
Example URI
200Headers
Content-Type: application/jsonBody
[
{
"_id": "59629f5a3a6c9973b2185c21",
"suborganization": "57be88e6da119ee36dcd0084",
"subtitle": {
"FR": ""
},
"header": {
"EN": "Welcome!"
},
"orientation": {
"EN": ""
},
"html_name": {
"EN": "I have<br />an appointment"
},
"name": {
"EN": "No Appointment"
},
"subheader": {
"EN": "Do you have an appointment?"
},
"machines": [],
"desks": [],
"screens": [],
"prequalifications": [],
"prioritize": false,
"notify": false,
"default": false,
"root": true,
"prm": false,
"meeting": false,
"waiting": 0,
"machine_order": 1,
"desk_order": 3,
"trigger": ""
}
]Response Parameters
- _id
string(optional)Identifier assigned by MongoDB
- suborganization
string(required)ID of the suborganization this prequalification is linked to
- subtitle
object(optional)- EN
string(optional)Small text displayed below the HTML name of the prequalification (used on the ticket machines only in multiple languages)
- header
object(required)- EN
string(optional)Header displayed on the screen showing this prequalification (used on the ticket machines only in multiple languages)
- orientation
object(optional)- EN
string(optional)Deprecated for now
- html_name
object(required)- EN
string(optional)HTML name of the prequalification (used on the frontend only in multiple languages)
- name
object(required)- EN
string(optional)Plain-text name of the prequalification (in multiple languages)
- subheader
object(optional)- EN
string(optional)Header displayed below the current header (used on the ticket machines only in multiple languages)
- machines
array(required)- desks
array(required)- screens
array(required)- prequalifications
array(required)- prioritize
boolean(optional)Prioritize this prequalification
- notify
boolean(optional)Notify desks when customers choose the prequalification
- default
boolean(optional)Default prequalification (internal stuff, at least one prequalification for each suborganization needs to be the default)
- root
boolean(optional)Root prequalification in the hierarchy (first level)
- prm
boolean(optional)Person with reduced mobility prequalification (needs to be displayed a certain way to conform with law)
- meeting
boolean(optional)Prequalification linked to appointments
- waiting
integer(required)Estimated number of minutes it takes to handle this prequalification
- machine_order
integer(required)Display order in ticket machine
- desk_order
integer(required)Display order on desk
- trigger
string(optional)Part of the templating system (internal stuff)
417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Customers ¶
Customer
A customer is a person that is going to wait in a queue. S/he can have an appointment, be fast-tracked because s/he is a prioritized prequalification, and so on.
A customer needs to register using a ticket machine and is handled by desks.
You can register a customer using the register route et call a customer using the next route (more details below).
As any other GET routes, you can use the search engine and the projections to filter out content you do not want to see.
Get Customer ¶
Get CustomerGET/customer/{cid}
Get information about a customer with a given ID.
Example URI
- cid
hexadecimal(required)Unique ID of the customer.
200Headers
Content-Type: application/jsonBody
{
"_id": "5b5c2394145bec468791489e",
"name": "John Smith",
"machine": "5962930a3737b80434b5008a",
"suborganization": "57be88e6da119ee36dbc0083",
"prequalification": "599340cba4d52e429cbc44b3",
"lang": "FR",
"registered_by": "bfa3e803-217e-4f00-97ed-5f64146N1a",
"wait": false,
"name_removed": false,
"visits": 0,
"expired": false,
"rsvp": true,
"prioritized": false,
"finalized": true,
"digital": false,
"notified": false,
"processed": false,
"called": false,
"meeting": false,
"pbc": 0,
"ttp": 0,
"ttw": 0,
"utimestamp": "2018-07-28T08:04:36.870Z",
"rsvptimestamp": "2018-07-28T08:04:36.811Z",
"mtimestamp": "2018-07-28T08:04:36.811Z",
"stimestamp": "2018-07-28T08:04:36.811Z",
"rtimestamp": "2018-07-28T08:04:36.811Z",
"prequalifications_path": [
"59730cbc8543a51c99b6c388",
"599340cba4d52e429cbc44b3"
],
"type": "name",
"ticket": "1",
"vibrate": false,
"title": "",
"desk": "5a107df0a36532433598220a",
"display": "John Smith",
"display_desk": "John Smith"
}Response Parameters
- phone
string(optional)Phone number if given
string(optional)Email address if given
- name
string(optional)Name (firstname / lastname) if given
- machine
string(required)Id of the chosen ticket machine
- suborganization
string(required)Id of the suborganization
- prequalification
string(required)ID of the chosen prequalification
- lang
string(required)Language of the customer
- registered_by
string(required)API key of registering device (machine or through an API access)
- _id
string(required)Identifier assigned by MongoDB
- external_meeting_id
string(optional)External meeting ID when specified (for appointment only)
- wait
boolean(optional)Based on the suborganization’s configuration, there are too many people before this customer, so s/he needs to wait
- visits
integer(optional)Number of visits based on alerts in suborganization’s configuration
- expired
boolean(optional)If the customer has an appointment and checks in late, the appointment can be considered as expired
- rsvp
boolean(optional)The customer checks in on the ticket machine (for a customer with an appointment, this means that s/he entered the store and said: “Ok I’m here now”)
- prioritized
boolean(optional)This customer will be served in priority
- finalized
boolean(optional)Not used anymore
- digital
boolean(optional)Set to true, this means that the customer can be contacted through digital channels (email / phone…)
- notified
boolean(optional)The text (or email) has been (or not) sent to the customer
- processed
boolean(optional)The customer is already processed (a desk has called her and now it’s done)
- called
boolean(optional)The customer has been called by a desk and it’s in progress
- meeting
boolean(optional)The customer has an appointment
- pbc
integer(optional)Number of people before this customer at the time of registration
- ttp
integer(optional)Number of minutes to processed the customer (from the time s/he was called to the time it was done)
- ttw
integer(optional)Number of minutes the customer waited on the line
- utimestamp
string(required)Last time we updated something regarding this customer
- rsvptimestamp
string(required)Time when the customer checks-in (useful for appointment)
- mtimestamp
string(required)Time of the appointment
- stimestamp
string(required)Time used to sort the customer in the line
- rtimestamp
string(required)Time of registration
- prequalifications_path
array(required)- type
string(required)Type of registration chosen by the customer (phone, email, vibration, name, …)
- ticket
string(required)Ticket assigned to this customer
- vibrate
boolean(optional)Does the customer use a vibrating pager?
- title
string(optional)Title of the customer (Mr / Mrs / Ms, for instance)
- desk
string(required)Desk that called the customer
- display
string(optional)What to show of the waiting / calling screen (based on suborganization’s configuration)
- display_desk
string(required)What to show on desk (based on suborganization’s configuration
417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Get all customers ¶
Get all customersGET/customers
Get all customers
Example URI
200Headers
Content-Type: application/jsonBody
[
{
"_id": "5b5c2394145bec468791489e",
"name": "John Smith",
"machine": "5962930a3737b80434b5008a",
"suborganization": "57be88e6da119ee36dbc0083",
"prequalification": "599340cba4d52e429cbc44b3",
"lang": "FR",
"registered_by": "bfa3e803-217e-4f00-97ed-5f64146N1a",
"wait": false,
"name_removed": false,
"visits": 0,
"expired": false,
"rsvp": true,
"prioritized": false,
"finalized": true,
"digital": false,
"notified": false,
"processed": false,
"called": false,
"meeting": false,
"pbc": 0,
"ttp": 0,
"ttw": 0,
"utimestamp": "2018-07-28T08:04:36.870Z",
"rsvptimestamp": "2018-07-28T08:04:36.811Z",
"mtimestamp": "2018-07-28T08:04:36.811Z",
"stimestamp": "2018-07-28T08:04:36.811Z",
"rtimestamp": "2018-07-28T08:04:36.811Z",
"prequalifications_path": [
"59730cbc8543a51c99b6c388",
"599340cba4d52e429cbc44b3"
],
"type": "name",
"ticket": "1",
"vibrate": false,
"title": "",
"desk": "5a107df0a36532433598220a",
"display": "John Smith",
"display_desk": "John Smith"
}
]Response Parameters
- phone
string(optional)Phone number if given
string(optional)Email address if given
- name
string(optional)Name (firstname / lastname) if given
- machine
string(required)Id of the chosen ticket machine
- suborganization
string(required)Id of the suborganization
- prequalification
string(required)ID of the chosen prequalification
- lang
string(required)Language of the customer
- registered_by
string(required)API key of registering device (machine or through an API access)
- _id
string(required)Identifier assigned by MongoDB
- external_meeting_id
string(optional)External meeting ID when specified (for appointment only)
- wait
boolean(optional)Based on the suborganization’s configuration, there are too many people before this customer, so s/he needs to wait
- visits
integer(optional)Number of visits based on alerts in suborganization’s configuration
- expired
boolean(optional)If the customer has an appointment and checks in late, the appointment can be considered as expired
- rsvp
boolean(optional)The customer checks in on the ticket machine (for a customer with an appointment, this means that s/he entered the store and said: “Ok I’m here now”)
- prioritized
boolean(optional)This customer will be served in priority
- finalized
boolean(optional)Not used anymore
- digital
boolean(optional)Set to true, this means that the customer can be contacted through digital channels (email / phone…)
- notified
boolean(optional)The text (or email) has been (or not) sent to the customer
- processed
boolean(optional)The customer is already processed (a desk has called her and now it’s done)
- called
boolean(optional)The customer has been called by a desk and it’s in progress
- meeting
boolean(optional)The customer has an appointment
- pbc
integer(optional)Number of people before this customer at the time of registration
- ttp
integer(optional)Number of minutes to processed the customer (from the time s/he was called to the time it was done)
- ttw
integer(optional)Number of minutes the customer waited on the line
- utimestamp
string(required)Last time we updated something regarding this customer
- rsvptimestamp
string(required)Time when the customer checks-in (useful for appointment)
- mtimestamp
string(required)Time of the appointment
- stimestamp
string(required)Time used to sort the customer in the line
- rtimestamp
string(required)Time of registration
- prequalifications_path
array(required)- type
string(required)Type of registration chosen by the customer (phone, email, vibration, name, …)
- ticket
string(required)Ticket assigned to this customer
- vibrate
boolean(optional)Does the customer use a vibrating pager?
- title
string(optional)Title of the customer (Mr / Mrs / Ms, for instance)
- desk
string(required)Desk that called the customer
- display
string(optional)What to show of the waiting / calling screen (based on suborganization’s configuration)
- display_desk
string(required)What to show on desk (based on suborganization’s configuration
417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Add standard customer to the queue ¶
Add standard customer to the queuePOST/register
This explains how to register a customer that just arrives in the store.
N.B.: In testing phase (see Get API information for details), you can only send up to 10 text messages and 50 emails. After you reach this limit, you should only register people by their name.
N.B: When you register a user, you need to ensure that the chosen mode is activated in the suborganization configuration. If the undigital mode is not activated you cannot use the name information, if the texting mode is not activated you cannot use the phone number, and so on.
Example URI
- lang
string(required)ISO 639-1 two characters codename (e.g. EN or FR or DE).
- phone
string(required)Phone number of the customer (undefined if not provided).
string(required)Email address of the customer (undefined if not provided).
- name
string(required)Name of the customer (undefined if not provided).
- prequalification
hexadecimal(required)Unique ID of the chosen prequalification.
- suborganization
hexadecimal(required)Unique ID of the suborganization.
- prequalifications_path
array(required)Array of prequalifications (In case the prequalifications are arranged in a hiearchy, this reflects the path chosen by a given customer)
- machine
hexadecimal(required)Unique ID of the ticket machine used for registration.
Headers
Content-Type: application/jsonBody
{
"lang": "FR",
"phone": "0689091314",
"prequalification": "507f1f77bcf86cd799439011",
"prequalifications_path": [
"507f1f77bcf86cd799439011"
],
"machine": "508f1f79bcf97cd799439018"
}200Headers
Content-Type: application/jsonBody
{
"message": "Customer is successfully added",
"change": "POST_customer",
"entity": {
"_id": "5b5c2394145bec468791489e",
"name": "John Smith",
"machine": "5962930a3737b80434b5008a",
"suborganization": "57be88e6da119ee36dbc0083",
"prequalification": "599340cba4d52e429cbc44b3",
"lang": "FR",
"registered_by": "bfa3e803-217e-4f00-97ed-5f64146N1a",
"wait": false,
"name_removed": false,
"visits": 0,
"expired": false,
"rsvp": true,
"prioritized": false,
"finalized": true,
"digital": false,
"notified": false,
"processed": false,
"called": false,
"meeting": false,
"pbc": 0,
"ttp": 0,
"ttw": 0,
"utimestamp": "2018-07-28T08:04:36.870Z",
"rsvptimestamp": "2018-07-28T08:04:36.811Z",
"mtimestamp": "2018-07-28T08:04:36.811Z",
"stimestamp": "2018-07-28T08:04:36.811Z",
"rtimestamp": "2018-07-28T08:04:36.811Z",
"prequalifications_path": [
"59730cbc8543a51c99b6c388",
"599340cba4d52e429cbc44b3"
],
"type": "name",
"ticket": "1",
"vibrate": false,
"title": "",
"desk": "5a107df0a36532433598220a",
"display": "John Smith",
"display_desk": "John Smith"
}
}Response Parameters
- message
string(required)Success message
- change
string(required)Change value (internal use only)
- entity
object(required)- phone
string(optional)Phone number if given
string(optional)Email address if given
- name
string(optional)Name (firstname / lastname) if given
- machine
string(optional)Id of the chosen ticket machine
- suborganization
string(optional)Id of the suborganization
- prequalification
string(optional)ID of the chosen prequalification
- lang
string(optional)Language of the customer
- registered_by
string(optional)API key of registering device (machine or through an API access)
- _id
string(optional)Identifier assigned by MongoDB
- external_meeting_id
string(optional)External meeting ID when specified (for appointment only)
- wait
boolean(optional)Based on the suborganization’s configuration, there are too many people before this customer, so s/he needs to wait
- visits
integer(optional)Number of visits based on alerts in suborganization’s configuration
- expired
boolean(optional)If the customer has an appointment and checks in late, the appointment can be considered as expired
- rsvp
boolean(optional)The customer checks in on the ticket machine (for a customer with an appointment, this means that s/he entered the store and said: “Ok I’m here now”)
- prioritized
boolean(optional)This customer will be served in priority
- finalized
boolean(optional)Not used anymore
- digital
boolean(optional)Set to true, this means that the customer can be contacted through digital channels (email / phone…)
- notified
boolean(optional)The text (or email) has been (or not) sent to the customer
- processed
boolean(optional)The customer is already processed (a desk has called her and now it’s done)
- called
boolean(optional)The customer has been called by a desk and it’s in progress
- meeting
boolean(optional)The customer has an appointment
- pbc
integer(optional)Number of people before this customer at the time of registration
- ttp
integer(optional)Number of minutes to processed the customer (from the time s/he was called to the time it was done)
- ttw
integer(optional)Number of minutes the customer waited on the line
- utimestamp
string(optional)Last time we updated something regarding this customer
- rsvptimestamp
string(optional)Time when the customer checks-in (useful for appointment)
- mtimestamp
string(optional)Time of the appointment
- stimestamp
string(optional)Time used to sort the customer in the line
- rtimestamp
string(optional)Time of registration
- prequalifications_path
array(optional)- type
string(optional)Type of registration chosen by the customer (phone, email, vibration, name, …)
- ticket
string(optional)Ticket assigned to this customer
- vibrate
boolean(optional)Does the customer use a vibrating pager?
- title
string(optional)Title of the customer (Mr / Mrs / Ms, for instance)
- desk
string(optional)Desk that called the customer
- display
string(optional)What to show of the waiting / calling screen (based on suborganization’s configuration)
- display_desk
string(optional)What to show on desk (based on suborganization’s configuration
422When the prequalification does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidPrequalification",
"message": "Invalid prequalification. Check the ID."
}422When the device does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDevice",
"message": "Invalid device. Check the ID"
}422When the desk does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDesk",
"message": "Invalid desk. Check the ID"
}422When the device type is invalid (see devices for more details).
Body
{
"code": 422,
"error": "InvalidDeviceType",
"message": "Type of the device is invalid for this action"
}422When the code for the language is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidLang",
"message": "Invalid lang. Use ISO 639-1 two characters codename"
}422When the date is not in ISO 8601 format, you get this error.
Body
{
"code": 422,
"error": "InvalidIso8601",
"message": "The date is not formatted following the ISO 8601 format"
}422When the phone number and/or the name and/or the email address are invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidContactInformation",
"message": "Invalid contact information. You should provide a phone number, an email address or a name."
}403When you try to register a customer using a mode (phone, email or name) that is not activated at the suborganization level, you get this error.
Body
{
"code": 403,
"error": "ContactModeUnavailable",
"message": "Your mode of registration is not activated. Check the suborganization configuration for more details."
}403When you are in testing mode (see Get API information for more details) and you have exceeded your SMS fair use, you get this error.
Body
{
"code": 403,
"error": "FairUseExceeded",
"message": "You are in testing phase and you have exceeded your fair use. Now you should only register people by name."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Add customer with an appointment to the queue ¶
Add customer with an appointment to the queuePOST/register
This explains how to register a customer that has an appointment later in the day or another day.
Example URI
- lang
string(required)ISO 639-1 two characters codename (e.g. EN or FR or DE).
- phone
string(required)Phone number of the customer (undefined if not provided).
string(required)Email address of the customer (undefined if not provided).
- name
string(required)Name of the customer (undefined if not provided).
- prequalification
hexadecimal(required)Unique ID of the chosen prequalification.
- suborganization
hexadecimal(required)Unique ID of the suborganization.
- prequalifications_path
array(required)Array of prequalifications (In case the prequalifications are arranged in a hiearchy, this reflects the path chosen by a given customer)
- machine
hexadecimal(required)Unique ID of the ticket machine used for registration.
- mtimestamp
string(required)Appointment date (ISO 8601 format). The timezone NEEDS to be UTC, be careful.
- meeting
boolean(required)Set to true for an appointment
- external_meeting_id
string(optional)External ID that can be used when integrating third-party systems.
Headers
Content-Type: application/jsonBody
{
"lang": "FR",
"phone": "0689091314",
"name": "John Smith",
"prequalification": "507f1f77bcf86cd799439011",
"prequalifications_path": [
"507f1f77bcf86cd799439011"
],
"machine": "508f1f79bcf97cd799439018",
"mtimestamp": "2018-06-25T15:15:00.000Z",
"meeting": true,
"external_meeting_id": "john_smith_201806251515"
}200Headers
Content-Type: application/jsonBody
{
"message": "Customer is successfully added",
"change": "POST_customer",
"entity": {
"_id": "5b5c1da8a36c49261173142e",
"phone": "0033688912727",
"name": "Corentin Ribeyre",
"machine": "59aeca503b0ff90f7889b061",
"suborganization": "57be88e6da119ee36dbc0083",
"prequalification": "59730cbc8543a51c99b6c388",
"lang": "FR",
"registered_by": "bfa3e803-217e-4f00-97ed-5f6427564484N1a-FmKtW",
"vibrator_configured": false,
"external_meeting_id": "167839",
"wait": false,
"name_removed": false,
"visits": 1,
"expired": false,
"rsvp": false,
"prioritized": false,
"finalized": true,
"digital": true,
"notified": false,
"processed": false,
"called": false,
"meeting": true,
"pbc": 0,
"ttp": 0,
"ttw": 0,
"utimestamp": "2018-07-28T07:39:20.481Z",
"rsvptimestamp": "2018-07-28T07:39:20.427Z",
"mtimestamp": "2018-07-28T20:00:00.000Z",
"stimestamp": "2018-07-28T20:00:00.000Z",
"rtimestamp": "2018-07-28T20:00:00.000Z",
"prequalifications_path": [
"59730cbc8543a51c99b6c388"
],
"type": "phone",
"ticket": "5b5c1da8a36c49261173142e",
"vibrate": false,
"title": "",
"desk": "5a107df0a36532433598220a",
"display": "R*",
"display_desk": "0033688912727"
}
}Response Parameters
- message
string(required)Success message
- change
string(required)Change value (internal use only)
- entity
object(required)- phone
string(optional)Phone number if given
string(optional)Email address if given
- name
string(optional)Name (firstname / lastname) if given
- machine
string(optional)Id of the chosen ticket machine
- suborganization
string(optional)Id of the suborganization
- prequalification
string(optional)ID of the chosen prequalification
- lang
string(optional)Language of the customer
- registered_by
string(optional)API key of registering device (machine or through an API access)
- _id
string(optional)Identifier assigned by MongoDB
- external_meeting_id
string(optional)External meeting ID when specified (for appointment only)
- wait
boolean(optional)Based on the suborganization’s configuration, there are too many people before this customer, so s/he needs to wait
- visits
integer(optional)Number of visits based on alerts in suborganization’s configuration
- expired
boolean(optional)If the customer has an appointment and checks in late, the appointment can be considered as expired
- rsvp
boolean(optional)The customer checks in on the ticket machine (for a customer with an appointment, this means that s/he entered the store and said: “Ok I’m here now”)
- prioritized
boolean(optional)This customer will be served in priority
- finalized
boolean(optional)Not used anymore
- digital
boolean(optional)Set to true, this means that the customer can be contacted through digital channels (email / phone…)
- notified
boolean(optional)The text (or email) has been (or not) sent to the customer
- processed
boolean(optional)The customer is already processed (a desk has called her and now it’s done)
- called
boolean(optional)The customer has been called by a desk and it’s in progress
- meeting
boolean(optional)The customer has an appointment
- pbc
integer(optional)Number of people before this customer at the time of registration
- ttp
integer(optional)Number of minutes to processed the customer (from the time s/he was called to the time it was done)
- ttw
integer(optional)Number of minutes the customer waited on the line
- utimestamp
string(optional)Last time we updated something regarding this customer
- rsvptimestamp
string(optional)Time when the customer checks-in (useful for appointment)
- mtimestamp
string(optional)Time of the appointment
- stimestamp
string(optional)Time used to sort the customer in the line
- rtimestamp
string(optional)Time of registration
- prequalifications_path
array(optional)- type
string(optional)Type of registration chosen by the customer (phone, email, vibration, name, …)
- ticket
string(optional)Ticket assigned to this customer
- vibrate
boolean(optional)Does the customer use a vibrating pager?
- title
string(optional)Title of the customer (Mr / Mrs / Ms, for instance)
- desk
string(optional)Desk that called the customer
- display
string(optional)What to show of the waiting / calling screen (based on suborganization’s configuration)
- display_desk
string(optional)What to show on desk (based on suborganization’s configuration
422When the prequalification does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidPrequalification",
"message": "Invalid prequalification. Check the ID."
}422When the device does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDevice",
"message": "Invalid device. Check the ID"
}422When the desk does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDesk",
"message": "Invalid desk. Check the ID"
}422When the device type is invalid (see devices for more details).
Body
{
"code": 422,
"error": "InvalidDeviceType",
"message": "Type of the device is invalid for this action"
}422When the code for the language is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidLang",
"message": "Invalid lang. Use ISO 639-1 two characters codename"
}422When the date is not in ISO 8601 format, you get this error.
Body
{
"code": 422,
"error": "InvalidIso8601",
"message": "The date is not formatted following the ISO 8601 format"
}422When the phone number and/or the name and/or the email address are invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidContactInformation",
"message": "Invalid contact information. You should provide a phone number, an email address or a name."
}403When you try to register a customer using a mode (phone, email or name) that is not activated at the suborganization level, you get this error.
Body
{
"code": 403,
"error": "ContactModeUnavailable",
"message": "Your mode of registration is not activated. Check the suborganization configuration for more details."
}403When you are in testing mode (see Get API information for more details) and you have exceeded your SMS fair use, you get this error.
Body
{
"code": 403,
"error": "FairUseExceeded",
"message": "You are in testing phase and you have exceeded your fair use. Now you should only register people by name."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Call the next customer ¶
Call the next customerPOST/next
Example URI
- desk
hexadecimal(required)Unique ID of the desk
- suborganization
hexadecimal(required)Unique ID of the suborganization
Headers
Content-Type: application/jsonBody
{
"desk": "569145cf486d1db46fb02956",
"suborganization": "57be88e6da119ee36dcd0084"
}200Headers
Content-Type: application/jsonBody
{
"message": "Customer is successfully added",
"change": "POST_customer",
"entity": {
"_id": "5b5c2394145bec468791489e",
"name": "John Smith",
"machine": "5962930a3737b80434b5008a",
"suborganization": "57be88e6da119ee36dbc0083",
"prequalification": "599340cba4d52e429cbc44b3",
"lang": "FR",
"registered_by": "bfa3e803-217e-4f00-97ed-5f64146N1a",
"wait": false,
"name_removed": false,
"visits": 0,
"expired": false,
"rsvp": true,
"prioritized": false,
"finalized": true,
"digital": false,
"notified": false,
"processed": false,
"called": true,
"meeting": false,
"pbc": 0,
"ttp": 0,
"ttw": 0,
"utimestamp": "2018-07-28T08:15:36.870Z",
"rsvptimestamp": "2018-07-28T08:04:36.811Z",
"mtimestamp": "2018-07-28T08:04:36.811Z",
"stimestamp": "2018-07-28T08:04:36.811Z",
"rtimestamp": "2018-07-28T08:04:36.811Z",
"ctimestamp": "2018-07-28T08:15:36.811Z",
"prequalifications_path": [
"59730cbc8543a51c99b6c388",
"599340cba4d52e429cbc44b3"
],
"type": "name",
"ticket": "1",
"vibrate": false,
"title": "",
"desk": "5a107df0a36532433598220a",
"display": "John Smith",
"display_desk": "John Smith"
}
}Response Parameters
- message
string(required)Success message
- change
string(required)Change value (internal use only)
- entity
object(required)- phone
string(optional)Phone number if given
string(optional)Email address if given
- name
string(optional)Name (firstname / lastname) if given
- machine
string(optional)Id of the chosen ticket machine
- suborganization
string(optional)Id of the suborganization
- prequalification
string(optional)ID of the chosen prequalification
- lang
string(optional)Language of the customer
- registered_by
string(optional)API key of registering device (machine or through an API access)
- _id
string(optional)Identifier assigned by MongoDB
- external_meeting_id
string(optional)External meeting ID when specified (for appointment only)
- wait
boolean(optional)Based on the suborganization’s configuration, there are too many people before this customer, so s/he needs to wait
- visits
integer(optional)Number of visits based on alerts in suborganization’s configuration
- expired
boolean(optional)If the customer has an appointment and checks in late, the appointment can be considered as expired
- rsvp
boolean(optional)The customer checks in on the ticket machine (for a customer with an appointment, this means that s/he entered the store and said: “Ok I’m here now”)
- prioritized
boolean(optional)This customer will be served in priority
- finalized
boolean(optional)Not used anymore
- digital
boolean(optional)Set to true, this means that the customer can be contacted through digital channels (email / phone…)
- notified
boolean(optional)The text (or email) has been (or not) sent to the customer
- processed
boolean(optional)The customer is already processed (a desk has called her and now it’s done)
- called
boolean(optional)The customer has been called by a desk and it’s in progress
- meeting
boolean(optional)The customer has an appointment
- pbc
integer(optional)Number of people before this customer at the time of registration
- ttp
integer(optional)Number of minutes to processed the customer (from the time s/he was called to the time it was done)
- ttw
integer(optional)Number of minutes the customer waited on the line
- utimestamp
string(optional)Last time we updated something regarding this customer
- rsvptimestamp
string(optional)Time when the customer checks-in (useful for appointment)
- mtimestamp
string(optional)Time of the appointment
- stimestamp
string(optional)Time used to sort the customer in the line
- rtimestamp
string(optional)Time of registration
- ctimestamp
string(optional)Time of calling
- prequalifications_path
array(optional)- type
string(optional)Type of registration chosen by the customer (phone, email, vibration, name, …)
- ticket
string(optional)Ticket assigned to this customer
- vibrate
boolean(optional)Does the customer use a vibrating pager?
- title
string(optional)Title of the customer (Mr / Mrs / Ms, for instance)
- desk
string(optional)Desk that called the customer
- display
string(optional)What to show of the waiting / calling screen (based on suborganization’s configuration)
- display_desk
string(optional)What to show on desk (based on suborganization’s configuration
422When the prequalification does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidPrequalification",
"message": "Invalid prequalification. Check the ID."
}422When the device does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDevice",
"message": "Invalid device. Check the ID"
}422When the desk does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidDesk",
"message": "Invalid desk. Check the ID"
}422When the device type is invalid (see devices for more details).
Body
{
"code": 422,
"error": "InvalidDeviceType",
"message": "Type of the device is invalid for this action"
}422When the code for the language is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidLang",
"message": "Invalid lang. Use ISO 639-1 two characters codename"
}422When the date is not in ISO 8601 format, you get this error.
Body
{
"code": 422,
"error": "InvalidIso8601",
"message": "The date is not formatted following the ISO 8601 format"
}422When the phone number and/or the name and/or the email address are invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidContactInformation",
"message": "Invalid contact information. You should provide a phone number, an email address or a name."
}403When you try to register a customer using a mode (phone, email or name) that is not activated at the suborganization level, you get this error.
Body
{
"code": 403,
"error": "ContactModeUnavailable",
"message": "Your mode of registration is not activated. Check the suborganization configuration for more details."
}403When you are in testing mode (see Get API information for more details) and you have exceeded your SMS fair use, you get this error.
Body
{
"code": 403,
"error": "FairUseExceeded",
"message": "You are in testing phase and you have exceeded your fair use. Now you should only register people by name."
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Update a customer ¶
Update a customerPUT/customer
Update a customer with a given _id (required). The request may then include any field from the customer
that you’d like to change. See the description of a customer above (in this section).
Please keep in mind that the fields are typed (a boolean should stay as a boolean, a string as a string, and so on).
Some fields are always validated through the validation process and may raise an error if they are incorrectly set.
Example URI
Headers
Content-Type: application/jsonBody
{
"_id": "569145cf486d1db46fb02956",
"mtimestamp": "2018-07-30T15:00:00.000Z",
"expired": false,
"name": "New Name of the Customer"
}200Headers
Content-Type: application/jsonBody
{
"success": "[Customer object]",
"message": "Customer is successfully modified"
}422When an entity (whatever it is) does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidEntity",
"message": "This entity is invalid. Check the ID"
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}Delete a customer ¶
Delete a customerDELETE/customer/{cid}
Delete a customer with a given ID (the response includes the deleted customer).
Example URI
- cid
hexadecimal(required)Unique ID of the customer (given by MongoDB)
200Headers
Content-Type: application/jsonBody
{
"success": "[Customer object]",
"message": "Customer is successfully removed"
}422When an entity (whatever it is) does not exist or is invalid, you get this error.
Body
{
"code": 422,
"error": "InvalidEntity",
"message": "This entity is invalid. Check the ID"
}417When you don’t provide an Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoAuthorizationHeaderError",
"message": "No authorization header found. You should provide an Authorization header with Authorization: api_key:signature."
}417When you don’t provide a two-part (api_key:signature) Authorization header, you get this error.
Body
{
"code": 417,
"error": "NoTwoPartAuthorizationError",
"message": "Authorization header should be of two parts: api_key:signature."
}403When your API key is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidAPIKey",
"message": "API Key does not exist."
}403When your signature is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidSignature",
"message": "The signature does not match."
}403When the timestamp is invalid, you get this error.
Body
{
"code": 403,
"error": "InvalidTimestamp",
"message": "Invalid timestamp."
}403When your account is locked (term violation, for instance), you get this error.
Body
{
"code": 403,
"error": "AccountIsLocked",
"message": "Your account is locked. Please contact an administrator."
}403When you try to access a route that is restricted. Some routes are inaccessible because it depends on your API rights.
Body
{
"code": 403,
"error": "InvalidRoute",
"message": "You don't have access to this route."
}429When you send more than the limited number of requests per minute, you get this error.
Body
{
"code": 429,
"error": "RateLimitExceeded",
"message": "You have exceeded the max number of requests per minutes."
}