forge-joniko/ldc-crm-client
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ldc-crm-client/docs/usages/custom/routes.md
Alexis Gousseau 1f42c1a4d8 client v4
2023-09-11 16:19:10 +02:00

16 KiB
Raw Permalink Blame History

Routes

Back

Summary

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.