DataMatrix

Даты приёмки и отгрузки ЧЗ: инструкция для интеграции

Эти поля позволяют узнать, когда конкретный код был принят и отгружен на его текущем складе. API возвращает последнее зарегистрированное событие каждого вида. Дата документа и дата погашения при маркировке не заменяют эти события.

Доступность: для работы требуется версия приложения с поддержкой этих полей и установленная таблица событий ЧЗ. Обновление инструкции само по себе не означает обновление сервера API. Перед использованием проверьте наличие обоих ключей в ответе GET по известному доступному коду.

Что потребуется

Адрес вашего сервера NWMS, персональный API-токен с правом просмотра ЧЗ (datamatrix.view) и доступ к нужному складу. Передавайте Authorization: Bearer … и Accept: application/json. Токен нельзя помещать в URL. Примеры используют учебные даты и ID; замените их своими.

Формат и смысл дат

Новые поля имеют формат ISO 8601 с секундами и явным часовым поясом, например 2026-10-22T10:15:00+03:00, либо null. Смещение соответствует часовому поясу установки; не считайте его всегда равным +03:00. История ограничена текущими доменом и складом кода. Если код принимали несколько раз, возвращается последняя зарегистрированная приёмка, а не список событий.

null означает отсутствие зарегистрированного события на текущем складе. Старые неизвестные даты не восстанавливаются по документам. Загрузка кода, ручная смена статуса и погашение не считаются физической приёмкой или отгрузкой. Поля предназначены только для чтения: не передавайте их в POST или изменение статуса.

Как работают фильтры и сортировка

• _from — нижняя граница, _to — верхняя. Можно передать одну или обе. Диапазоны приёмки и отгрузки применяются одновременно через AND.
• Дата 2026-10-22 интерпретируется в часовом поясе установки. Верхняя граница включает весь день до следующей полуночи. Одинаковые даты from/to выбирают события за один день.
• Для точного времени передавайте 2026-10-22T10:15:00Z либо 2026-10-22T10:15:00+03:00. Обе точные границы включены, сравнение выполняется в UTC. Дробные секунды и время без смещения не поддерживаются. Знак + в URL кодируйте как %2B; в cURL используйте --data-urlencode.
• Фильтры можно передать прямо в query либо как filter[accepted_at_from] (для legacy — filter[dmt_accepted_at_from]). Прямой параметр имеет приоритет. Пустая строка не задаёт границу.
• В sort укажите имя поля; знак - задаёт убывание. Несколько полей разделяются запятой. При равных значениях используется ID кода по возрастанию. null идёт первым при возрастании и последним при убывании. При фильтрации непустым диапазоном строки с null исключаются.

Пример: принятые за день, сначала последние

Задайте NWMS_BASE_URL адресом своего сервера, а NWMS_TOKEN — токеном в своём окружении. Оба запроса только читают данные.

curl --get "${NWMS_BASE_URL}/api/v2/datamatrix" \
    --header "Authorization: Bearer ${NWMS_TOKEN}" \
    --header "Accept: application/json" \
    --data-urlencode 'warehouse_id=42' \
    --data-urlencode 'accepted_at_from=2026-10-22' \
    --data-urlencode 'accepted_at_to=2026-10-22' \
    --data-urlencode 'sort=-accepted_at,id' \
    --data-urlencode 'per_page=100'

curl --get "${NWMS_BASE_URL}/api/datamatrix" \
    --header "Authorization: Bearer ${NWMS_TOKEN}" \
    --header "Accept: application/json" \
    --data-urlencode 'dmt_wh_id=42' \
    --data-urlencode 'dmt_accepted_at_from=2026-10-22' \
    --data-urlencode 'dmt_accepted_at_to=2026-10-22' \
    --data-urlencode 'sort=-dmt_accepted_at,dmt_id' \
    --data-urlencode 'per_page=100'

Пример: отгрузки с точного момента

GET /api/v2/datamatrix?shipped_at_from=2026-10-22T10:15:00%2B03:00&sort=shipped_at,id
GET /api/datamatrix?dmt_shipped_at_from=2026-10-22T10:15:00%2B03:00&sort=dmt_shipped_at,dmt_id

Пример строки ответа

Ниже показаны только нужные поля одного элемента data[]; остальные поля и оболочка ответа сохранены.

// API v2: data[0]
{"id":1001,"created_at":"2026-10-19","accepted_at":"2026-10-22T10:15:00+03:00","shipped_at":null}
// Legacy: data[0]
{"dmt_id":1001,"dmt_created_date":"2026-10-19","dmt_accepted_at":"2026-10-22T10:15:00+03:00","dmt_shipped_at":null}

Проверка результата и обработка ошибок

1. Получите один известный код без фильтра дат. Отсутствие новых ключей означает, что сервер ещё не поддерживает этот контракт; null в существующем ключе означает неизвестную дату.
2. Сверьте даты с записью ЧЗ на том же складе. Проверьте, что used_at / dmt_used_date обрабатываются отдельно как дата погашения.
3. Примените диапазон одного дня и проверьте обе границы и порядок. Загружайте все страницы: v2 использует links.next и meta, legacy — next_page_url и поля пагинации верхнего уровня. Обе версии принимают page и per_page, максимум 500 строк на страницу.
4. 422: исправьте неверную дату, время без часового пояса, массив вместо строки или обратный диапазон. 401: проверьте токен. 403: проверьте права и доступ. Пустой data при успешном ответе не является ошибкой: подходящих доступных кодов может не быть.

Если таблица событий ещё не установлена, новые поля будут null, а отбор по ним вернёт пустой список; администратор должен проверить установку миграции. Диапазоны работают по последнему событию и не заменяют журнал всех событий или курсор изменений: для выгрузки истории/инкрементальной синхронизации не полагайтесь только на эти даты.