Общие правила API

Адрес и ключ

Запросы отправляются на адрес вашего кабинета: https://<логин>.agorta.ru/api/<метод>, где <логин> — имя кабинета (поддомен), например https://shop.agorta.ru/api/products.

Каждый запрос подписывается секретным ключом. Ключи создаются в разделе Интеграции → Подключения → Интеграция по API (см. Интеграция по API). Ключ передаётся одним из способов:

• заголовком Token: <ключ> — рекомендуется;
• параметром token=<ключ> в адресе или теле запроса.

Если ключ не передан или неверен, ответ будет {"success": false, "error": [...]}, и запрос не выполнится.

Общие и личные ключи

• Общие ключи кабинета — те, что вы создаёте на странице Интеграция по API. Дают полный доступ ко всем методам, в том числе к служебным методам синхронизации кассы.
• Личные ключи пользователей — их создаёт себе ИИ-помощник Макс, чтобы работать от имени пользователя. Запрос по такому ключу выполняется в правах этого пользователя: нужно то же право, что и для этого действия в личном кабинете («Список номенклатуры» — для GET /api/products, «Создание и редактирование номенклатуры» — для POST, «Удаление номенклатуры» — для DELETE и т. д.). Документы видны и создаются только тех типов, которые доступны пользователю; без права проведения документы сохраняются непроведёнными; закупочные цены отдаются только при праве «Просмотр закупочной цены». Автором изменений записывается этот пользователь. Нет права — ответ 403 с текстом «Нет прав: …», служебный метод — 403 «Метод недоступен для личного ключа».

Методы запросов

Данные для создания и изменения передаются в теле запроса в формате JSON (Content-Type: application/json). Если отправить тело как JSON не получается, передайте строку JSON в поле data формы multipart/form-data. Изображения загружаются обычной формой multipart/form-data.

Ответ

Ответ всегда в JSON. Общие поля:

Списки возвращают success: false, если по фильтру ничего не найдено, — это не сбой, а пустой результат.

Постраничный вывод

Списки отдаются страницами по 60 записей. Номер страницы — параметр page (по умолчанию 1). Читайте страницы по очереди, пока ответ не придёт пустым. У документов вместо страниц можно использовать limit и offset.

Сортировка

Параметр order — поле сортировки, для обратного порядка добавьте DESC (в адресе — order=title%20DESC). Допустимые значения перечислены у каждого метода; неизвестное значение заменяется сортировкой по умолчанию.

Ограничения

• За один запрос можно создать не больше установленного для кабинета количества документов. При превышении придёт код HTTP 413 и поле api_count с допустимым максимумом — разбейте данные на части.
• Время выполнения одного запроса ограничено одной минутой. Большие выгрузки делайте постранично.
• Во время технического обслуживания сервиса (бывает редко) на запросы приходит код HTTP 418. Повторите запрос позже — данные при этом не теряются, если ваша программа отправит их снова.

Значения, которые встречаются в разных методах

Тип НДС (vat_type): 0 — без НДС, 1 — начислить сверху цены, -1 — выделить из цены. Ставка НДС (vat): 0, 5, 7, 10, 22.

Признак предмета расчёта (ppr): 1 — товар, 2 — подакцизный товар, 3 — работа, 4 — услуга, 5 — материал, 9 — комбинация.

Система налогообложения (sno): 0 — как у организации, 01 — ОСН, 02 — УСН «доходы», 04 — УСН «доходы минус расходы», 10 — ЕСХН, 20 — патент.

ЕГАИС (egais): 0 — не учитывается, 1 — алкоголь, 2 — пиво.

Удалённые записи: поле date_delete равно 0 у действующей записи и времени удаления — у удалённой. Время (date_update, date_delete) — в секундах от 01.01.1970 (UNIX-время).

Методы

• Номенклатура — список, создание, изменение, удаление, изображения.
• Категории номенклатуры.
• Справочники — бренды, единицы измерения, метки, склады.
• Контрагенты и группы контрагентов.
• Документы — список, создание, проведение, печатные формы.