Перейти к содержанию

Заказы (сделки)

Авторизация

Все запросы требуют API-ключ и номер проекта для авторизации. API-ключ можно посмотреть в настройках профиля.

Номер проекта можно передавать в URL запроса, например: https://cloud.roistat.com/api/v1/project/integration/order/list?project=12345

API-ключ можно передавать двумя способами:

  • Устанавливая HTTP-заголовок Api-key(рекомендуемый способ):

    Api-key: 1234567890qwerty
    
  • Добавляя параметр key в URL запроса (небезопасный способ):

    https://cloud.roistat.com/api/v1/project/integration/order/list?key=1234567890qwerty&project=12345
    

Получить список заказов из проекта Roistat

POST /project/integration/order/list

Данный метод используется для получения списка заказов из проекта Roistat.

Если вместе с заказом вам нужна подробная информация по его визиту, то в теле запроса укажите "extend": ["visit"].

В теле запроса можно использовать стандартные фильтры через массив filters. Фильтрация недоступна по свойствам визита, дополнительным полям заказа и полю "source_type".

Можно настроить фильтр по воронке статуса сделки, используя параметр "status" и следующие значения: "0" – статусы воронки «В работе», "1" – статусы воронки «Оплаченные», "2" – статусы воронки «Отмененные».

Обратите внимание: в будущем поле "visit_id" будет убрано из ответа метода.

Ограничения по количеству запросов:

Если передается extend":["visit"]:

  • Если лимит строго больше 1000: 1 запрос в минуту.
  • Если лимит строго больше 100: 5 запросов в минуту.
  • Если лимит меньше 100: 10 запросов в минуту.

Если не передается "extend":["visit"]:

  • 20 запросов в минуту.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/integration/order/list?project=12345

Тело запроса:

