Overview

Use the Product Support service to allow consumers to register a product. Product registration is essential for many follow-up processes such as warranties and recalls. This service does not handle warranties or recalls.

The service allows consumers to:

  • Register a product
  • View registered products

You can also configure the service to:

  • Send an email upon product registration
  • Maintain products that consumers can register
  • Create stores to indicate the retail location where products are purchased
  • Update store details

When you configure the service, you can:

  • Maintain email templates for registration notifications
  • Create new stores
  • Flag products that are available for registration from a catalog

Scopes prevent unauthorized access to the Product Support service. The accepted scopes for the service are:

  • hybris.ssrvc-productsupport_view
  • hybris.ssrvc-productsupport_admin
  • hybris.ssrvc-productsupport_manage


API Reference

/{tenant}/productRegistrations

Product Registrations

/{tenant}/productRegistrations

get

Retrieve a collection of product registrations.

If no query is specified, all product registrations are returned in the result collection. To filter the result collection, use the query parameter q. The product registrations service uses the same query syntax as the Document service.

You can sort the result collection using the query parameter sort.

Only persisted fields can be used for querying and sorting.

The GET method is paged. Use the query parameters pageNumber to control which page is retrieved. Use the query parameter pageSize to control the number of service tickets per page. The maximum pageSize supported is 64.

For Service Agent access hybris.ssrvc-productsupport_manage scope is mandatory. Otherwise it is assumed that the call is made by an authenticated customer.

post

Create a new product registration.

The id of the product registration is automatically generated by the system. It is returned in the field id in the response body. It is also part of the response header Location.

Upon successful creation of the product registration, the email of product registration is sent to the customer.

For Service Agent access hybris.ssrvc-productsupport_manage scope is mandatory. Otherwise it is assumed that the call is made by an authenticated customer.

/{tenant}/productRegistrations/{productRegistrationId}

Product Registration

get

Retrieves a single product registration of a given product registration Id

put

Updates a single product registration of a given product registration Id Requires scope 'hybris.ssrvc-productsupport_manage' or 'hybris.ssrvc-productsupport_admin'.

delete

Delete a product registration.

The product registration to be deleted is identified by its id.

Required scope: hybris.ssrvc-productsupport_admin

/{tenant}/stores

Stores

/{tenant}/stores

get

Retrieve a collection of stores.

If no query is specified, all stores are returned in the result collection. To filter the result collection, use the query parameter q. The stores service uses the same query syntax as the Document service.

You can sort the result collection using the query parameter sort.

Only persisted fields can be used for querying and sorting.

The GET method is paged. Use the query parameters pageNumber to control which page is retrieved. Use the query parameter pageSize to control the number of service tickets per page. The maximum pageSize supported is 64.

post

Create a new stores.

The id of the stores is automatically generated by the system.

The following are the required fields to create store StoreCode StoreName Address1 City State Zip Code Country

Required scope: hybris.ssrvc-productsupport_manage

/{tenant}/stores/{storeId}

Store

get

Retrieve a stores.

The stores to be retrieved is identified by its id.

For Service agent access hybris.ssrvc-productsupport_view scope is mandatory. Otherwise it is assumed that the call is made by an authenticated customer.

put

Update a stores.

The stores to be updated is identified by its id.

Note that creating a stores with a caller-specified id is not allowed. Use the POST method at the endpoint /{tenant}/stores to create stores and have their ids generated by the system.

Required scope: hybris.ssrvc-productsupport_manage

delete

Delete a stores.

The stores to be deleted is identified by its id.

Required scope: hybris.ssrvc-productsupport_admin


Product Registration

Product registration is the process of registering a product, purchased online or at a store. Only a signed-in user can register a product. Registering a product allows the purchaser to create service tickets for the registered product, view service ticket status, and chat with a live support agent.

Product Registration attributes

Product registration has these attributes:

  • customerId: The ID of the customer registering a product. This is the equivalent to the SAP Hybris user ID passed in the token. If a service agent registers a product on behalf of the customer, the agent must have the customer's ID and the required scopes.
  • productId: The ID of the the purchased product. This is equivalent to the hybris.product ID.
  • productSerialNo: This field is the product serial number that uniquely identifies a product.
  • storeId: This field identifies the retail store where the product was purchased. The administrator in the Builder UI can maintain a list of the stores.
  • datePurchased: This field is the date the product was purchased.

 

Stores

Stores represent a retail location where customers or the general public can buy products. An administrator can maintain a list of store outlets in the Builder UI.

Store attributes

A store has these attributes:

  • storeCode: Use this field to maintain the store code that uniquely identifies a retail store.
  • storeName: Specify the name of the store.
  • address1: Enter the first address line for the physical location of the store.
  • address2 and address3: Optionally, provide second and third address lines for the physical location of the store.
  • city: Specify the city where the store is located.
  • state: Identify the state or province where the store is located.
  • zip: Specify the ZIP code of the store location.
  • country: Identify the country where the store is located.


Error Types

For more information about error codes, see the detailed error description for each API operation in the API Reference.

