Client Order Request Api (далее просто API)

CLIENT ORDER REQUEST API
1
CLIENT ORDER REQUEST API
История документа
Версия
1.0
1.1
Заголовок
Описание RestAPI
Описание назначения/Order Life Cycle
Дата
02.11.2013
19.11.2013
2
CLIENT ORDER REQUEST API
НАЗНАЧЕНИЕ API
Client Order Request Api (далее просто API) предназначен для регистрации конечного
действия пользователя(заказа) в системе CallTouch . Данное действие позволяет клиентам
CallTouch, связать сессионные параметры пользователя (ключевые слова поиска, источник,
тип источника, сессию гугл аналитикс) с его конечным целевым действием(например
таким как покупка товара ) . API позволяет осуществлять регистрацию заказов, поиск ,
поддержку жизненного цикла заказа, что помогает оценить процент не завершенных
заказов или заказов, которые были отклонены.
Статусы заказа
NOT_SET (заказ был инициирован пользователем, но не был оформлен)
PENDING(заказ был оформлен, но еще не подтвержден системой)
APPROVED(заказ оплачен и подтвержден системой)
CANCELED(заказ отменен оператором системы или пользователем)
REJECTED(заказ отклонен системой)
COMPLETED(заказ доставлен клиенту/ завершен)
Жизненный цикл заказа
CANCELED
NOT_SET
PENDING
APPROVED
COMPLETED
REJECTED
3
CLIENT ORDER REQUEST API
ФОРМАТ ЗАПРОСОВ
РЕГИСТРАЦИЯ ЗАЯВКИ
URL: http:// api.calltouch.ru/calls-service/RestAPI/requests/orders/register/
Допустимые типы запроса: GET, POST
Параметры:
Имя параметра
Обязателен?
clientApiId
ДА
subject
НЕТ
status
НЕТ
fio
phoneNumber
personalPhone
НЕТ
НЕТ
НЕТ
email
НЕТ
orderSum
НЕТ
orderNumber
НЕТ
orderComment
НЕТ
orderStatus
НЕТ
requestNumber
НЕТ
sessionId
НЕТ
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
Назначение/имя запроса; Далее эту информацию можно
будет видеть и редактировать в личном кабинете.
Статус заявки; NOT_SET(если не установлено),, ACCEPTED,
REJECTED
Фамилия имя отчество клиента, заполнившего анкету
Номер телефона клиента по заявке на сайте
Личный телефон или нет(true, false); Ставить нужно “false”,
если не требуется, чтобы телефон не был сохранен как
личный телефон клиента
Адрес электронной почты клиента, заполнившего заявку на
сайте
Общая сумма заказа (обязательное поле, если есть
orderNumber). Если требуется посчитать суммы заказов по
сессиям пользователя – необходимо заполнять.
уникальный номер заказа в системе клиента (не в
CallTouch). Заполняется как уникальный ключ. Может
равняться уникальному номеру заявки, если это один и тот
же объект.
Комментарии к заказу. Может быть заполнено по
усмотрению сайта, например подробным описание
заказанных товаров. Далее эту информацию можно будет
видеть и редактировать в личном кабинете.
Статус заказа (NOT_SET(если неустановлено), PENDING,
APPROVED, REJECTED, CANCELLED);
Уникальный номер заявки на сайте. Заполняется
уникальным ключем, сгенерированным на стороне клиента
для дальнешей связи заявки на сайте и заявки, созданной в
CallTouch
Текущий номер сессииCallTouch, заполняется параметром,
который CallTouch передает call_value переменной скрипта.
4
CLIENT ORDER REQUEST API
Для интеграции сессии пользователя необходимо в параметр sessionId устанавливать значение
параметра call_value, которое Calltouch передает при ответе на запрос выделения тел. номера для
сайта.
ОТВЕТ: JSONRequestObject
Пример: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/register/?clientApiId=xxxxxx&requestNumber=1&orderNumber
=1&orderSum=1258&fio=Alex&email=alex@calltoch.ru&phoneNumber=8926xxxxxx&personalPho
ne=false&orderСomment=VseOk
РЕГИСТРАЦИЯ ЗАКАЗА ПО ЗВОНКУ
URL: http:// api.calltouch.ru/calls-service/RestAPI/orders/register/
Допустимые типы запроса: GET, POST
Параметры:
Имя параметра
Обязателен
?
clientApiId
ДА
status
НЕТ
fio
phoneNumber
personalPhone
НЕТ
НЕТ
НЕТ
email
НЕТ
orderSum
НЕТ
orderNumber
НЕТ
orderComment
НЕТ
orderStatus
НЕТ
orderDate
linkTimeThreshold
НЕТ
НЕТ
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
Статус заявки; NOT_SET(если не установлено),, ACCEPTED,
REJECTED
Фамилия имя отчество клиента, заполнившего анкету
Номер телефона клиента по заявке на сайте
Личный телефон или нет(true, false); Ставить нужно “false”,
если не требуется, чтобы телефон не был сохранен как
личный телефон клиента
Адрес электронной почты клиента
Общая сумма заказа (обязательное поле, если есть
orderNumber). Если требуется посчитать суммы заказов по
сессиям пользователя – необходимо заполнять.
уникальный номер заказа в системе клиента (не в
CallTouch). Заполняется как уникальный ключ.
Комментарии к заказу. Может быть заполнено по
усмотрению сайта, например подробным описание
заказанных товаров. Далее эту информацию можно будет
видеть и редактировать в личном кабинете.
Статус заказа (NOT_SET(если неустановлено), PENDING,
APPROVED, REJECTED, CANCELLED)
Определяет время заказа(Формат дата.число.год чч:мм:сек )
Параметр определяющий допустимый порог по времени для
поиска ближайшего звонка (размерность в секундах), если
параметр отсутствует то значение будет определяться
5
CLIENT ORDER REQUEST API
значением настройки из нашей системы по умолчанию 7200
(2 часа)
Важным параметром является orderDate, он определяет время заказа. Предполагается, что заказ
составляется во время разговора по телефону с клиентом и данная дата является временем
заведения заказа на момент звонка. Это дата будет использоваться для поиска звонка для связки.
Критерий определения
Дата звонка <= Дата заказа <= Дата звонка + Длительность звонка + linkTimeThreshold(допустимый
порог)
Телефон звонившего должен совпадать с phoneNumber.
ОТВЕТ: JSONOrderObject
Пример: http://api.calltouch.ru/callsservice/RestAPI/orders/register/?clientApiId=xxxxx&orderSum=780
&fio=Александр&phoneNumber=79187665050&orderComment=test test&orderNumber=MK908777&orderDate=22.04.2014 15:09:44
ПОИСК ЗАЯВКИ
URL: http://api.calltouch.ru/calls-service/RestAPI/requests
Допустимые типы запроса: GET
Имя параметра
Обязателен?
clientApiId
ДА
dateFrom
dateTo
subject
keywords
НЕТ
НЕТ
НЕТ
НЕТ
city
source
medium
НЕТ
НЕТ
НЕТ



Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
Дата начала просмотра. Формат: (mm/dd/yyyy)
Дата конца просмотра. Формат: (mm/dd/yyyy)
Назначение/имя запроса.(поиск: START_WITH),
Ключевые слова по которым был заход на сайт(поиск:
CONTAINS),
Город (поиск: FULL MATCH)
Источник(поиск: FULL MATCH)
Тип источника(поиск: FULL MATCH)
поиск: START_WITH – поиск строк, которые начинаются с “значения параметра”
поиск: CONTAINS – поиск строк, которые содержат в себе “ значение параметра”
поиск: FULL MATCH – поиск строк с полным соответствием “ значению параметра”
ОТВЕТ: Array(JSON Request Object)
6
CLIENT ORDER REQUEST API
Пример: http:// api.calltouch.ru/callsservice/RestAPI/requests?clientApiId=xxxx&dateFrom=01/02/2013&dateTo=02/14/2013
ВЫБОР ЗАЯВКИ
URL: http:// api.calltouch.ru/calls-service/RestAPI/requests/{requestNumber}
Допустимые типы запроса: GET
Имя параметра
Обязателен?
clientApiId
ДА
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
ОТВЕТ: JSON Request Object
Пример: http:// api.calltouch.ru/calls-service/RestAPI/requests/1?clientApiId=xxxx
ВЫБОР ЗАКАЗА
URL: http:// api.calltouch.ru/calls-service/RestAPI/requests/orders/{orderNumber}
Допустимые типы запроса: GET
Имя параметра
Обязателен?
clientApiId
ДА
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
ОТВЕТ: JSON Order Object
Пример: http:// api.calltouch.ru/calls-service/RestAPI/requests/orders/2?clientApiId=xxxx
ПОДТВЕРЖДЕНИЕ ЗАКАЗА(STAUS=APPROVED)
Допустимые типы запроса: GET
7
CLIENT ORDER REQUEST API
Имя параметра
Обязателен?
clientApiId
ДА
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
ОТВЕТ: JSON Order Object
Пример: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/2/approve?clientApiId=xxxx
ОТМЕНА ЗАКАЗА(STAUS=CANCELED)
Допустимые типы запроса: GET
Имя параметра
Обязателен?
clientApiId
ДА
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
ОТВЕТ: JSON Order Object
Пример: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/2/cancel?clientApiId=xxxx
ОШИБКА В ОБРАБОТКЕ ЗАКАЗА(STAUS=REJECTED)
Допустимые типы запроса: GET
Имя параметра
Обязателен?
clientApiId
ДА
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
ОТВЕТ: JSON Order Object
Пример: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/2/reject?clientApiId=xxxx
ОШИБКА В ОБРАБОТКЕ ЗАКАЗА(STAUS=COMPLETED)
8
CLIENT ORDER REQUEST API
Допустимые типы запроса: GET
Имя параметра
Обязателен?
clientApiId
ДА
Описание
Уникальный идентификатор, ключ для отправки запроса в
CallTouch, выдается по запросу для каждого сайта.
Обращаться за значением необходимо по заявке из личного
кабинета.
ОТВЕТ: JSON Order Object
Пример: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/2/complete?clientApiId=xxxx
ФОРМАТ ОТВЕТОВ
- JSONRequestObject
Пример
запрос: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/register/?clientApiId=xxxxxx&requestNumber=5399&orderNu
mber=11225&orderStatus=PENDING&orderSum=1251&fio=Alex&email=alex@calltouch.ru&phon
eNumber=79163223554&personalPhone=true
ответ:
{"requestNumber":"5399","status":"NOT_SET","client":{"fio":"Alex","phones":[{"phoneNumber":"79
163223554","phoneType":"PERSONAL"}],"contacts":[{"contactType":"EMAIL","contactValue":"alex
@calltouch.ru"}]},"order":{"orderNumber":"11225","orderSum":"1251","orderStatus":"PENDING","
orderComments":null},"session":null}
- JSON Order Object
Пример
запрос: http:// api.calltouch.ru/callsservice/RestAPI/requests/orders/2/approve?clientApiId=xxxx
ответ:
{"orderNumber":"2","orderSum":"1251","orderStatus":"APPROVED","orderComments":null}
9