{
Nice Chat API
}
Back to Homepage
{
Nice Chat API
}
Description Making Sending
List Categories Create Category Edit Category Remove Category
List Products Create Product Edit Product Remove Product
List Orders
Push the feed Getting the results of push Push the feed with callback

Nice Chat API

Welcome to the API reference!

You can view code examples and switch between programming languages to find the one appropriate for you. We provide the examples in raw-JSON data, cUrl, PHP and Python.

The NiceChat API system based on REST standard.

In the NiceChat API you can use next actions:

You can send data as JSON string (as raw POST data) or as HTTP-POST params by "multipart/form-data" or "application/x-www-form-urlencoded" encoding.

Authentication

Description

The NiceChat API system require the signature of each sent request.

You can generate a API-Key/API-Secret pair in the Settings/Website/API. The key is passed in the request as plain and the secret is used to sign the request.

You can place the authorization chipher as query parameters or in HTTP headers.
To work with query parameters, you need to add API-Key as _key and signature hash as _sing as parameters of you query. It can be urlencoded query_string properties for GET queries or POST parameters for other kind of queries. There is "multipart/form-data" and "application/x-www-form-urlencoded" POST modes support.
In headers mode you need to add API-Key as X-API-Key and signature hash as _sing HTTP headers.
Caution! If you use application/json format you can use only! headers mode (since you need to sign a complete json-string (in exactly the same as it will be sent in the POST-body) and do not change it anymore).

Making

Signature - there is a hex-represent (lower case) of SHA256 hash of the concatenation of the values of the API-Secret + HTTP-path + query-body + and method.

API-Secert - is available in Settings/Website/API

HTTP-path - is URL without protocol, server and parameter (for example, for https://account.nice.chat/marketplaces/v1/import-products-result/xxxxxxxxxxxxx/?q query path is a /marketplaces/v1/import-products-result/xxxxxxxxxxxxx/)

Method - can be GET, POST, PUT, PATCH, DELETE.

Query-body. For json-query it is a compiled json-string is the same as you put in the post-data. For POST-params query body is a urlencoded dictionary sorter by key-name. For example, post params like { title => "Товар", id => 1 } must be transformed to id=1&title=%D0%A2%D0%BE%D0%B2%D0%B0%D1%80.

  • PHP
  • Python
import hashlib


def make_sign(payload, key, secret, action, request_method):

    if isinstance(payload, dict):
        hstr = u'&'.join(['%s=%s' % (j, payload.get(j)) for j in sorted(payload.keys())])
    elif isinstance(payload, basestring):
        hstr = payload
    else:
        return None

    hstr = u'%s%s%s%s' % (secret, action, hstr, request_method)

    try:
        return hashlib.sha256(hstr).hexdigest()
    except UnicodeEncodeError:
        return hashlib.sha256(unicode(hstr).encode('utf-8')).hexdigest()
<?php

function make_sign($payload, $secret, $action, $request_method) {

    $_payload = $payload;

    if (is_array($_payload)) {
        ksort($_payload);
        $_payload = http_build_query($_payload);
    }
    return hash('sha256', $secret.$action.$_payload.$request_method);

}

?>

Sending

This chapter contains examples of requests in different languages. In each example (exclude cUrl)), the make_sign function "included" from the Making's example.

Standard read request:

  • PHP
  • cUrl
  • Python
#!/usr/bin/env bash
curl \
  -H "X-API-Key: FEDH0000000008VH" \
  -H "X-API-Sign: bce54bffd0606f19d56d73693c246c968ffc7b85bc1e8210636bcf9ab4e5187e" \
    https://account.nice.chat/marketplaces/v1/products/
import requests

from lib import make_sign


_key = 'FEDH0000000008VH'
_secret = 'JVFzW6y000000000000000000UukIThD'

NC_API_BASE = 'https://account.nice.chat'

_request_method = 'GET'
_action = '/marketplaces/v1/products/'


_payload = {}

sign = make_sign(_payload, _key, _secret, _action, _request_method)

