Документация API

API wallmarkets позволяет программно управлять поставками, возвратами,товарами и счетами супермаркетов. Все конечные точки возвращают JSON итребуют аутентификации по API-ключу.

Базовый URL

https://www.wallmarkets.store/api/v1

Формат ответа

Каждый ответ включает в себя поле статуса и полезную нагрузку в видеданных (или объект ошибки в случае неудачи).

{
  "status": "success",
  "data": { ... }
}

Аутентифицируйте каждый запрос, включив свой ключ API в качестве маркераBearer в заголовок Authorization.

Генерация ключей API

Создайте ключи в разделе Настройки аккаунта > КлючиAPI. Каждый ключ поддерживает:

• Прицелы: Ограничение доступа к каждому ресурсу (например, поставки:читать, возвраты:писать, товары:читать)
• Срок действия: Необязательная дата истечения срока действия - просроченные ключиотклоняются автоматически
• Вращение: Поверните ключ, чтобы получить новый секрет без изменения идентификатораключа

Заголовок аутентификации

Authorization: Bearer YOUR_API_KEY

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

curl -X GET \
  https://www.wallmarkets.store/api/v1/deliveries \
  -H 'Authorization: Bearer wm_live_abc123...'

Ограничения тарифов обеспечивают стабильность обслуживания. Лимитызависят от тарифного плана:

Лимиты по планам

Заголовки ограничения скорости

Каждый ответ содержит эти заголовки:

• X-RateLimit-Limit: Максимальное количество запросов в час
• X-RateLimit-Remaining: Запросы, оставшиеся в текущем окне
• X-RateLimit-Reset: Эпохальные секунды UTC, когда окно сбрасывается

Необходимый объем: deliveries:read / deliveries:write

Поставки по списку

Возвращает постраничный список доставок для аутентифицированногопользователя.

# Query Parameters
?page=1&per_page=20&status=pending&date_from=2024-01-01&supermarket_id=5

Получить доставку

{
  "id": 123,
  "supermarket_name": "E-mart",
  "subchain_name": "Sukhbaatar Branch",
  "products": [
    {"product_id": 8, "name": "Product A", "quantity": 10, "unit_price": 5000},
    {"product_id": 15, "name": "Product B", "quantity": 5, "unit_price": 12000}
  ],
  "total_value": 110000,
  "delivery_date": "2024-10-15",
  "status": "completed",
  "created_at": "2024-10-01T10:30:00Z"
}

Создать доставку

{
  "supermarket_id": 5,
  "subchain_id": 12,
  "products": [
    {"product_id": 8, "quantity": 10},
    {"product_id": 15, "quantity": 5}
  ],
  "delivery_date": "2024-10-20",
  "notes": "Urgent delivery"
}

Обновление статуса доставки

{
  "status": "completed"
}

Допустимые переходы: ожидание → в_транзите → завершено, илиожидание → отменено.

Необходимый объем: returns:read / returns:write

Возврат по списку

Возвращает постраничный список. Фильтр по доставке, супермаркету,причине или диапазону дат.

# Query Parameters
?page=1&per_page=20&reason=damaged&delivery_id=123

Создать возврат

{
  "delivery_id": 123,
  "product_id": 8,
  "quantity": 3,
  "reason": "damaged",
  "return_date": "2024-10-18",
  "description": "Products arrived damaged during transit"
}

Вернитесь

{
  "id": 42,
  "delivery_id": 123,
  "product_id": 8,
  "product_name": "Product A",
  "quantity": 3,
  "reason": "damaged",
  "description": "Products arrived damaged during transit",
  "return_date": "2024-10-18",
  "credit_amount": 15000,
  "created_at": "2024-10-18T09:15:00Z"
}

Необходимый объем: products:read / products:write

Список продуктов

Возвращает все товары для авторизованного пользователя. Фильтр покатегориям или поиск по названию.

# Query Parameters
?page=1&per_page=50&category=Dairy&search=milk

Получить продукт

{
  "id": 8,
  "sequential_id": "P-0008",
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy",
  "created_at": "2024-08-01T12:00:00Z"
}

Создать продукт

{
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy"
}

Уникальный последовательный идентификатор (sequential_id) присваиваетсяавтоматически.

Обновление продукта

{
  "price": 5500
}

Обновляются только те поля, которые вы включили. Исторические записи одоставке не затрагиваются.

Необходимый объем: supermarkets:read / supermarkets:write

Список супермаркетов

[
  {
    "id": 5,
    "name": "E-mart",
    "branches": [
      {"id": 12, "name": "Sukhbaatar Branch", "address": "..."},
      {"id": 13, "name": "Bayangol Branch", "address": "..."}
    ]
  }
]

Получить супермаркет

Возвращает подробную информацию о супермаркете, включая все филиалы,окна доставки и контактную информацию.

Создайте супермаркет

{
  "name": "E-mart",
  "contact_email": "buyer@emart.mn",
  "branches": [
    {
      "name": "Sukhbaatar Branch",
      "address": "Peace Avenue 15, UB",
      "delivery_window": "08:00-12:00"
    }
  ]
}

Подпишитесь на веб-крючки, чтобы получать HTTP-обратные вызовы вреальном времени при наступлении событий. Webhooks автоматическидеактивируются после 10 последовательных сбоев в доставке.

Типы событий

Пример полезной нагрузки Webhook

{
  "event": "delivery.completed",
  "timestamp": "2024-10-15T14:30:00Z",
  "data": {
    "delivery_id": 123,
    "supermarket_name": "E-mart",
    "subchain_name": "Sukhbaatar Branch",
    "total_value": 110000,
    "completed_at": "2024-10-15T14:30:00Z"
  }
}

Политика повторных попыток

Неудачные доставки повторяются с экспоненциальной обратной связью (1мин, 5 мин, 30 мин). После 10 неудач подряд подписка автоматическиотключается. Повторно включите ее в настройках веб-хука.

Коды состояния HTTP

Формат ответа на ошибку

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "delivery_date must be in the future",
    "field": "delivery_date"
  }
}