Практическое руководство API v2

1. Сервер, токен и первый запрос

Базовый URL — адрес вашей установки NWMS без /api/v2. Документация localhost описывает локальный код; доступность нового метода на другом сервере зависит от установленного выпуска. Используйте Bearer-токен своей учётной записи. Права и область данных пользователя сохраняются при обращении через API.

export NWMS_BASE_URL='https://YOUR-NWMS-HOST'
export NWMS_TOKEN='YOUR-TOKEN'
export NWMS_REQUEST_KEY='UNIQUE-KEY-FOR-ONE-OPERATION'
curl --globoff "${NWMS_BASE_URL}/api/v2/products?per_page=1" \
  --header "Authorization: Bearer ${NWMS_TOKEN}" \
  --header 'Accept: application/json'

2. Структура запроса и ответа

3. Фильтры, сортировка и выгрузка

Допустимые фильтры перечислены у каждого endpoint. Типовой формат — filter[field]; сортировка sort=-updated_at,id задаёт убывание даты и возрастание ID. include включает только разрешённые связи. Для уведомлений per_page по умолчанию 50, максимум 250; другие методы могут иметь иной предел. Передавайте query-параметры через URL-кодирование, особенно кириллицу, плюс в часовом поясе и квадратные скобки.

curl --get "${NWMS_BASE_URL}/api/v2/notification-templates" \
  --header "Authorization: Bearer ${NWMS_TOKEN}" \
  --header 'Accept: application/json' \
  --data-urlencode 'filter[status_id]=1' \
  --data-urlencode 'filter[name]=Приёмка' \
  --data-urlencode 'include=bindings' \
  --data-urlencode 'sort=-updated_at,id' \
  --data-urlencode 'per_page=50' \
  --data-urlencode 'page=1'

При выгрузке сохраняйте одинаковые фильтры и сортировку на всех страницах, переходите по links.next до null. Изменяющаяся база не является снимком: храните ID и updated_at, устраняйте повторения на своей стороне. after_id используйте только там, где он явно документирован. Для created_at/updated_at граница YYYY-MM-DD включает весь день в часовом поясе приложения; явно согласуйте часовой пояс сервера при синхронизации.

4. Идемпотентность и восстановление после таймаута

Для обычных изменяющих v2-операций с этим middleware Idempotency-Key необязателен, но рекомендуется; максимум 191 символ. Успешный ответ хранится сутки в области пользователя, HTTP-метода и пути. Повтор должен содержать тот же URL и те же байты тела: даже другая сериализация одинакового JSON может дать конфликт. Ответ повтора содержит Idempotency-Replayed: true. Ошибочные ответы не сохраняются как успешный результат.

5. Обработка ошибок

Не полагайтесь на один универсальный error: cross-dock использует meta.error_code, а обычный конфликт ключа — error. Точная схема и примеры приведены у каждой операции.

Документы, партии и фактические остатки