{
    "filters": {
        "and": [
            [
                "creation_date",
                ">",
                "2016-05-21T21:00:00+0000"
            ],
            [
                "creation_date",
                "<",
                "2016-05-22T21:00:00+0000"
            ],
            [
                "status",
                "=",
                "2"
            ]
        ]
    },
    "extend": [
        "visit"
    ],
    "limit": 100,
    "offset": 0
}
{
    "data": [
        {
            "id": "95101",
            "url": "http://roistat.com/index.php?order/info&order_id=95101",
            "source_type": "standard",
            "creation_date": "2016-06-19T00:32:12+0000",
            "update_date": "2016-06-19T02:00:07+0000",
            "revenue": 0,
            "cost": 0,
            "client_id": "78173",
            "visit_id": "4336465",
            "custom_fields": {
                "Менеджер": "Иванов Иван",
                "roistat": 4336465,
                "status_name": "0. Открыт"
            },
            "status": {
                "id": "1",
                "type": "progress",
                "name": "0. Открыт"
            },
            "visit": null,
            "page": "http://mylandingaddress.com/"
        }
    ],
    "total": 1,
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Параметр Тип Описание Обязательный
filters object нет
and array[string] нет
extend array[string] нет
limit integer нет
offset integer нет
Параметр Тип Описание Обязательный
data array[object] нет
id string ID заказа из CRM нет
url string URL заказа в CRM нет
source_type string тип созданной заявки нет
creation_date string дата и время создания заказа в формате UTC0 нет
update_date null или string дата и время последнего изменения данных о заказе, в формате UTC0 нет
revenue null или integer выручка по заказу нет
cost null или integer себестоимость нет
roistat null или integer Значение поля roistat нет
visit_id null или string номер визита клиента нет
custom_fields object дополнительные поля нет
>> Менеджер null или string нет
>> roistat null или integer нет
>> status_name string нет
status object данные о статусе заказа нет
>> id string уникальный номер статуса в системе Roistat нет
>> type string тип статуса в системе Roistat, соответствует одной из 3-х групп, по которым вы распределяли статусы, загрузившиеся из вашей CRM в Roistat: - unused - группа "Не учитываются" - in progress - группа "В работе" - paid - группа "Оплаченные" - canceled - группа "Отмененные" нет
>> name string человекочитаемое название статуса в CRM нет
visit null или object Подробные данные о визите заказа. Будут отображены, только если при запросе было указано "extend": ["visit"]. В противном случае будет null. Подробнее о данных визита читайте в методе /project/site/visit/list нет
client_id null или string ID клиента нет
page null или string Страница создания заказа нет
total integer нет
status string нет

Загрузить информацию о заказах в проект

POST /project/add-orders

Метод используется для загрузки информации о заказах. Доступен только при интеграции через API.

Возможность загружать товары доступна в режиме ограниченного бета-тестирования и доступна только на проектах с включенной Товарной аналитикой.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/add-orders?project=12345

Тело запроса:

[
    {
        "id": "1",
        "name": "New order",
        "date_create": "1393673200",
        "status": "0",
        "roistat": "12345",
        "price": "222",
        "cost": "111",
        "client_id": "123",
        "fields": {
            "Manager": "Валера"
        },
        "products": [
            {
                "id": "product_1",
                "name": "Стегозавр",
                "quantity": 2,
                "price": 1233,
                "cost": 780,
                "brand": "WooBoo",
                "variant": "зеленый",
                "category": {
                    "level1": "Интерактивные игрушки",
                    "level2": "Игрушки с хвостом",
                    "level3": "Динозавры",
                    "level4": "С шипами",
                    "level5": "Травоядные"
                }
            }
        ],
        "history": [
            {
                "date": "1393673300",
                "price": 2233,
                "cost": 780,
                "status ": "1"
            }
        ]
    },
    {
        "id": "2",
        "name": "New order",
        "date_create": "1393673200",
        "status": "0",
        "roistat": "67890",
        "price": "333",
        "cost": "222",
        "client_id": "124",
        "fields": {
            "Manager": "Валера"
        }
    }
]
{
    "uploaded": 0,
    "processed": 0,
    "skipped_by_status": 0,
    "skipped_by_waiting_visit_info": 0,
    "skipped_by_internal_error": 0,
    "skipped_because_not_changed": 0,
    "skipped_fields_by_invalid_format": 0,
    "saved": 0,
    "comment": "",
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Параметр Тип Описание Обязательный
id string ID сделки в CRM нет
name string человекочитаемое название сделки в CRM нет
date_create string дата создания сделки в формате: - UNIX-time - YYYY-MM-DD HH:MM:SS по московскому времени - YYYY-MM-DD HH:MM:SS с указанием смещения относительно UTC (например, 2016-12-12 11:30:10+0000) Если дата передается как 2016-12-12 11:30:10, она воспринимается как 2016-12-12 11:30:10+0300 Если в данное поле будет передана дата некорректного формата, то заказ будет пропущен. В ответе, в поле 'skipped_by_invalid_format' будет указано число заказов пропущеных из-за некорректного формата даты, а в поле 'comment' будут указаны id заказов, содержащих ошибку нет
status string ID статуса из массива statuses нет
roistat null или string номер визита нет
price null или string сумма сделки; используется в показателе "Выручка" в Roistat нет
cost null или string себестоимость сделки нет
client_id string ID клиента в CRM нет
fields object дополнительные поля. - ограничение по каждому полю - 1000 символов. нет
object нет
>>  string нет
products array[object] нет
id string id товара нет
name string наименование товара нет
quantity integer количество товаров нет
price number стоимость единицы товара нет
cost number себестоимость товара нет
brand string бренд товара нет
variant string разновидность товара (например "красный цвет" или "шнурок 5 см" нет
category object категории товара (вложенность до 5-го уровня) нет
>> level1 string нет
>> level2 string нет
>> level3 string нет
>> level4 string нет
>> level5 string нет
history array[object] история сделки нет
date string дата изменения сделки нет
price null или number сумма сделки (может быть отрицательной) нет
cost null или number себестоимость сделки нет
status string статус сделки нет
Параметр Тип Описание Обязательный
uploaded integer количество загруженных сделок нет
processed integer нет
skipped_by_status integer нет
skipped_by_waiting_visit_info integer нет
skipped_by_internal_error integer нет
skipped_because_not_changed integer нет
skipped_by_invalid_format integer нет
skipped_fields_by_invalid_format integer нет
comment string нет
saved integer нет

Получить внешний URL-адрес заказа из CRM

GET /project/orders/{orderId}/external-url

Воспользуйтесь данным методом для получения внешнего URL-адреса заказа из CRM.

Строка запроса:

GET https://cloud.roistat.com/api/v1/project/orders/123/external-url?project=12345

Тело запроса:

Без параметров.

{
    "externalUrl": "http://new123qwerty.amocrm.ru/leads/detail/123",
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Без параметров.

Параметр Тип Описание Обязательный
externalUrl string URL заказа в CRM нет
status string нет

Загрузить статусы сделок в проект

POST /project/set-statuses

Данный метод используется для загрузки статусов.

Все используемые статусы необходимо передавать в одном массиве, а не по отдельности. Если вы хотите добавить новые статусы, то в новом запросе необходимо передать и старые, и новые статусы.

Тип статуса в системе Roistat соответствует одной из трёх групп, по которым распределялись статусы, загрузившиеся из вашей CRM в Roistat:

  • progress - группа В работе
  • paid - группа Оплаченные
  • canceled - группа Отмененные

Если ID нового статуса совпадает с ранее загруженным, производится замена.

Данный метод доступен только при интеграции по API.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/set-statuses?project=12345

Тело запроса:

[
    {
        "id": "1",
        "name": "New",
        "type": "progress"
    },
    {
        "id": "2",
        "name": "inProgress",
        "type": "progress"
    }
]
{
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Параметр Тип Описание Обязательный
id string уникальный номер (ID) статуса в системе Roistat нет
name string человекочитаемое название статуса в CRM нет
type string тип статуса в системе Roistat, соответствует одной из 3-х групп, по которым вы распределяли статусы, загрузившиеся из вашей CRM в Roistat: progress - группа "В работе" paid - группа "Оплаченные" canceled - группа "Отмененные" нет
Параметр Тип Описание Обязательный
status string нет

Получить список дополнительных полей из CRM

POST /project/analytics/order-custom-fields

Данный метод используется для получения списка дополнительных полей сделок из вашей CRM.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/analytics/order-custom-fields?project=12345

Тело запроса:

Без параметров.

{
    "fields": [
        "Город",
        "Касса",
        "Менеджер"
    ],
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Без параметров.

Параметр Тип Описание Обязательный
fields object человекочитаемые названия полей сделок из CRM нет
field1 string нет
field2 string нет
field3 string нет
status string нет

Обновить статус сделки

POST /project/integration/order/{orderId}/status/update

Метод для обновления статуса сделки.

Доступен только при интеграции с целями или интеграции через API.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/integration/order/123/status/update?project=12345

Тело запроса:

{
    "status_id": "1"
}
{
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Параметр Тип Описание Обязательный
status_id string ID статуса в Roistat нет
Параметр Тип Описание Обязательный
status string нет

Обновить информацию по сделке в проекте

POST /project/integration/order/{orderId}/goal/update

Метод обращается к проекту и по ID проксилида обновляет информацию в проекте. Метод доступен только в интеграции с целями.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/integration/order/{orderId}/goal/update?project=12345

Тело запроса:

{
    "status": "success"
}

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Параметр Тип Описание Обязательный
string нет
Параметр Тип Описание Обязательный
status string нет

Удалить сделку

POST /project/integration/order/{orderId}/delete

Метод для удаления сделки.

Доступен только при интеграции через API.

Строка запроса:

POST https://cloud.roistat.com/api/v1/project/integration/order/{orderId}/delete?project=12345

Тело запроса:

Без параметров.

Строка запроса:

Параметр Тип Описание Обязательный
project string Номер проекта да

Тело запроса:

Без параметров.

Параметр Тип Описание Обязательный
status string нет