r = requests.get(NC_API_BASE + _action, data=_payload, headers={
    'X-API-Key': _key,
    'X-API-Sign': sign
})

print r
<?php

$key = 'FEDH0000000008VH';
$secret = 'JVFzW6y000000000000000000UukIThD';

define(NC_API_BASE, 'https://account.nice.chat');

$request_method = 'GET';
$action = '/marketplaces/v1/products/';

$payload = array();
require_once('lib.php');

$sign = make_sign($payload, $secret, $action, $request_method);

$headers = [
    'X-API-Key: '.$key,
    'X-API-Sign: '.$sign
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, NC_API_BASE.$action);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);

?>

Create request:

  • PHP
  • cUrl
  • Python
#!/usr/bin/env bash
curl -X POST \
  --data "currency=usd&price=100&in_stock=True&id=ID-5&title=Example-1&_key=FEDH0000000008VH&_sign=1371d0d0a5a3ec91db2457f439bafc8824b41e350cef74871998dbb8394f86aa" \
    https://account.nice.chat/marketplaces/v1/products/
import requests

from lib import make_sign


_key = 'FEDH0000000008VH'
_secret = 'JVFzW6y000000000000000000UukIThD'

_payload = {
    'id': 'ID-5',
    'title': 'Example-1',
    'price': 100,
    'currency': 'usd',
    'in_stock': True
}

NC_API_BASE = 'https://account.nice.chat'

_request_method = 'POST'
_action = '/marketplaces/v1/products/'

sign = make_sign(_payload, _key, _secret, _action, _request_method)

r = requests.post(NC_API_BASE + _action, data=_payload, headers={
    'X-API-Key': _key,
    'X-API-Sign': sign
})

print r
<?php

$key = 'FEDH0000000008VH';
$secret = 'JVFzW6y000000000000000000UukIThD';

define(NC_API_BASE, 'https://account.nice.chat');

$request_method = 'POST';
$action = '/marketplaces/v1/products/';

$payload = array(
    'id' => 'ID-10',
    'title' => 'Example-1',
    'price' => 100,
    'currency' => 'usd',
    'in_stock' => 1
);
require_once('lib.php');

$sign = make_sign($payload, $secret, $action, $request_method);

$payload['_key'] = $key;
$payload['_sign'] = $sign;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, NC_API_BASE.$action);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
                http_build_query($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);

?>

Update request:

  • PHP
  • cUrl
  • Python
#!/usr/bin/env bash
curl -X PUT \
  -H "Content-type: application/json" \
  -H "X-API-Key: FEDH0000000008VH" \
  -H "X-API-Sign: 0cc446018f2e43cf71af2862efe4bbb48456608cbd2f1c2552876f70139239a5" \
  --data "{\"currency\": \"usd\", \"price\": 200, \"in_stock\": true, \"title\": \"Example-1\"}" \
    https://account.nice.chat/marketplaces/v1/products/ID-1/
import requests
import json

from lib import make_sign


_key = 'FEDH0000000008VH'
_secret = 'JVFzW6y000000000000000000UukIThD'

_payload = json.dumps({
    'title': 'Example-1',
    'price': 200,
    'currency': 'usd',
    'in_stock': True
})

NC_API_BASE = 'https://account.nice.chat'

_request_method = 'PATCH'
_action = '/marketplaces/v1/products/ID-1/'

sign = make_sign(_payload, _key, _secret, _action, _request_method)


r = requests.patch(NC_API_BASE + _action, data=_payload, headers={
    'X-API-Key': _key,
    'X-API-Sign': sign,
    'Content-type': 'application/json'
})

print r
<?php

$key = 'FEDH0000000008VH';
$secret = 'JVFzW6y000000000000000000UukIThD';

define(NC_API_BASE, 'https://account.nice.chat');

$request_method = 'PUT';
$action = '/marketplaces/v1/products/ID-10/';

$payload = json_encode(array(
    'title' => 'Example-1',
    'price' => 200,
    'currency' => 'usd',
    'in_stock' => false
));
require_once('lib.php');

