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

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

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

Обновлено 3 дня назад

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

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

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

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

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

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

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

Исключением являются системные статусы "Новый", "Выполнен" и "Отменен" — они зарезервированы, поэтому изменить их невозможно.

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

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

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

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

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

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

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

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

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

7. Как отправить запрос к API с помощью документации?

Ответ: Для этого выберите нужный метод и нажмите «Test Request».

Затем введите свой API-ключ и заполните остальные обязательные поля с пометкой «Required». При желании заполните остальные поля и нажмите «Send»:

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".

К примеру, на дату в "updated_at" заказа не влияют изменения в полях:

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

На дату в "updated_at" товара не влияют изменения через API в полях:

Артикул (его сложение, если поле было пустым);
Штрихкод;
Закупочная стоимость;
Стоимость.

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

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

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

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

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

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

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

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

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

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

15. Как получить коллекцию методов для Postman?

Ответ: Чтобы получить готовую коллекцию методов, нажмите кнопку «Run in Postman» в документации. Для использования необходимо указать ваш API-ключ в переменной api_token в коллекции (Edit → Variables).

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

Ответ:

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

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

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

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

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

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

18. Как оптимизировать запросы, чтобы не получить блокировку?

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

Создание большого количества товаров: используйте метод массового импорта — до 100 товаров в одном запросе;
Создание большого количества заказов: метод массового импорта — до 50 заказов за раз;
Создание большого количества покупателей: метод массового импорта — до 50 покупателей в одном запросе;
Обновление товаров: для изменения цены, закупочной стоимости или размеров воспользуйтесь методом обновления вариантов товара — до 10 000 товаров в одном запросе. Идентификаторы вариантов необязательны — достаточно артикула и нужных полей. Работает и для товаров без вариантов (они имеют один вариант по умолчанию);
Получение остатков: вместо периодических проверок остатков через API, используйте вебхуки — это позволяет получать обновления автоматически;
Получение изменений статуса заказа или статуса оплаты заказа: вместо получения всех заказов и проверки этих полей вы можете настроить отправку вебхуков именно по этим изменениям;
Получение списков (GET-запросы): убедитесь, что используете максимальный доступный лимит — ?limit=50. Если, например, указано ?limit=15, количество запросов возрастает, что нагружает API. Или если указано количество более 50, это выходит за лимит и может привести к блокировке.

Это базовые рекомендации. Если вы сталкиваетесь с лимитами и не знаете, как оптимизировать работу с API — обратитесь в нашу поддержку, и мы поможем.

19. Почему при получении карточки или заказа с товарами id не соответствует id товара из каталога?

Ответ: При получении карточки воронки или заказа поле products.id не соответствует идентификатору товара из каталога, поскольку это разные сущности.

products.id — это идентификатор товарной позиции в рамках конкретного заказа или карточки, то есть отдельной записи товара, которая была добавлена в эту карточку / заказ.

Если товар связан с каталогом, идентификаторы передаются отдельно:

При получении карточки воронки дополнительно передаётся offer_id — идентификатор варианта товара. По нему можно получить вариант и product_id товара из каталога, к которому относится данный вариант.
При получении заказа передаётся объект offer, в котором:
- id — идентификатор варианта товара;
- product_id — идентификатор товара из каталога.

Теги: апи, ошибка апи, запросы api, работа с api, работа с api, опенапі, опен апі, лимиты, оптимизировать

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