Tec.Delivery требования к REST API для получения данных SCU

Документ описывает обязательные требования к REST API в части получения данных, включая поддержку GET и альтернативного режима POST с JSON-телом запроса.

1. Общие требования к endpoint получения данных

1.1 Поддерживаемые методы

• Вариант 1 — GET
  GET /api/v1/catalog
  Параметры передаются в query string.
• Вариант 2 — POST (для сложных фильтров и больших параметров)
  POST /api/v1/catalog
Content-Type: application/json
  Параметры передаются в JSON-теле запроса.

Назначение POST:

• передача длинных фильтров
• передача массивов ID
• избежание ограничений URL
• поддержка сложной фильтрации

2. Формат запроса (POST / JSON body)

Пример запроса:

{
  "modified_since": "2026-02-01T00:00:00Z",
  "limit": 100,
  "offset": 0,
  "parent": 123,
  "ids": ["20020", "20021"]
}

Допустимые параметры:

• modified_since
• limit
• offset
• cursor
• parent
• ids (массив ID)
• дополнительные фильтры при необходимости

Примечание по наименованиям полей: Наименования полей, приведённые в документе (например, modified_at, modified_since, image_url, image_hash, parent, next_cursor), указаны в качестве примера и могут отличаться в конкретной реализации.

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

Требования:

• JSON должен быть валидным
• Кодировка — UTF-8

3. Идентификаторы сущностей

Каждый объект должен содержать:

• id — уникальный и стабильный идентификатор
• type — тип сущности (category, product)
• parent — идентификатор родителя (0 или null для корня)

Требования:

• ID не должен изменяться
• parent-связь должна быть валидной

4. Контроль изменений данных

Каждый объект должен содержать:

• modified_at — дата и время последнего изменения (ISO 8601, UTC)

Пример:

"modified_at": "2026-02-09T12:45:33Z"

Назначение: определение изменений с момента последней синхронизации.

5. Инкрементальное получение данных

API должно поддерживать получение только изменённых данных.

Параметр: modified_since

Поддерживается как:

• query-параметр (GET)
• JSON-поле (POST)

Пример GET:

GET /api/v1/catalog?modified_since=2026-02-01T00:00:00Z

Пример POST:

{
  "modified_since": "2026-02-01T00:00:00Z"
}

Поведение:

• Возвращаются только изменённые объекты
• Удалённые объекты также возвращаются (через is_deleted или deleted_at)

6. Пагинация (обязательная)

API должно поддерживать пагинацию.

Варианты:

• limit + offset
• cursor + next_cursor

Пример ответа (limit / offset):

{
  "data": [...],
  "total": 15420,
  "limit": 100,
  "offset": 200
}

Пример ответа (cursor):

{
  "data": [...],
  "next_cursor": "eyJpZCI6MjAwfQ==",
  "has_more": true
}

7. Отдельная передача изображений

Запрещено:

• передача изображений в Base64
• передача бинарных данных в списках

В ответе допускается только:

• image_url
• image_modified_at и/или image_hash

Пример:

{
  "id": "20020",
  "type": "product",
  "name": "Греча ядрица 900г Националь",
  "image_url": "https://example.com/images/20020.jpg",
  "image_hash": "a94a8fe5ccb19ba61c4c0873d391e987"
}

Требования к URL:

• URL должен быть публично доступен
• Не допускаются локальные IP (192.168.x.x, 10.x.x.x и т.п.)
• Загрузка изображения выполняется отдельным HTTP-запросом

8. Иерархическая структура (parent → child)

Модель синхронизации — древовидная. Глубина вложенности на меене 2 и не более 3:

• 1 — категория
• 2 — подкатегория / товар
• 3 — товар

Пример данных:

{"name": "Бакалея", "type": "category", "parent": 0, "id": "123"}
{"name": "Крупа", "type": "category", "parent": 123, "id": "1020"}
{"type": "product", "name": "Греча ядрица 900г Националь", "sku": "4600935000043", "parent": "1020", "id": "20020"}

Поддержка фильтра:

• GET: GET /api/v1/catalog?parent=123
• POST:

{
  "parent": 123
}

Требования:

• parent=0 или null — корневой уровень
• Сортировка должна быть стабильной
• Структура должна быть детерминированной

9. Удалённые объекты

Удалённые объекты должны возвращаться при инкрементальной синхронизации.

Допустимые поля:

• is_deleted
• deleted_at

Итоговые обязательные требования

• Поддержка получения данных через GET и POST (JSON body)
• Стабильные и уникальные id для сущностей
• Поле modified_at у каждой сущности
• Параметр инкрементальной синхронизации modified_since
• Обязательная пагинация (limit/offset или cursor)
• Изображения — только через image_url + image_modified_at/image_hash
• Иерархия структуры через parent (parent → child)
• Передача удалений через is_deleted или deleted_at