$sign = make_sign($payload, $secret, $action, $request_method);

$headers = [
    'Content-Type: application/json',
    'X-API-Key: '.$key,
    'X-API-Sign: '.$sign
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, NC_API_BASE.$action);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $request_method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
//curl_setopt($ch, CURLOPT_VERBOSE, 1);
$server_output = curl_exec ($ch);
curl_close ($ch);

?>

Edit Categories

Category - is the main container for storing and grouping your Products. Also known as "Group", "Catalog", "Folder")

List exists Categories

You can get a list of existing categories in the system by sending the signed GET requesthttps://accounts.nice.chat/marketplaces/v1/categories/.

System return HTTP Status 200 Ok and data package in JSON, for example:

  • Success
  • Faild
{
   "status": "ok",
   "code": 200,
   "description": "Accepted",
   "result": {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
         {
         "id": "CQ1",
         "name": "Example-1",
         "is_enabled": true
         },
         {
            "id": "CQ2",
            "name": "Example-2",
            "is_enabled": false
         }
      ]
   }
}
{
   "status": "error",
   "code": 401,
   "description": "Access token or signature is non-valid",
}

The result package always contains the following fields:

  • "count" - total count of items in result;
  • "next" - path for query next pagination or null for last page;
  • "previous" - path for query previous pagination or null for first page;
  • "result" - payload:
    • "id" - category unique ID, string, required;
    • "name" - category display Name, string, required;
    • "is_enabled" - boolean;

Create Category

To create new Category you need to send signed POST query on https://accounts.nice.chat/marketplaces/v1/categories/.

  • Success
  • Faild
{
   "status": "ok",
   "code": 201,
   "description": "Created",
   "result": {
      "id": "ID3",
      "name": "Example-3",
      "is_enabled": true
   }
}
{
   "status": "error",
   "code": 412,
   "description": "Object with this ID already exists",
}

Edit Category

To create new Category you need to send signed PUT query on https://accounts.nice.chat/marketplaces/v1/categories/<category_id>/.

  • Success
  • Faild
{
   "status": "ok",
   "code": 202,
   "description": "Modified",
   "result": {
      "name": "Example-3-udp",
      "is_enabled": true
   }
}
{
   "status": "error",
   "code": 404,
   "description": "Object not found",
}

Remove Category

To remove Category you need to send signed DELETE query on https://accounts.nice.chat/marketplaces/v1/categories/<category_id>/.

  • Query
  • Success
  • Faild
#!/usr/bin/env bash
curl -X DELETE \
  -H "X-API-Key: FEDH0000000008VH" \
  -H "X-API-Sign: d7f72a0ae932b09cb459276c8fa541c4b9bfbeca6d3b9a8436db23bf9b1a472f" \
    https://account.nice.chat/marketplaces/v1/categories/ID-10/
{
   "status": "ok",
   "code": 204,
   "description": "Accepted"
}
{
   "status": "error",
   "code": 404,
   "description": "Object not found",
}

Edit Products

Product - is the main container for storing and grouping your Products. Also known as "Group", "Catalog", "Folder")

List exists Products

You can get a list of existing products in the system by sending the signed GET requesthttps://accounts.nice.chat/marketplaces/v1/products/.

System return HTTP Status 200 Ok and data package in JSON, for example:

{
   "status": "ok",
   "code": 201,
   "description": "Created",
   "result": {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
         {
            "id": "PQ1",
            "category": "CQ1",
            "title": "Example product-1",
            "price": 10.00,
            "currency": "usd",
            "description": "Example description",
            "url": "http://example.com/p-1",
            "image_url": "https://cdn.nice.chat/media/2017-5/example.com/c78bd457575a3221c6b3d0d17ffb00ffc63d7cd0_VMi038v.jpg",
            "in_stock": true
         },
         {
            "id": "PQ2",
            "category": "CQ2",
            "title": "Example product-2",
            "price": 15.00,
            "currency": "cad",
            "description": "Example description",
            "url": "http://example.com/p-2",
            "image_url": "https://cdn.nice.chat/media/2017-5/example.com/2936730f1718c5e82eddf331cf2ecbe5181c0801_z842Pe0.png",
            "in_stock": false
         }
      ]
   }
}

