Вопросы - Ответы (FAQ) по Open API

Собрали ответы на самые распространенные вопросы в процессе работы с API KeyCRM

Автор Анастасія Останіна

Обновлено 1 неделю назад

1. Как происходит авторизация при подключении к API?

Ответ: Для авторизации нужно передавать заголовок в формате Bearer + APIkey.

"headers":{"authorization":["Bearer ваш-API-ключ"]}

2. Как узнать, данные в какие поля я могу передавать и получать?

Ответ: В документации API описан каждый метод. Примеры запросов или ответов содержат список всех доступных параметров для этого метода.

На вкладке «Schema» подробно описан каждый доступный параметр с указанием типа данных и примером значения:

3. Почему название стандартных статусов заказов в АРІ возвращается транслитерацией?

Ответ: Стандартный набор статусов создается с алиасами в названиях - по ним подставляется в интерфейсе в соответствии с языком пользователя название статуса.

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

4. Как передать значение в несколько кастомных полей разных типов?

Ответ: Пропишите данные к каждому полю через запятую в массиве custom_fields.

Если поле с типом список или мультисписок, то список значений нужно передавать в параметре value в массиве. Все значения должны быть добавлены, как опции в этом поле.

"custom_fields": [
    {
      "uuid": "системна назва поля з CRM",
      "value": "Значення, яке потрібно записати в це поле"
    },
    {
      "uuid": "системна назва поля з CRM",
      "value": ["Опція 1", "Опція 2", "Опція 3"] 
    }
  ]

5. Почему GET запросом я получаю не все данные, как в примере в документации?

Ответ: По умолчанию передаются только базовые данные, чтобы получить все доступные дополнительные, добавьте к запросу include, к каждому методу в документации добавлен список доступных.

6. Что значит ошибка «Too Many Requests»?

Ответ: У нас действует ограничение до 60 запросов в минуту с одного IP-адреса по API-ключу. Если частота запросов больше этого лимита, запросы начинают получать эту ошибку.

Рекомендуем оптимизировать ваш процесс, чтобы снизить количество запросов. Например, вы можете настроить паузу между запросами в 1 секунду.

7. Почему я получаю ошибку при попытке сделать тестовый запрос через swager?

Ответ: В нашей документации нет возможности добавить API ключ, отправлять запросы и получать ответы от сервера. Поскольку запрос был бы отправлен из браузера. Именно такие запросы мы не обрабатываем в целях безопасности, потому что в таком случае API токен будет в открытом доступе, другие пользователи смогут его получить и с его помощью получить доступ к личным данным или редактировать информацию пользователей.

Вы можете только сгенерировать примеры нужных вам запросов для дальнейшего использования. И увидеть там примеры ответов и какие данные вы можете получить. А для проверки запроса можно использовать программы для работы с API, например POSTMAN.

8. Почему не создается заказ и получаю ошибку «The source uuid has already been taken»?

Ответ: Ошибка означает, что в этом источнике уже есть заказ с этим номером из источника (source_uuid). Соответственно повторно заказ с таким же номером создан не может быть, это проверка системы на дубли.

Возможно удалялись заказы на сайте или восстанавливали резервную копию (бэкап). Поскольку вероятно сбилась нумерация на сайте и использованные номера заказов снова стали доступными для новых заказов.

9. Почему не обновляется остаток товара по идентификатору?

Ответ: Скорее всего вы передали идентификатор, которого нет в системе. В методе на обновление остатков нужно передавать именно offer_id - идентификатор варианта товара, он не равен product_id (идентификатор товара).

Даже если у вас товары без вариантов, каждый из них имеет offer_id. Поскольку для системы товар без вариантов означает товар в одном варианте. Идентификаторы вариантов можно получить в файле экспорта или запросом на получение списка вариантов товаров по API.

Если вы используете артикулы, то остатки можно обновлять только передав sku, без необходимости получать и передавать идентификаторы вариантов.

10. Не отправляются запросы к API KeyCRM вообще, в чем может быть причина?

Ответ: Проверьте основные моменты:

На вашем сервере корректный SSL сертификат;
Запросы отправляются с сервера, а не из браузера;
Ваш хостинг провайдер не блокирует отправку запросов.

Если вы все проверили и сложность остается - напишите в нашу поддержку.

11. В заказе были изменения, но дата в поле updated_at не обновилась. Почему?

Ответ: Пока что не все изменения в заказе обновляют это поле, а именно изменения в полях:

Теги;
Ответственные;
ЮТМ-метки;
Файлы;
Задачи; Задачи;
Оплаты;
Тип отгрузки.

Изменения во всех остальных полях заказа будут обновлять дату в «updated_at».

12. Как добавить файл в карточку воронки или заказа?

Ответ: Чтобы добавить файл, сначала его нужно загрузить на сервер CRM. В ответе вы получите id (fileId) - идентификатор вашего файла в системе.

Далее уже можно передать запрос на добавление этого файла в карточку воронки или в заказ.

13. Как получить остаток из колонки «Доступно» с учетом резервов?

Ответ: Как при получении общих остатков по всем складам, так и при получении остатков по каждому складу отдельно вы получаете количество в двух полях:

«quantity» — общее количество остатков;
«reserve» — общее количество зарезервированных остатков.

Соответственно вы можете при получении добавить формулу расчета в скрипт и от общего остатка вычитать резерв, чтобы записывать именно количество доступное к продаже с учетом резерва по товарам.

14. Почему я получаю ошибку «The buyer.email must be a valid email address»?

Ответ: Ошибка означает, что передаваемый email не валиден. Адрес электронной почты должен быть в формате xxx@xxx.xxx без пробелов и спец.символов.

15. Как пользоваться Swagger?

Ответ: Swagger позволяет взаимодействовать с API через удобный веб-интерфейс, где можно просматривать документацию и сгенерировать примеры нужных вам запросов для дальнейшего использования, увидеть там примеры ответов и какие данные вы можете получить:

Перейдите в нашу документацию по API;
Выберите нужный метод;
Нажмите Try it out и заполните параметры;
Нажмите Execute, чтобы сформировать ссылку, взять curl и можно использовать в программе для работы с API, например POSTMAN или со своего сервера.

Теги: апи, ошибка апи, запросы api, работа с api, работа с api, Swagger, свагер

Оцените эту статью