You can also check the standard error codes at API best practices.


Scopes

Scopes are strings that let you specify exactly what type of access you need to resources and operations in the Product Support service.

You must provide a proper scope that allows users to perform certain operations. Grant the scopes in an access token from the OAuth 2.0 service. For more information about the authorization and authentication used in YaaS services, and also about the scopes in general, see: Authorization Scopes

The table presents all the scopes that the Product Support service supports.

For service agent access, the hybris.ssrvc-productsupport_manage scope is mandatory. Otherwise, the service assumes that an authenticated customer is calling the service.
ScopeDescription
hybris.ssrvc-productsupport_viewUse this scope to view existing product registrations and stores.
hybris.ssrvc-productsupport_adminUse this scope to create or modify existing product registrations and stores.
hybris.ssrvc-productsupport_manageUse this scope to delete existing product registrations and stores.

If an operation requires two scopes, you must assign both scope to the role. For example, to view an existing product registration, change some properties, and update the registration:

  1. To view and update a product registration's properties, assign the hybris.ssrvc-productsupport_view and hybris.ssrvc-productsupport_manage scopes to the role.
  2. To view a product registration only, assign only the hybris.ssrvc-productsupport_view scope to the role.


Product Registration

Introduction

With the Product Support service, you can manage your product registrations. This tutorial explores how to:

  • Create and retrieve a product registration.
  • Update a product registration.
  • Create and retrieve stores.
  • Update and delete existing stores.

The tutorials uses these endpoints to manage product registrations in the service:

  • Call /{tenant}/productRegistrations to get a list of registered products and creates product registrations. An end application, such as a storefront, can use this endpoint to show product registrations and permit product purchasers to register their products.
  • Use /{tenant}/productRegistrations/{productRegistrationId} to retrieve and update a specified product registration.
  • Call /{tenant}/stores to retrieve the list of stores and you can also post to create new store.
  • Send requests to /{tenant}/stores/{storeId} to update, delete, and retrieve a store, specified by ID.

Set up the project

Follow the examples to set up and run the tutorial project.

Define variable assertion

clientId = clientIdPlaceholder;
clientSecret = clientSecretPlaceholder;
tenant = projectIdPlaceholder;
client = appIdPlaceholder;
scopesRequired='hybris.tenant='+tenant+' hybris.document_manage hybris.document_view hybris.customer_read hybris.customer_update hybris.customer_create  hybris.ssrvc-productsupport_view  hybris.ssrvc-productsupport_admin hybris.ssrvc-productsupport_manage';
token = tokenPlaceholder;
serialValue = Math.floor((Math.random() * 10000) + 1);
CodeSuffix =  Math.floor((Math.random() * 10000) + 1);
demoCustomerId = "C6031109895";
demoProductId = "580938fd348496001dfc14cc";
assert = chai.assert;
Provide a valid, existing customerId and productId for the product and client you select to run this tutorial. You can also create a Product using Builder UI. Replace demoCustomerId and demoProductId values with existing customerId and productId.

Get an access token

For proper authorization to perform these operations, you must provide a valid Bearer access token in your request header. To do so, create an API Client for the OAuth2 service:

API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');

Now, get the token:

AccessToken = oAuth2Service.token.post({
  'client_id' : clientId,
  'client_secret': clientSecret,
  'grant_type' : 'client_credentials',
  'token_type': 'Bearer',
  'scope': scopesRequired
});
access_token = AccessToken.body.access_token;

Create a customer

API.createClient('customerService',
'/services/customer/v1/api.raml');
response = customerService.tenant(tenant).signup.post({
    "email": "itutorial@yaas.io",
    "password": "secret"      
    }, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json'
      }
    }
)

assert.equal(response.status, 201);
response;

customerId = response.body.id;

if(customerId != undefined){
    demoCustomerId = customerId;
}

Create an API client for the Product Support service

API.createClient('productSupport',
'/services/productsupport/v1/api.raml');

Create a store

Send a POST request to the /{tenant}/stores endpoint to create a new store.

You can also create new stores without API calls, in the Builder UI > Self Service section.

response = productSupport.tenant(tenant).stores.post({
          'storeCode':'ESPALCAUSA',
        'storeName':'Electronics Store',
        'address1':'123 Test Drive',
        'city':'Demo City',
        'state':'CA',
        'zip':'94304',
        'country':'USA',
        'createdBy':'SYSTEM'
    }, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
);

assert.equal(response.status, 201);
response;

To make the calls simple and the code examples clean, assign the id of the returned object to the newStoreId variable.

