Use cases

Use Case: Authentication and login process for customer interface

  1. Get <user name> from your account manager. It is usually customer_interface for the customer interface, but it might be different depending on the project.
  2. Create a token using the method [badge-green POST] /tokens.
    The creation of a token is different from other API calls. HTTP Authorization header contains only a login name and no token (because it doesn't exist yet). 
    <user name>:

    Value of HTTP header Authentication contains BASE64 encoded string <user name>:. The request looks like this:

POST <projectURL>/rest-api/customer-interface/v1.0/tokens
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOiA=
  1. You will get a token_id as a response. 
    {
"data":{
"token_id":<token_id>
}
}
  2. The next step is to put together the user name and token in the HTTP Authorization header. The value of the header has to be BASE 64 encoded. 
    <user name>:<token_id>

    HTTP Authorization header looks similar to:

    Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOiA=
  3. For the customer login use the method [badge-green POST] /tokens/{token_id}/actions/login. Remember to set <token_id> in the HTTP Authorization header as is in step nr. 4. Put right customer credentials in the request's body after.

Note: Do not copy the credentials below. Code is just an example of a method used.

{
  "login_type": "email",
  "login_value": "example@crmcarecloud.com",
  "password": "password_example"
}
  1. You will receive the customer_id of the logged-in customer as a response. 
    {
"data":{
"customer_id":<customer_id>
}
}


Use Case: Creation of a customer account process

  1. You should know all the values for the mandatory/optional customer account parameters before creating a customer account by [badge-green POST] /customers. Use any available resource you need to get the lists of actual values. We will use resource stores in this example. To get all options for store_id you should call [badge-blue GET] /stores. Parameter store_id will be set during the customer account creation process.

    GET <projectURL>/rest-api/customer-interface/v1.0/stores
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
#<user name>:<token>
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOmNlMzZjMDg2YmZjN2U3YjBkMjNjNjY3YjdhOTUxZTk=

  2. You will get a response containing the list of stores and their unique IDs.

    "data": {
"stores": [
  {
    "store_id": "86e05affc7a7abefc",
    "store_code": "",
    "name": "Ice Cream HQ",
    "store_address": {
      "address1": "Main",
      "address2": "18",
      "address3": null,
      "address4": null,
      "address5": null,
      "address6": null,
      "address7": null,
      "zip": "11000",
      "city": "Prague",
      "country_code": "cz"
    },
    "contact_email": "",
    "manager_name": "",
    "phone_number": "",
    "partner_id": "86e05affc7a7abe",
    "system_id": "A23753",
    "gps_coordinates": {
      "gps_longitude": 0,
      "gps_latitude": 0
    },
    "url_address": "",
    "opening": [],
    "image_urls": [],
    "last_change": "2018-12-19 16:12:56"
  }
]   
}

  3. You will get a response containing the list of stores and their unique IDs.
    Use the method [badge-green POST] /customers to create a customer account and set store_id as the registration branch of a customer account.

    Header:

    POST <projectURL>/rest-api/customer-interface/v1.0/customers
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
#<user name>:<token>
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOmNlMzZjMDg2YmZjN2U3YjBkMjNjNjY3YjdhOTUxZTk=

    Request body:

    {
"customer_sources": [
{
  "customer_source_id": "0b1788109b8",
  "external_id": "94826712"
}
],
"personal_information": {
"gender": 1,
"first_name": "John",
"last_name": "Smith",
"email": "happy_customer@crmcarecloud.com",
"language_id": "en",
"store_id": "86e05affc7a7abefc",
"birthdate": "1993-01-21",
"phone": "420221634695",
"address": {
  "address1": "Old Town Square",
  "address2": "35",
  "zip": 11000,
  "city": "Prague",
  "country_code": "cz"
},
"agreement":{
  "agreement_gtc": 2,
  "agreement_profiling": 2,
  "agreement_marketing_communication": 2
}
},
"additional_properties": [
  {
      "property_id":"wedding_date",
      "property_name":"Date of wedding",
      "property_value":"2001-08-13",
      "last_change":"2019-04-15 14:37:3.574408"
  }
],
"social_network_credentials": {
"social_network_id": "twitter",
"social_network_token": "38e123j1jedu12d1jnjqwd"
},
"autologin": false,
"password": ""
}

  4. Set all the parameters according to the documentation and get a response including customer_id.

    {
"data":{
    "customer_id":"8bababca29337fcf"
}
}
  5. Customers subresources can be set during the process of a customer account creation. Customer's interests and properties will be set in the next steps. Lists of all available interests and properties are available using the [badge-blue GET] /interests and [badge-blue GET] /customer-properties.

  6. To save a value of interest on a customer account use the interest-records subresource as follows:

    POST <projectURL>/rest-api/customer-interface/v1.0/customers/8bababca29337fcf/interst-records
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
#<user name>:<token>
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOmNlMzZjMDg2YmZjN2U3YjBkMjNjNjY3YjdhOTUxZTk=
    {
"interest_record": {
"interest_id": "87d706e4864d02af7",
"customer_id": "8bababca29337fcf"
}
}

  7. You will get a response including the interest record unique id.

    {
"interest_record_id":"fdsdfe7nh640"
}

  8. Use a similar process to set a property value on a customer account. Use subresource property-records as follows:

    POST <projectURL>/rest-api/customer-interface/v1.0/customers/8bababca29337fcf/property-records
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
#<user name>:<token>
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOmNlMzZjMDg2YmZjN2U3YjBkMjNjNjY3YjdhOTUxZTk=
    {
"property_record": {
"property_id": "87d76e48264d026dpab0f7",
"customer_id": "8bababca29337fcf"
}
}

  9. You will get a response with the property record id.

    {
"property_record_id":"fdsdfbfkdsioe7532"
}
  10. Repeat POST method calls if you need to set more property-records or interest-records on a customer account.


Use Case: Use of the additional properties in resources

  1. Every resource in API has a list of parameters, that are static. As we know, every client has different requirements, and that's why we have additional properties structure in some of our resources. The additional properties contain list of a properties, that can be used by clients to set up a properties that are not used in the main parameters of a resource. The additional properties make API flexible to use.

  2. Resource [badge-blue GET] /rewards contains an additional properties parameter. Additional properties have the same strutcure throughout the API.

  3. API call of the resource [badge-blue GET] /rewards can show us all properties and the values of that resource:

    POST <projectURL>/rest-api/customer-interface/v1.0/rewards
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
#<user name>:<token>
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOmNlMzZjMDg2YmZjN2U3YjBkMjNjNjY3YjdhOTUxZTk=
  4. You will get a response containing the list of rewards with all of their additional properties.
"data": {
    "rewards": [
      {
        "reward_id": "8bdf68d3838b4e009991819e85",
        "code": "",
        "name": "Letní balíček 2017",
        "note": null,
          ...
        "additional_properties": [
            {
            "property_record_id": "global:8bdf68d3838b4e009991819e85",
            "property_id": "global",
            "property_name": "Global setup of reward",
            "property_value": true,
            "last_change": "2017-06-14 10:43:49.882375"
            }
       ],
        "priority": null,
        "image_urls": [],
        "last_change": "2017-06-14 10:43:49.882375",
        "state": 1
      },
       ...