576 lines
16 KiB
Markdown
576 lines
16 KiB
Markdown
# Routes
|
|
|
|
[Back](../custom.md)
|
|
|
|
Summary
|
|
|
|
- [Routes](#routes)
|
|
- [Ping](#ping)
|
|
- [Opt in](#opt-in)
|
|
- [Create a customer](#create-a-customer)
|
|
- [Get customer info](#get-customer-info)
|
|
- [Update a customer](#update-a-customer)
|
|
- [Delete a customer](#delete-a-customer)
|
|
- [Authenticate a customer](#authenticate-a-customer)
|
|
- [Send customer answers to a question](#send-customer-answers-to-a-question)
|
|
- [Question listing](#question-listing)
|
|
- [Question listing unanswered only](#question-listing-unanswered-only)
|
|
- [Question listing with customer answers](#question-listing-with-customer-answers)
|
|
- [Get brand statistics](#get-brand-statistics)
|
|
- [Get question statistics](#get-question-statistics)
|
|
|
|
**For all error codes please refer to ``src/Enums/ApiError.php``**
|
|
|
|
---
|
|
|
|
## Ping
|
|
|
|
Name : ``apiV4.ping``
|
|
|
|
URI : ``api/v4/ping``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
PARAMETERS :
|
|
|
|
[]
|
|
|
|
This is the only route that don't need to be authenticated. You may use this to check in a supervision or any if you can still reach LDC crm and if it has not crashed.
|
|
|
|
Response code you always be.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
---
|
|
|
|
## Opt in
|
|
|
|
Name : ``apiV4.optin``
|
|
|
|
URI : ``api/v4/optin``
|
|
|
|
METHOD: ``POST``
|
|
|
|
PARAMETERS:
|
|
|
|
[
|
|
'email': '', // A valid email string
|
|
'status': 0 or 1 // A valid boolean value
|
|
]
|
|
|
|
You this you may create or delete a single opt in. This is used to add one of your customer to you mailing lists. So you may bind this to a subscribe newsletter button for example. ***Please note that you cannot create a single opt in using the same email than one of you customer have***
|
|
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``singleOptinCustomerExists`` : If a customer using the same email exists. You are not allowed to create a single opt in.
|
|
- ``validationException`` :
|
|
- If the provided ``email`` is not valid, checks are dns, rfc, spoof based. This is as strict as possible to prevent your contact list to contain trash.
|
|
- If ``status`` do not contain a boolean value.
|
|
|
|
---
|
|
|
|
## Create a customer
|
|
|
|
Name : ``apiV4.customers.store``
|
|
|
|
URI : ``api/v4/customers``
|
|
|
|
METHOD: ``POST``
|
|
|
|
PARAMETERS:
|
|
|
|
- ``firstname`` : **required** *string* min:1 max:255
|
|
- ``lastname`` : **required** *string* min:1 max:255
|
|
- ``email`` : **required** max:255 A valid email string
|
|
- ``password`` : **required** min:8 max:255 Need to have mixed case, letters, numbers and must not be compromised. This means it must not appear as breached on the internet.
|
|
- ``birth_date``: **required** Must be with format Y-m-d.
|
|
- ``address``: *string* max:255.
|
|
- ``address2``: *string* max:255.
|
|
- ``phone``: *string* Accepted country phones are France, Belgium Luxembourg.
|
|
- ``country``: *integer* This has to contain a value of ``src/Enums/Country.php``, accepted are France or DROM COM (guadeloupe, martinique, frenchGuiana, reunion, saintPierreAndMiquelon, mayotte, saintBarthelemy, saintMartinFrenchPart, wallisAndFutuna, frenchPolynesia, newCaledonia), Belgium or Luxembourg
|
|
- ``city``: *string* min:2 max:255
|
|
- ``postcode``: *string* A valid postal code of France, Belgium or Luxembourg
|
|
- ``opt_in``: **required** A valid boolean
|
|
|
|
|
|
This is used of course to create a new customer.
|
|
***Note : Reponse will contain hashcode, this is the ID of your customer and you may store this information along with its email***
|
|
|
|
**Note : If a single optin exists with you customer email, it will be deleted**
|
|
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
firstname string
|
|
lastname string
|
|
birth_date datetime
|
|
address string
|
|
address2 string
|
|
phone string
|
|
country string
|
|
city string
|
|
postcode string
|
|
opt_in boolean
|
|
hashcode string
|
|
status boolean
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``validationException`` : If any provided parameter is invalid.
|
|
|
|
---
|
|
|
|
## Get customer info
|
|
|
|
Name : ``apiV4.customers.show``
|
|
|
|
URI : ``api/v4/customers/{serviceCustomer}``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
|
|
This is used to get data about a customer, to show profile page for example. **You are encouraged to cache these informations** and update only when the customer updates its own informations.
|
|
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
firstname string
|
|
lastname string
|
|
birth_date datetime
|
|
address string
|
|
address2 string
|
|
phone string
|
|
country string
|
|
city string
|
|
postcode string
|
|
opt_in boolean
|
|
hashcode string
|
|
status boolean
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``modelNotFound`` : If the customer could not be found.
|
|
|
|
---
|
|
|
|
## Update a customer
|
|
|
|
Name : ``apiV4.customers.update``
|
|
|
|
URI : ``api/v4/customers/{serviceCustomer}``
|
|
|
|
METHOD: ``PUT|PATCH``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
PARAMETERS:
|
|
|
|
- ``firstname`` : **at_least** *string* min:1 max:255
|
|
- ``lastname`` : **at_least** *string* min:1 max:255
|
|
- ``email`` : **at_least** max:255 A valid email string
|
|
- ``password`` : **at_least** min:8 max:255 Need to have mixed case, letters, numbers and must not be compromised. This means it must not appear as breached on the internet.
|
|
- ``birth_date``: **at_least** Must be with format Y-m-d.
|
|
- ``address``: **at_least** max:255.
|
|
- ``address2``: **at_least** max:255.
|
|
- ``phone``: **at_least** Accepted country phones are France, Belgium Luxembourg.
|
|
- ``country``: **at_least** This has to contain a value of ``src/Enums/Country.php``, accepted are France or DROM COM (guadeloupe, martinique, frenchGuiana, reunion, saintPierreAndMiquelon, mayotte, saintBarthelemy, saintMartinFrenchPart, wallisAndFutuna, frenchPolynesia, newCaledonia), Belgium or Luxembourg
|
|
- ``city``: **at_least** min:2 max:255
|
|
- ``postcode``: **at_least** A valid postal code of France, Belgium or Luxembourg
|
|
- ``opt_in``: **at_least** A valid boolean
|
|
|
|
|
|
This is used to update customer info. You must at least update on field while calling this.
|
|
|
|
**Note : at_least rule means that at least one of these fields must be present. Send only fields you want to update.**
|
|
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
firstname string
|
|
lastname string
|
|
birth_date datetime
|
|
address string
|
|
address2 string
|
|
phone string
|
|
country string
|
|
city string
|
|
postcode string
|
|
opt_in boolean
|
|
hashcode string
|
|
status boolean
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``validationException`` : If any provided parameter is invalid.
|
|
- ``modelNotFound`` : If the customer could not be found.
|
|
|
|
---
|
|
|
|
## Delete a customer
|
|
|
|
Name : ``apiV4.customers.destroy``
|
|
|
|
URI : ``api/v4/customers/{serviceCustomer}``
|
|
|
|
METHOD: ``DELETE``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
|
|
This is used to remove customer info. ***This cannot be undone and will completly remove all of customer info on our systems.***
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``modelNotFound`` : If the customer could not be found.
|
|
|
|
---
|
|
|
|
## Authenticate a customer
|
|
|
|
Name : ``apiV4.customers.authenticate``
|
|
|
|
URI : ``api/v4/customers/authenticate``
|
|
|
|
METHOD: ``POST``
|
|
|
|
PARAMETERS :
|
|
|
|
- ``email`` : This should be a valid email address and of course exists in you customer database.
|
|
- ``password`` : The actual customer password.
|
|
|
|
|
|
Use this to test Customer credentials and determine if there are valid. You shall then allow login.
|
|
|
|
***Note : make sure you use https connection, http only connections are not accepted***
|
|
|
|
**Note: to login a customer account must be activated, this means you shall verify yourself his email address, than call the activate url.**
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``validationFailed`` : If email is no valid.
|
|
- ``authFailed`` : If credentials aren't valid.
|
|
- ``customerNotActivated`` : If the customer account is not activated.
|
|
|
|
---
|
|
|
|
## Send customer answers to a question
|
|
|
|
Name : ``apiV4.customers.answers.store``
|
|
|
|
URI : ``api/v4/customers/{serviceCustomer}/answers``
|
|
|
|
METHOD: ``POST``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
PARAMETERS :
|
|
|
|
- ``question`` : This has to be a valid question ID
|
|
- ``answers`` : Has to be an array that contains a valid list of answers ID. Even if only one answer is given it still has to be an array. Answers has to belong to the provided question ID.
|
|
|
|
This is to provide customer answer(s)
|
|
|
|
***Note : no checks are done as for the question type, this means even the question should have only one answer you can provide multiple answers.***
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
Possible errors:
|
|
|
|
- ``validationFailed`` : If any of the provided IDS are not valid.
|
|
- ``modelNotFound`` : If the customer could not be found.
|
|
|
|
---
|
|
|
|
## Question listing
|
|
|
|
Name : ``apiV4.questions.index``
|
|
|
|
URI : ``api/v4/questions``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
Use this call to fetch all existing questions. This method also provide the possible answers. We encourage you to cache them.
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
[
|
|
'id' => xx, // question id
|
|
'type' => xx // ``src/Enums/QuestionType.php``,
|
|
'question' => 'question string', // The question string.
|
|
'answers' => [
|
|
[
|
|
'id' => xx, // Answer ID
|
|
'answer' => 'answer string'
|
|
],
|
|
...
|
|
],
|
|
...
|
|
]
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
---
|
|
|
|
## Question listing unanswered only
|
|
|
|
Name : ``apiV4.questions.unAnsweredBy``
|
|
|
|
URI : ``api/v4/questions/un-answered-by/{serviceCustomer}``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
Use this to get question that are still unanswered by your customer.
|
|
|
|
***Note : no checks are done as for the question type, this means even the question should have only one answer you can provide multiple answers.***
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
[
|
|
'id' => xx, // question id
|
|
'type' => xx // ``src/Enums/QuestionType.php``,
|
|
'question' => 'question string', // The question string.
|
|
'answers' => [
|
|
[
|
|
'id' => xx, // Answer ID
|
|
'answer' => 'answer string'
|
|
],
|
|
...
|
|
]
|
|
],
|
|
...
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
- ``modelNotFound`` : If the customer could not be found.
|
|
|
|
---
|
|
|
|
## Question listing with customer answers
|
|
|
|
Name : ``apiV4.questions.indexWithResponse``
|
|
|
|
URI : ``api/v4/questions/with-answers/{serviceCustomer}``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
Use this to get all questions associated with answers already given by your customer.
|
|
|
|
***Note : no checks are done as for the question type, this means even the question should have only one answer you can provide multiple answers.***
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
[
|
|
'id' => xx, // question id
|
|
'type' => xx // ``src/Enums/QuestionType.php``,
|
|
'question' => 'question string', // The question string.
|
|
'answers' => [
|
|
[
|
|
'id' => xx, // Answer ID
|
|
'answer' => 'answer string'
|
|
],
|
|
...
|
|
],
|
|
'customerAnswers' => [
|
|
[
|
|
'id' => xx, // Answer ID
|
|
'answer' => 'answer string'
|
|
],
|
|
...
|
|
]
|
|
],
|
|
...
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
- ``modelNotFound`` : If the customer could not be found.
|
|
|
|
---
|
|
|
|
## Get brand statistics
|
|
|
|
Name : ``apiV4.stats.brandStats``
|
|
|
|
URI : ``api/v4/stats/brand``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
ROUTE PARAMETERS :
|
|
|
|
- ``serviceCustomer`` : The customer hashcode or email, But you may absolutely prefer the customer hashcode. Requested uris leave trace in system logs.
|
|
|
|
PARAMETERS :
|
|
- ``start`` : Must be a date with format ``Y-m-d``, also has to represent a date before ``end``
|
|
- ``end`` Must be a date with format ``Y-m-d``, also has to represent a date after ``start``
|
|
|
|
**Note : The period shall not be exceed 3 month.**
|
|
|
|
***Note : Active user are those who connected since last 6 month, new accounts also are those who has been created since less than 6 months.***
|
|
|
|
Use this to get General stats about your service.
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
[
|
|
[
|
|
'date' => 'Y-m-d', // Date with format
|
|
'active' => xx, // Active users integer
|
|
'inactive' => xx, // Inactive users integer
|
|
'old_accounts' => xx, // Old accounts integer
|
|
'new_accounts' => xx, // New accounts integer
|
|
'total_accounts' => xx, // Total accounts integer
|
|
'total_opt_in' => xx // Total opt in integer
|
|
]
|
|
],
|
|
...
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
- ``validationFailed`` : If any of the provided dates are invalid.
|
|
|
|
---
|
|
|
|
## Get question statistics
|
|
|
|
Name : ``apiV4.stats.questionStats``
|
|
|
|
URI : ``api/v4/stats/question/{serviceQuestion}``
|
|
|
|
METHOD: ``GET|HEAD``
|
|
|
|
ROUTE PARAMETERS :
|
|
- ``serviceQuestion`` : The question ID you want statistics about.
|
|
|
|
PARAMETERS :
|
|
- ``start`` : Must be a date with format ``Y-m-d``, also has to represent a date before ``end``
|
|
- ``end`` Must be a date with format ``Y-m-d``, also has to represent a date after ``start``
|
|
|
|
**Note : The period shall not be exceed 3 month.**
|
|
|
|
***Note : Active user are those who connected since last 6 month, new accounts also are those who has been created since less than 6 months.***
|
|
|
|
Use this to get General stats about your service.
|
|
|
|
Response should be if ok.
|
|
|
|
HTTP : 200
|
|
[
|
|
'status': 'OK',
|
|
'data': [
|
|
'answers' [
|
|
[
|
|
'id' => xx, // Answer ID
|
|
'answer' => 'answer string'
|
|
],
|
|
...
|
|
],
|
|
'stats' => [
|
|
'Y-m-d' = [
|
|
'xx' => xx, // Index is answer ID, value is integer the total count of persons who gave this answer this day.
|
|
],
|
|
...
|
|
]
|
|
],
|
|
'version': 'x.x.x'
|
|
]
|
|
|
|
- ``modelNotFound`` : If the question could not be found.
|
|
- ``validationFailed`` : If any of the provided dates are invalid.
|