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

Собрали ответы на самые распространенные вопросы в процессе работы с API KeyCRM
Автор Анастасія Останіна
Обновлено 2 недели назад
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. Как получить остаток из колонки «Доступно» с учетом резервов?

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

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

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

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

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

Рекомендуем добавить валидацию email на стороне вашего сайта, мобильного приложения или другой системы, которая передает данные через API. Это уменьшит количество ошибок и обеспечит корректность контактной информации. Также стоит проверять данные на сервере для дополнительной защиты от некорректного ввода.

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

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

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

16. Почему я получаю заказы, созданные в другие даты, чем указываю в фильтре created_between?

Ответ: 

  • Фильтр created_between работает именно по дате создания в CRM ("created_at"), а не по дате создания на источнике ("ordered_at"), которое может не совпадать с "created_at".  Поэтому проверьте верные ли даты вы передаете;
  • Время во всех сущностях используется UTC (GMT+0), поэтому следует учесть его при указании даты.

17. Как настроить передачу статусов заказа из CRM на сайт?

Ответ: Один из вариантов реализации автоматического изменения статусов заказов из CRM на сайт:

  1. На сайте добавить скрипт, который будет получать и сохранять список статусов из CRM и прописать соответствие статусов между сайтом и CRM;
  2. В CRM настроить триггер, который будет автоматически отправлять вебхук при изменении статуса заказа;
  3. Реализовать скрипт на сайте, который будет принимать данные от CRM, находить соответствующий заказ по его номеру и менять статус на сайте в соответствии со статусом в CRM.

Как это будет работать:

  • Меняется статус заказа в CRM и срабатывает триггер, который отправляет на сайт JSON с данными этого заказа. Он включает «source_uuid» (номер заказа на сайте) и «status_id» (ID статуса в CRM);
  • Скрипт на сайте принимает данные, находит заказ по «source_uuid» и обновляет его статус в соответствии с переданным «status_id» из CRM.

Теги: апи, ошибка апи, запросы api, работа с api, работа с api, Swagger, свагер
Оцените эту статью