The result package always contains the following fields:

  • "count" - total count of items in result;
  • "next" - path for query next pagination or null for last page;
  • "previous" - path for query previous pagination or null for first page;
  • "result" - payload:
    • "id" - products unique ID, string, required;
    • "category" - category unique ID, string;
    • "title" - product title, string;
    • "price" - product price, numeric;
    • "currency" - product currency, ISO 3-letter currency code;
    • "description" - product description, text;
    • "url" - product page URL on your site;
    • "image_url" - full URL to product main image;
    • "in_stock" - is product available on warehouse, boolean;

Create Product

To create new Product you need to send signed POST query on https://accounts.nice.chat/marketplaces/v1/products/.

Important - "image_url" must be a full real URL to image on your server or content distribution service.

{
   "status": "ok",
   "code": 201,
   "description": "Created",
   "result": {
      "id": "PQ3",
      "category": "CQ1",
      "title": "Example product-3",
      "price": 15.00,
      "currency": "cad",
      "description": "Example description",
      "url": "http://example.com/p-2",
      "image_url": "https://example.com/image/product-q3.png",
      "in_stock": false
   }
}

Edit Product

To create new Product you need to send signed PUT query on https://accounts.nice.chat/marketplaces/v1/products/<product_id>/.

If you want not to change image (it was not updated) you must leave previous value (with cdn.nice.chat) and nice.chat not perform request to get image. If you send null nice.chat remove image for specified Product.

{
   "status": "ok",
   "code": 202,
   "description": "Modified",
   "result": {
      "category": "CQ1",
      "title": "Example product-4",
      "price": 15.00,
      "currency": "cad",
      "description": "Example description",
      "url": "http://example.com/p-2",
      "image_url": "https://example.com/image/product-q3.png",
      "in_stock": false
   }
}

Remove Product

To remove Product you need to send signed DELETE query on https://accounts.nice.chat/marketplaces/v1/products/<product_id>/.

#!/usr/bin/env bash
curl -X DELETE \
  -H "X-API-Key: FEDH0000000008VH" \
  -H "X-API-Sign: d7f72a0ae932b09cb459276c8fa541c4b9bfbeca6d3b9a8436db23bf9b1a472f" \     https://account.nice.chat/marketplaces/v1/products/ID-10/

Orders

Order is an aggregated read-only entity that describes all about situation when the purchase is made on the site. The Order includes both purchase and delivery information, as well as live Client data.

List exists Orders

You can get a list of existing products in the system by sending the signed GET request https://accounts.nice.chat/marketplaces/v1/orders/.

System return HTTP Status 200 Ok and data package in JSON, for example:

{
   "status": "ok",
   "code": 200,
   "description": "Accepted",
   "result": {
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
         {
            "id": 30,
            "deal": {
               "website": "example.com",
               "num": "o-11/170521",
               "agents": [
                  "admin@example.com"
               ],
               "chat": 71,
               "date": "2017-05-21 10:26:03.475537+00:00",
               "products": [
                  {
                     "url": "http://example.com/product-1",
                     "price": 111.0,
                     "qty": 1,
                     "id": "1",
                     "title": "Example product-1"
                  }
               ]
            },
            "contacts": {
               "info": {
                  "geoCountry": "Ukraine",
                  "geoCity": "Kyiv"
               },
               "billing_address": {},
               "client": {
                  "chats": 2,
                  "name": "Order-test-guest",
                  "visits": 3,
                  "coming": "2017-05-21 10:23:24.295912+00:00",
                  "id": 95,
                  "latest": "2017-05-21 10:26:55.029384+00:00"
               },
               "shipping_address": {
                  "First name": "Guest",
                  "Last name": "Test",
                  "Address": "Address row, 1"
                  "City": "Kyiv",
                  "State": "Kyiv",
                  "Country": "UA",
                  "POST/ZIP": "11111",
               }
            }
         }
      ]
   }
}