response = productSupport.tenant(tenant).stores.get('q=storeCode:"ESPALCAUSA"', {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)
assert.equal(response.status, 200);
assert.equal(response.body[0].storeCode, 'ESPALCAUSA');
newStoreId = response.body[0].id;
response;

Retrive a list of stores

Send a GET request to the /{tenant}/stores endpoint to get a list of all created stores.

You can also view a list of created stores without API calls, in the Builder UI > Self Service section.
response = productSupport.tenant(tenant).stores.get({}, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)
assert.equal(response.status, 200);
response;

Get an existing store by ID

Send a GET request to the /{tenant}/stores/{storeId} endpoint to retrieve an existing store by store ID.

response = productSupport.tenant(tenant).stores.storeId(newStoreId).get({}, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)
assert.equal(response.status, 200);
existingStore = response.body;
response;

Update an existing store

Send a PUT request to the /{tenant}/stores/{storeId} endpoint to update a specified store.

existingStore.storeName = 'Electronics Store Update'
response = productSupport.tenant(tenant).stores.storeId(newStoreId).put( existingStore, {
          headers: {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type' : 'application/json',
              'Content-Language': 'en',
              'Accept-Language':'en',
            'hybris-languages':'en,de'
          }
    }
)

assert.equal(response.status, 200);

response;

To ensure the update worked as intended, retrieve a store and verify the operation was successful.

response = productSupport.tenant(tenant).stores.storeId(newStoreId).get({}, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
          'Accept-Language': 'en',
        'hybris-languages':'en,de'
          }
    }
)

assert.equal(response.status, 200);
assert.equal(response.body.id, newStoreId);
assert.equal(response.body.storeName, 'Electronics Store Update');
response;

Get a list of product registrations

Send a GET request to the /{tenant}/productRegistrations endpoint to retrieve a list of product registrations and registration data.

response = productSupport.tenant(tenant).productRegistrations.get({}, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)

assert.equal(response.status, 200);
response;


Create a product registration

Send a POST request to the /{tenant}/productRegistrations endpoint to create a new product registration and save it to the Document repository.

Provide a valid, existing customerId and productId for the product and client you select to run this tutorial. You can also create a Product using Builder UI.
You can also create a new product registration using the Storefront UI (Self Service Storefront). You can also make the API call from your own application. Creating a product registration requires a JSON input.
pr_productSerialNo = "DEMO"+serialValue;

response = productSupport.tenant(tenant).productRegistrations.post({
      "customerId":demoCustomerId,
      "productId":demoProductId,
      "productSerialNo":pr_productSerialNo,
      "storeId":newStoreId,
      "datePurchased":"2016-10-10T23:59:59.999+0000",
      "createdBy":demoCustomerId
    }, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)

assert.equal(response.status, 201);
response;

Get a list of existing product registrations

Send a GET request to the /{tenant}/productRegistrations to get a list of product registrations. To make the calls simple and the code examples clean, this example assigns the id of the returned object to the existingProductRegistrationId variable.


queryParm= 'q=productSerialNo:"' + pr_productSerialNo +'"';
response = productSupport.tenant(tenant).productRegistrations.get(queryParm, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)
assert.equal(response.status, 200);
existingProductRegistration = response.body[0];
existingProductRegistrationId = existingProductRegistration.id;
response;

Update an existing product registration

Send a PUT request to the /{tenant}/productRegistrations/{productRegistrationId} endpoint to update an existing product registration.

The example shown uses sample product registration values. Replace the sample values with valid values. In the JSON payload, in the productRegistration field, provide the productRegistraton ID generated in the preceding POST operation.

existingProductRegistration.productSerialNo = 'ABC1234567'
response = productSupport.tenant(tenant).productRegistrations.productRegistrationId(existingProductRegistrationId).put(existingProductRegistration, {
      headers: {
        'Authorization': 'Bearer ' + access_token,
        'Content-Type' : 'application/json',
        'Accept-Language':'en',
        'hybris-languages':'en,de'
      }
    }
)
assert.equal(response.status, 204);
response;

Delete a product registration by ID

Send a DELETE request to the endpoint shown to delete an existing product registration.

response = productSupport.tenant(tenant).productRegistrations.productRegistrationId(existingProductRegistrationId).delete(null, {
  headers: {
    'Authorization': 'Bearer ' + access_token,
    'Content-type' : 'application/json',
    'Accept-Language':'en',
    'hybris-languages':'en,de'
           }
    }
  )
  assert.equal(response.status, '204');
  response;

Delete a store by ID

Send a DELETE request to the /{tenant}/stores/{storeId} endpoint to delete an existing store.


response = productSupport.tenant(tenant).stores.storeId(newStoreId).delete(null, {
  headers: {
    'Authorization': 'Bearer ' + access_token,
    'Content-type' : 'application/json',
    'Accept-Language':'en',
    'hybris-languages':'en,de'
           }
    }
  )
  assert.equal(response.status, '204');
  response;

Clean UP

Delete master data created for tutorial. e.g : Customer


response = customerService.tenant(tenant).customers.customerNumber(demoCustomerId).delete(null, {
  headers: {
    'Authorization': 'Bearer ' + access_token,
    'Content-type' : 'application/json',
    'Accept-Language':'en',
    'hybris-languages':'en,de'
           }
    }
  )
  assert.equal(response.status, '202');
  response;


Glossary

TermDescription
IsRegistrableThis is a flag that you can use to mark a product as "registrable." Maintain this optional flag in the Builder UI. This flag is an extension that you can use only with the Self Service package.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.