Обращение к API

laxo API принимает запросы одним из трех способов:

POST. Вызываемые методы и их параметры передаются в массиве JSON-объектов.
GET. Вызываемый метод указывается в URL, а параметры запроса передаются в виде GET-параметров.
Гибридный способ. Вызываемый метод указывается в URL, а параметры запроса передаются в JSON-теле аналогично способу POST.

Выбор способа зависит от предполагаемого сценария использования API. Способ POST является рекомендуемым, так как поддерживает отправку цепочки запросов, а также является более безопасным с точки зрения передачи чувствительных данных.

Вызов каждого метода описывается основными параметрами: class, method, sid, param. С помощью class и method указывается метод API, к которому идет обращение, в sid – идентификатор сессии (токен), а в param – параметры запроса. Также допускается передача необязательного параметра lang, который отвечает за язык, на котором возвращается ответ. Подробную информацию о значении каждого параметра можно найти в разделе Список методов.

Со структурой запроса лучше всего познакомиться на примерах:

// jQuery
$.ajax({
  url: "https://<<DOMAIN>>.laxo.one/api/", // <<DOMAIN>> – адрес вашего портала
  method: "POST",
  contentType: "application/json",
  dataType: "json",
  data: JSON.stringify(
  [
    {
      "class": "order_status", // Категория метода
      "method": "get_list",    // Название метода
      "sid": "<<SID>>",        // Идентификатор сессии (токен)
      "lang": "ru",            // Локаль обращения (необязательно)
      "param": {
        "funnel_id": 1         // Параметры запроса
      }
    }
  ])
});

// jQuery
$.ajax({
  url: "https://<<DOMAIN>>.laxo.one/rest/bonus/send_code/?phone=79999999999", // Адрес, метод и параметр указаны явно в URL
  method: "GET",
  dataType: "json"
});

// jQuery
$.ajax({
  url: "https://<<DOMAIN>>.laxo.one/rest/order_status/get_list/?funnel_id=1", // Адрес, метод и параметр указаны явно в URL
  method: "POST",
  contentType: "application/json",
  dataType: "json",
  data: JSON.stringify(
  [
    {
      "sid": "<<SID>>"  // Идентификатор сессии (токен)
    }
  ])
});

Для способа POST адрес конечной точки: https://<<DOMAIN>>.laxo.one/api/, где:
<<DOMAIN>> – адрес портала (аккаунта), с данными которого нужно взаимодействовать.
Для способа GET и гибридного способа адрес конечной точки: https://<<DOMAIN>>.laxo.one/rest/:class/:method/?param, где:
<<DOMAIN>> – адрес портала (аккаунта), с данными которого нужно взаимодействовать;
:class – категория метода;
:method – имя вызываемого метода;
?param – параметры запроса в формате key1=value1&key2=value2 (необязательно).
Способ GET подходит для обращения к методам без обязательного SID (токена), так как передача SID в URL не поддерживается. Для методов с авторизацией используйте POST или гибридный способ.
Для способа POST и гибридного способа параметры передаются в виде массива объектов. Такой подход позволяет делать несколько обращений в одном запросе, передавая данные между вызываемыми методами.

Если при отправке запроса методом POST параметры переданы как одиночный объект (вместо массива объектов), то API возвращает пустой ответ.

Цепочка команд

API по умолчанию поддерживает вызов сразу нескольких методов в одном запросе, что позволяет оптимизировать число запросов, а также организовать взаимодействие между методами в рамках одного запроса с помощью параметров RESULT_TO_PARAM и RESULT_TO_PROPERTY

// jQuery
$.ajax({
  url: "https://<<DOMAIN>>.laxo.one/api/", // <<DOMAIN>> – адрес вашего портала
  method: "POST",
  contentType: "application/json",
  dataType: "json",
  data: JSON.stringify(
  [
    // Первая команда в цепочке запросов:
    // Получаем список сообщений чата
    {
      "class": "message",
      "method": "get_list",
      "sid": "<<SID>>",   // Идентификатор сессии (токен)
      "param": {
        "chat_id": 123
      }
    },

    // Вторая команда в цепочке запросов:
    // Отмечаем первое сообщение из списка прочитанным
    {
      "class": "message",
      "method": "read",
      "sid": "<<SID>>",           // Идентификатор сессии (токен)
      "result_to_param": {        // Вставить результаты предыдущей команды в параметры текущей
        "id": 0,
        "index": 0,
        "property": "message_id"  // Передать только message_id, а не все свойства из ответа
      }
    },
  ])
});

// Если первая команда возвращает:
{
  "message_id": 10,
  "message_text": "Здравствуйте!"
}

// То полный запрос второй команды выглядит так:
{
  "class": "message",
  "method": "read",
  "param": 10,
  "sid": "<<SID>>"
}