The result package always contains the following fields:

  • "count" - total count of items in result;
  • "next" - path for query next pagination or null for last page;
  • "previous" - path for query previous pagination or null for first page;
  • "result" - payload:
    • "id" - order unique ID, integer;
    • "deal" - information about deal and purchase in current Order;
      • "website" - domain of website where Order was pushed on;
      • "num" - optional Order Number on website;
      • "date" - purchase date in ISO format;
      • "website" - domain of website where Order was pushed on;
      • "agent" - list of emails of agents that was participated to this Order;
      • "products" - list of goods in this Order:
        • "id" - products unique ID, string, required;
        • "title" - product title, string;
        • "price" - product price, numeric;
        • "currency" - product currency, ISO 3-letter currency code;
        • "url" - product page URL on your site, string;
        • "qty" - quntity of products in Order, integer;
    • "contacts" - information about client in current Order;
      • "client" - actual (on query moment) inforation about Client:
        • "id" - uniquie ID of Client on Nice.Chat, integer
        • "name" - name assigned to Client on agents interface, string
        • "coming" - timestamp of first appearance on the site
        • "latest" - timestamp of last activity
        • "visits" - count of visits to the site by the Сlient
        • "chats" - count of chats with this client
      • "billing_address", "shipping_address" - dictionaries with Client addresses
      • "info" - additional info about current deal, dictionary

Feeds

You can push the products feed at the right time.
You can turn-off option "Check products automatically" in Settings\Website\Products and Nice.Chat will not been check your feed itself.

Pushing

Sending a feed for processing is very easy and fast.
You need to do POST request to https://accounts.nice.chat/marketplaces/v1/import-products/ with two fields:

  • - url full URL to your feed;
  • - format - type of your feed. Can be google-csv for Google Merchant or yml for Yandex Market;

{
    "format": "google-csv",
    "url": "https://example.com/products/products.txt"
}

The NiceChat return 20x response and "token" to track pushed task.

{
   "status": "ok",
   "code": 201,
   "description": "Created",
   "result": {
       "token": "390bdd72-bf2b-4114-83c8-c6b6e868b773"
   }
}

Getting the results of push

https://account.nice.chat/marketplaces/v1/import-products-result/390bdd72-bf2b-4114-83c8-c6b6e868b773/

{
   "status": "ok",
   "code": 200,
   "description": "Accepted",
   "result": {
       "pushed": "2017-05-24T14:31:24.337680+00:00",
       "updated": "2017-05-24T14:31:35.850520+00:00",
       "state": "success",
       "imported elements count": 392
   }
}
  • - "pushed" - ISO timestamp, when the task was pushed to queue;
  • - "updated" - ISO timestamp, when was the last update of task information;
  • - "state" - string represent of task's state. Can be "enqueued" => "started" => "success" or "failed";
  • - "imported elements count" - optional field, inform you the number of items that have been processed, integer;

Push the feed with callback

You can add "callback" property to you request:

{
    "format": "google-csv",
    "url": "https://example.com/products/products.txt",
    "callback": "http://example.com/webhook.php"
}

And NiceChat will send results to your site after task will been finished.

Results sent as flat POST values.

Caution! Callback not queued - if your server could not process the request or returned an error, the notification will not be repeated.

[state] => "success"
[updated] => "2017-05-24T14:59:12.728011"
[imported_elements_count] => 392

Error handling

HTTP status codes summary

20x - Normal completion of the task. Server can return 200 Ok, 201 Created, 202 Accepted, 204 No Content codes.

  • 400 – The request was incorrect, please make sure that passed arguments are matching format in method's documentation.
  • 401 – Unauthorized. You attempt to authenticate with an invalid API key or Signature.
  • 404 – Not Found. You attempt to request a resource which doesn't exist.
  • 405 – Method not allowed. You try to do something wrong - server can not execute the specified action on the object.
  • 50x – Temporary Server Error. Something unexpected happened on our end. Please try again (may be the system is updating and you will get something fresh soon) or contact support.