E-Commerce via web services

The most common configuration for e-commerce integration is where EthosCE tracks and records the user's cart information, to be retrieved later by an external checkout system.

A typical workflow is as follows:

User is logged into EthosCE
User adds a product, or products, to cart
User navigates to their cart, and clicks check out
User is redirected to external cart
External cart queries EthosCE web services to obtain the list of products in the user's cart
External cart queries EthosCE to retrieve the SKU (model) or external ID of each product and populates the external cart.
User completes check out on external cart
External cart enrolls user in purchased courses via EthosCE web services
External cart deletes products from cart via EthosCE web services

The steps which require interaction with EthosCE are:

Checking the user's cart

A user's cart information is stored as the individual items they've placed in their cart. In EthosCE terms, it is the list of cart items currently assigned to the user's cart id (their uid). A call to the uc_cart_item endpoint, filtering by cart id will display a list of all items currently in the requested user's cart. As a reference, the user we're enrolling in these requests has a uid of 200.

Checking a user's cart

<?php
// Send the query request via GET
$curl = curl_init("http://your-domain.com/uc_cart_item.json?cart_id=200");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));

$json = curl_exec($curl);
$response = json_decode($json);
$product_list = $response['list'];

This call will return an array of information. In the array, the list value will contain an additional array of cart items, which represent the courses the users have placed in their EthosCE cart. In the array returned the user has added nodes 70 and 75 for purchasing. If the user had no items in their cart, the list value would be empty.

Returned cart items in $product_list

Array
(
    [0] => stdClass Object
        (
            [cart_item_id] => 36
            [cart_id] => 200
            [nid] => 70
            [qty] => 1
            [changed] => 1458745078
            [node] => stdClass Object
                (
                    [uri] => http://your-domain/node/70
                    [id] => 70
                    [resource] => node
                    [uuid] => c8de7a61-0d7c-48b0-b146-289d8ed2524d
                )
        )

    [1] => stdClass Object
        (
            [cart_item_id] => 37
            [cart_id] => 200
            [nid] => 75
            [qty] => 1
            [changed] => 1458745078
            [node] => stdClass Object
                (
                    [uri] => http://your-domain/node/75
                    [id] => 75
                    [resource] => node
                    [uuid] => 289d8ed2524d-48b0-byr6-as34kn4iopwn
                )
        )

)

Looking up the External ID of each item in the cart.

In order to populate the external cart, each course in EthosCE should be linked to a product id in the external system using a key. Typically this key is stored in the External ID field in the course, although the SKU may be used as well. The value of the External ID field can be retreived using the course endpoint.

<?php
$curl = curl_init('http://your-domain/course.json?nid=75');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
// Your session token and content type
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
print curl_exec($curl);

The SKU can be retreived using the node endpoint.

<?php
$curl = curl_init('http://your-domain/node.json?nid=75');
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "admin:webservicepw"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
// Your session token and content type
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
print curl_exec($curl);

Enrolling the user in their purchased courses

In the context of this request, the courses to enroll in are identified by the cart item nid's, which were returned in the request above. A detailed explanation of enrolling a user in a course is found on Enrolling a user via web service. The page details instructions on how to also verify if a user is currently enrolled in a particular course before making the enrollment request. For this request, we will assume the user is not enrolled in either of the courses, and send the enrollment requests immediately. Each enrollment request must be sent individually, as bulk enrollment via web services is not supported.

Enrolling the user

// Iterate through the products to create the enrollment request
foreach ($product_list as $product) {
  $data = array(
    'nid' => $product->nid,
    'uid' => 200,
    'enrollmenttype' => 'webservice_call', // enrollmenttype and type should be updated per client system. They are unique identifiers of the external system sending the call. 
    'type' => 'webservice_call', // Formatted in lower case alphanumeric and underscore characters. The two values are not required to be identical.
    'status' => 1,
  );
// Send the enrollment creation request
  $curl = curl_init("http://your-domain.com/course_enrollment");
  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
  curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials go here
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
  curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));

  $response = curl_exec($curl);
}

Each successful creation request will return an array of values containing the "URI" of the new enrollment record, as well as it's enrollment "id".

{"uri":"http://your-domain.com/course_enrollment/500","id":"500","resource":"course_enrollment"}

Clearing the cart of data

Now that the user has been enrolled in their courses, we must remove the cart items from their session. This can be done by sending individual deletion requests for each cart item.

Deleting cart items

// Iterate through the products to create the deletion request
foreach ($product_list as $product) {
  $curl = curl_init("http://your-domain.com/uc_cart_item/{$product->nid}");
  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
  curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);

  $json = curl_exec($curl);
  $cinfo = curl_getinfo($curl);
  $response = json_decode($json);
  if ($cinfo['http_code'] == 200 && empty($response)) {
    // The entity has been deleted.
  }
  else {
    // An error has occurred.
  }
}

For an explanation of the information returned from the requests above, see Web Service Responses.