API Docs

Methods

Authentication

All requests submitted to the ClearSale API must be authorized by an authenticated user. You will need an ApiKey, Client ID and Client Secret. If the user approves, ClearSale provides your application with an access token.

Logout

Signature: void Logout(RequestAuth Auth)

EndPoint: https://integration.clear.sale/api/auth/logout
SandBox: https://sandbox.clear.sale/api/auth/logout

Order

Status Update Webhook

The status update webhook return status is another available option to receive the status orders whose status was AMA, i.e., orders that were not in a final status.

As soon as a decision is made regarding an order (either approved or denied), the system can be configured to actively send (post) the new status to an endpoint.

The endpoint should be implemented to receive the object OrderStatus via POST in JSON format (Content type: application/json).

Error Handling

The ClearSale Integration API uses HTTP response codes to indicate failure of request.
The responses include a message (ErrorMessage) detailing the nature of the error.

Device Fingerprint

Overview

Device Fingerprint is JavaScript code that collects and analyzes public information about a user’s device. By using this feature, it is possible to identify whether the device and its transaction history are already known to ClearSale.

Device Fingerprint Implementation

The script only had to be included on one web page.

Script execution time will rarely exceed 3 seconds, but the user must not leave the page before the script finishes executing. Therefore, we recommend installing the script on a page that includes interactive elements such as completing forms and providing payment information.

The script will not change the appearance of the page on which it loads.

Script location

Script tags must be included at the end of the html page before </body>.

We recommend inserting this code on the checkout page or its equivalent.

If you follow these recommendations, your website will not suffer any performance loss due to the integration.

Code

The code should be included on the page before the tag, as in the example below:

                <script>
                (function (a, b, c, d, e, f, g) {
                a['CsdmObject'] = e; a[e] = a[e] || function () {
                (a[e].q = a[e].q || []).push(arguments) 
                }, a[e].l = 1 * new Date(); f = b.createElement(c),
                g = b.getElementsByTagName(c)[0]; f.async = 1; f.src = d; g.parentNode.insertBefore(f, g)
                })(window, document, 'script', '//device.clearsale.com.br/p/fp.js', 'csdp');
                csdp('app', 'YOUR_APP');
                csdp('app', 'YOUR_SESSION_ID'); 
                </script>
                
                

ClearSale will inform you of the value with which you should replace the word highlighted in green (YOUR_APP) to identify your website in our system. The value highlighted in green (YOUR_SESSION_ID) is related to the unique session ID generated by the server. This information is extremely important and must be stored and sent to ClearSale later in the order transaction.

The session ID value must be alphanumeric (CHAR type) and that it can be no larger than 128 bytes. Valid characters include numbers, uppercase and lowercase letters, and the underscore and hyphen ([a-z], [A-Z], [0-9], _, -).

Alternative Session ID Creation Method

In certain situations, such as when using Google Tag Manager, it is not possible to fill in the session ID on the implementation code block. In such a case, use an input tag in your HTML to define the ID tag in the Fingerprint implementation code:

Include the input tag on your page, as shown in the example below:

                  <input type=" hidden id=" YOUR_INPUT_ID value=" UNIQUE_SESSION_ID_VALUE" />
                

In the implementation code, you must define the Input ID so the script receives the entered value, as shown in the example below:

                  <script>
                  (function (a, b, c, d, e, f, g) {
                  a['CsdmObject'] = e; a[e] = a[e] || function () {
                  (a[e].q = a[e].q || []).push(arguments) 
                  }, a[e].l = 1 * new Date(); f = b.createElement(c),
                  g = b.getElementsByTagName(c)[0]; f.async = 1; f.src = d; g.parentNode.insertBefore(f, g)
                  })(window, document, 'script', '//device.clearsale.com.br/p/fp.js', 'csdp');
                  csdp('app', 'YOUR_APP');
                  csdp('inputsessionid', 'YOUR_INPUT_ID'); 
                  </script>
                  
                

If you do not use a session ID value on your website, we can create it for you. However, you must send this value to ClearSale later in the order transaction.

Place the input tag on your page as shown in the example below:

                  <input type=" hidden id=" YOUR_INPUT_ID value="" />
                

In the implementation code, you only need to enter the input ID. The script will generate and store a session ID value for the input created, as shown in the example below:

                  <script>
                  (function (a, b, c, d, e, f, g) {
                  a['CsdmObject'] = e; a[e] = a[e] || function () {
                  (a[e].q = a[e].q || []).push(arguments) 
                  }, a[e].l = 1 * new Date(); f = b.createElement(c),
                  g = b.getElementsByTagName(c)[0]; f.async = 1; f.src = d; g.parentNode.insertBefore(f, g)
                  })(window, document, 'script', '//device.clearsale.com.br/p/fp.js', 'csdp');
                  csdp('app', 'YOUR_APP');
                  csdp('outputsessionid', 'YOUR_INPUT_ID'); 
                  </script>
                  
                

Mapper

Mandatory Mapper Implementation

Objective

ClearSale's Mapper is a script developed in JavaScript that responsible for monitoring the environment and interactions and recognizing navigation behavior patterns.

Script Deployment

• The script must be included on each page where there are visits.
• The script must be included just before </body> tag.

                	<script>
                (function (a, b, c, d, e, f, g) {
                a['CsdmObject'] = e; a[e] = a[e] || function () {
                (a[e].q = a[e].q || []).push(arguments) 
                }, a[e].l = 1 * new Date(); f = b.createElement(c),
                g = b.getElementsByTagName(c)[0]; f.async = 1; f.src = d; g.parentNode.insertBefore(f, g)
                })(window, document, 'script', '//device.clearsale.com.br/m/cs.js', 'csdm');
                csdm('app', 'APP_ID'); 
                </script>
                

Page Identification

For better monitoring, navigation and analysis, it is important to be able to identify some pages, as this increases our accuracy. Thus, whenever possible, we strongly recommend using List of page types whenever possible.

The use of a <meta> tag inserted into the header of your html document is the simplest, and is the recommended way to identify pages. Below is an example of how to implement this homepage identification.

                	<meta name="cs:page" content="home">
                

Below is an example of how to identify a page that allows details (List of page details).

                	<meta name="cs:page" content="product">
                <meta name="cs:description" content="name=name of my product, sku=123456">
                

Where meta tags cannot be used for some technical reason or asynchronous calls (such as AJAX), we suggest using the manual mode of transmission. To use this mode you need to add one more line to main script. Below is a complete example.

                	<script>
                (function (a, b, c, d, e, f, g) {
                a['CsdmObject'] = e; a[e] = a[e] || function () {
                (a[e].q = a[e].q || []).push(arguments) 
                }, a[e].l = 1 * new Date(); f = b.createElement(c),
                g = b.getElementsByTagName(c)[0]; f.async = 1; f.src = d; g.parentNode.insertBefore(f, g)
                })(window, document, 'script', '//device.clearsale.com.br/m/cs.js', 'csdm');
                
                csdm('app', 'APP_ID');
                csdm('mode', 'manual'); 
                </script>
                

When the manual mode is enabled, information must be relayed to us using the methods below.

                	<script type="text/javascript">
                // No identification send. 
                csdm('send'); 
                // Page identified send.
                csdm('send', 'home'); 
                // Page identified with details send.
                csdm('send', 'search', 'key-words=Celular 16GB, page-number=2'); 
                </script>
                

Appendix: Tables and Descriptions

Telephone Type

Person or Company

Gender

Payment Method

Credit Card Type

Identification Document Type

Status List

Incoming Status List*

Currency Codes

List Types

List of Page Types

List of Page Details