// jQuery
$.ajax({
  url: "https://<<DOMAIN>>.laxo.one/api/", // <<DOMAIN>> – адрес вашего портала
  method: "POST",
  contentType: "application/json",
  dataType: "json",
  data: JSON.stringify(
  [
    // Первая команда в цепочке запросов:
    // Получаем данные контакта
    {
      "class": "contact",
      "method": "get",
      "sid": "<<SID>>",   // Идентификатор сессии (токен)
      "param": {
        "contact_id": 10
      }
    },

    // Вторая команда в цепочке запросов:
    // Создаем сделку, добавляя в параметры ответ предыдущей команды
    {
      "class": "order",
      "method": "add",
      "sid": "<<SID>>",                 // Идентификатор сессии (токен)
      "param": {
        "order_name": "Новая заявка"
      },
      "result_to_property": {           // Вставить результаты предыдущей команды в параметры текущей
        "id": 0,                        // Берем данные из первой команды (необязательное свойство)
        "property": "contact_id",       // Имя свойства из ответа, значение которого нужно передать
        "name": "contact_id"            // Имя параметра, куда нужно передать значение свойства contact_id из ответа
      }
    },
  ])
});

// Если первая команда возвращает:
{
  "contact_id": 10,
  "contact_name": "Иван",
  "contact_phone": "79999999999"
}

// То полный запрос второй команды выглядит так:
{
  "class": "order",
  "method": "add",
  "param": {
    "order_name": "Новая заявка",
    "contact_id": 10
  },
  "sid": "<<SID>>"
}

Используйте параметр result_to_param.id или result_to_property.id для указания номера команды, из которой нужно взять ответ. Параметр является необязательным, если нужно выбрать данные первой команды.
Используйте параметр result_to_param.index или result_to_property.index для указания порядкового номера объекта, если первая команда вернула вместо одного объекта, например данные указанного контакта, массив объектов (список контактов). Параметр является необязательным, если команда возвращает одиночный объект, а не массив.
Используйте result_to_param, если параметры второй команды нужно полностью заменить ответом первой команды.
Используйте result_to_property, если параметры второй команды нужно частично заменить ответом первой команды, например подставив значение только одного параметра.
API не накладывает ограничений на количество вызываемых команд в одной цепочке запросов.

Ответ API

Вне зависимости от способа обращения к API в ответе всегда возвращается массив объектов, содержащих минимум 2 элемента: объект с ответом на вызываемую команду, объект с перечнем ошибок.

Если запрос включает N-команд (цепочка), то ответ состоит из массива объектов размером N+1, где первые N объектов соответствуют каждой отправленной команде, а последний элемент содержит служебную информацию: список ошибок и SID (при использовании).

Каждый объект содержит два свойства: code – код ответа и response – содержимое ответа.

При отсутствии ошибок в response последнего объекта свойство errs отсутствует.
При возникновении ошибки в одной из вызываемых команд остальные продолжают выполнение.

Структуру ответа лучше всего рассмотреть на примерах:

[
  // Успешное выполнение какой-то команды. Код ответа – 200.
  {
    "code": 200,
    "response": {
      "RU": {
        "price": "390.00",
        "currency": "RUB",
        "icon_currency": "ruble-sign"
      }
    }
  },
  // Дополнительный элемент ответа со списком ошибок (отсутствуют)
  {
    "code": 200,
    "response": []
  }
]

[
  // Выполнение команды было прервано ошибкой (код ошибки – 701).
  {
    "code": 701,
    "response": null
  },
  // Дополнительный элемент ответа со списком ошибок
  {
    "code": 200,
    "response": {
      "errs": {
        "701": "Некорректные данные запроса."
      },
      "sid": "<<SID>>"
    }
  }
]

[
  // Первая команда завершилась с ошибкой
  {
    "code": 701,
    "response": null
  },
  // Вторая команда выполнилась успешно (код ответа - 200)
  {
    "code": 200,
    "response": {
      "unsubscribed": true
    }
  },
  // Дополнительный элемент ответа со списком ошибок
  // Использован редкий случай: команда сообщила о некритичной ошибке 704, но не прервала свою работу
  {
    "code": 200,
    "response": {
      "errs": {
        "701": "Некорректные данные запроса.",
        "704": "Поясняющий текст к некритической ошибке."
      },
      "sid": "<<SID>>"
    }
  }
]

Список кодов ошибок приводится в описании к каждому методу. Полный список ошибок также доступен на этой странице.

Остались вопросы? Спросите в чате В нашем сообществе в Telegram можно быстро задать вопрос, получить подсказку от команды Laxo или обменяться опытом с другими пользователями.

Задать вопрос