Техническая информация

Seller API

Аутентификация
Работа с заказами

Работа с доставкой

Общая информация


Текущая версия Seller API v3

API для продавцов – программный интерфейс, который предназначен для получения информации о заказах и сопутствующих данных, поступивших через платформу. Данный программный интерфейс соответствует спецификации JSON API. Спецификация описывает процесс взаимодействия клиент-серверных систем, построенных на базе формата сообщений JSON и протокола передачи гипертекста (HTTP).

Каждый запрос в систему сопровождается заголовками и набором параметров.

Каждый запрос обязательно должен содержать следующие:

Формат даты и времени: Все даты и время указываются в часовом поясе UTC+6

Общая информация
Ссылка на прод: https://marketapi.forte.kz/
Ссылка на тест: https://qa-market-api.fortebank.com

Статусы заказов "order_status":

  • pending_approve — Ожидает подтверждения наличия
  • shipment — На доставке
  • taken — Выдан
  • returned — Возвращен
  • cancelledbybank — Отменён банком
  • cancelledbyclient — Отменён покупателем
  • cancelledbymerchant — Отменён продавцом
  • cancelledbytimeout — Отменён по таймауту

Способы доставки заказа "delivery_types":

  • pickup - самовывоз
  • delivery - доставка продавца
  • dhl - DHL
  • spark - Spark Logistics
  • yandex-standart - Доставка Yandex Standart
  • yandex - Доставка Yandex Express
Способы оплаты заказов "common_pay_type":
  • LOAN - кредит/рассрочка
  • CARD - банковская карта
  • LOAN_WITH_PREPAYMENT - комбинированный, кредит/рассрочка c предоплатой (авансовый платеж)


Получение списка заказов


Адрес:

POST /v3/shopping-cart/orders/filter/

Тело запроса:

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae

Тело запроса:

{
"scope": "fortemarket", // Область заказов. Значение из примера указывает на оформленные через площадку Forte Market
"size": 15, // Количество заказов возвращаемых на одной странице
"sort": "updated_on_DESC", // Сортировка. Значение из примера означает сортировку по дате обновления в порядке убывания (от новых к старым)
"from": 0, // Смещение для пагинации. Значение из примера означает, что это первая страница
"order_status": [ // Массив статусов заказов, по которым производится фильтрация
"pending_approve" // Значение в примере означает что сервер вернет только заказы в статусе "Ожидает подтверждения"
]
}

Ответ сервера:

{
"total_hits": 1, // Общее количество заказов, найденных по заданным параметрам
"orders": [
{
"uid": "4015490658352-71774", // Уникальный идентификатор заказа
"version": 4, // Версия структуры сущности заказа
"scope": "fortemarket", // Область оформления заказа
"fio": "Иван", // Имя покупателя (ФИО, или только имя)
"mobile": "7777777777", // Телефон покупателя
"order_status": "pending_approve", // Внутренний код статуса заказа
"order_status_title": "Ожидает подтверждения", // Название статуса на русском языке
"created_on": "2025-05-18T12:30:56.371158423Z", // Дата и время создания заказа
"paid": true, // Флаг, показывающий, была ли совершена оплата по заказу
"updated_on": "2025-05-18T12:35:27.192423878Z", // Время последнего обновления заказа
"common_price": 125000, // Итоговая стоимость заказа
"delivery_types": "delivery", // Внутренний код способа доставки
"delivery_title": "Доставка продавца", // Название способа доставки
"estimated_delivery_date": "2025-05-21T15:00:00Z", // Ожидаемая дата доставки
"common_pay_type": "LOAN_WITH_PREPAYMENT", // Общий способ оплаты, в примере - рассрочка/кредит с предоплатой
"payment_types_nested": [ // Массив вложенных способов оплаты (если платёж комбинированный как в примере)
{
"order_pay_type": "LOAN", // Тип оплаты — рассрочка/кредит
"invoice_id": "69afbd81-f37f-11ef-bd7b-620b74834dd1", // ID счёта на оплату
"invoice_status": "paid", // Статус счёта
"pay_type": "FORTE_EXPRESS", // Подробный тип оплаты - кодовое название банка
"pay_types_code": "FORTE_EXPRESS_0_6", // Код способа оплаты (рассрочка на 6 мес)
"pay_title": "Рассрочка на 6 месяцев", // Название способа оплаты
"paid": true, // Статус оплаты
"sum": 100000 // Сумма оплаты по этой части
},
{
"order_pay_type": "CARD", // Тип оплаты — банковская карта
"invoice_id": "69b41691-f37f-11ef-bd7c-620b74834dd1", // ID счёта
"invoice_status": "approved", // Статус счёта
"pay_type": "CARD", // Подробный тип оплаты - банковская карта
"pay_types_code": "CARD_0_0", // Код способа оплаты
"pay_title": "Банковская карта", // Название способа оплаты
"paid": true, // Статус оплаты
"is_prepayment": true, // Платеж является предоплатой (используется в комбинации с кредитом/рассрочкой)
"sum": 25000 // Сумма оплаты по этой части
}
],
"merchant_ids": [ // ID продавцов, связанных с заказом
"9VYpqYXvl77LkHvenw"
],
"own_type": "forte_id", // Тип владельца (клиента)
"owner": "e111111111111111-b2222222222-c3333333", // ID владельца заказа (клиента)
"address": "Астана, ул Пушкина, дом 1", // Адрес доставки, указанный клиентом
"city_id": "KZ-ALA", // Код города
"orderdump": "example", // Вспомогательное поле — дамп данных заказа
"common_old_price": 150000, // Исходная цена заказа
"time_to_cancel": "2025-05-19T06:16:11.295473713Z" // Срок до которого заказ может быть отменён
}
]
}

Получение деталей заказа

Адрес:

POST/v3/shopping-cart/order/{order_id}

Заголовки

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae 

Тело запроса: пустое

{}

Ответ сервера:

{
"basket_id": "c3d9d1cc-3181-11f0-a59c-d63f927cb8e4", // Уникальный идентификатор корзины, к которой относится заказ
"uid": "5667004752278-55306", // Уникальный идентификатор заказа
"version": 4, // Версия структуры сущности заказа
"scope": "fortemarket", // Область оформления заказа
"created_on": "2025-05-15T11:43:25.203859204Z", // Дата и время создания заказа
"updated_on": "2025-05-15T11:53:57.995228082Z", // Время последнего обновления заказа
"own_type": "forte_id", // Тип владельца (клиента)
"owner": "e11111-c2222222-g33333333", // ID владельца заказа (клиента)
"common_price": 30, // Фактическая сумма заказа
"common_old_price": 30, // Исходная цена заказа
"common_quantity": 1, // Общее количество товаров в заказе
"items": [ // Массив с данными по товарам
{
"uid": "71cc3542-cc29-11ef-90e9-caa3a29f7868", // Уникальный идентификатор товара
"merchant_id": "9VYpqYXvl77LkHvenw", // Идентификатор продавца
"name": "Мяч волейбольный Mikasa VLS 300 №5 (тест)", // Название товара
"amount": 1, // Количество
"price": 30, // Цена
"articul": "тест 3215", // Артикуль
"status": "taken", // Статус товара
"sku_id": "1e85b853-ecdc-11ec-8a9d-e67e71f4afbe", // Идентификатор ску
"product_id": "1e86fba5-ecdc-11ec-8a9d-e67e71f4afbe", // Идентификатор товара
"product_slug": "myach-volejbolnyj-mikasa-vls-300-5-fortemarket-test-tovar-ne-prodaetsya-495336", // Слаг
"media": [ // Массив с данными по медиа у товара
{
"media_type": "image", // Тип медиа
"media_url": "/darbiz/catalogs/ecd/18d6eaab-ecdc-11ec-99db-067aba42c30c.jpg" // Ссылка на картинку
}
],
"created_on": "2025-01-06T12:26:24.670856504Z", // Дата и время создания медиа
"updated_on": "2025-05-12T06:51:32.991Z", // Время последнего обновления заказа
"published_on": "2025-05-15T09:15:11.610454751Z", // Дата и время публикации
"sale_channels": [ // Массив области продаж данного товара
"fortemarket"
],
"is_visible": true, // Видимость товара на маркетплейсе
"cities": [ // Массив доступных городов у продавца
"KZ-AST",
"KZ-ALA",
"KZ"
],
"available": true, // Наличие товара
"pickup_options": [ // Массив пунктов выдачи продавца
{
"id": "PP1" // ID пункта выдачи
}
],
"cities_availability": [ // Массив наличия товара в городах
{
"city_id": "KZ-ALA", // Идентификатор города
},
{
"city_id": "KZ-AST",
}
],
"city_price_map": { // Цена на товар в городах
"KZ-ALA": 30,
"KZ-AST": 30,
},
"categories_array": [ // Древо категорий товара
"9c71b505-c149-11e7-8acc-005056965856",
"7a9ffae6-708c-11e8-9748-0a580a0202b0",
"6a3ef5e3-7c58-11e9-b00c-0a580a02080b"
],
"name_ebt": "Мяч волейбольный Mikasa VLS 300 №5 (тест)", // Название товара на маркетплейсе
"merchant_info": { // Массив данных по продавцу
"uid": "111111111111111", // Уникальный идентификатор
"title": "Dar Family", // Название
"city": "Алматы", // Город
"address": "KZ-ALA Северное Кольцо 3 1", // Адрес
"email": "example11111@gmail.com", // Почтовый адрес
"mobile": "77777777777", // Телефон
"logoToken": "/darbiz/catalogs/4f0/37ac9f59-4f03-11ef-afac-ea071785969f.webp", // Логотип
"email_subscription": false, // Статус рассылки
"bin": "123654799552", // БИН ИИН
"default_category": "1839f1c7-4db0-11e7-abc4-708bcda3b266", // Категория по умолчанию
"iban": "KZ6996502F00085153K9", // IBAN ИИК
"legal_name": "ТОО Примерпримерыч"", // Юридическое название
"merchant_settings": { // Настройки продавца
"pending_approve_overdue_time": 1, // Время обработки заказа
}
},
"pickup_point": "PP16", // Пункт выдачи
"pickup_address": { // Массив с данными по пункту выдачи
"regionId": "KZ-ALA", // Код региона
"street": "проспект Абая", // Улица
"streetNum": "44/2", // Дом
"longitude": 76.92575694823124, // Координаты пункта
"latitude": 43.23897796239738 // Координаты пункта
},
"is_pickup_available": true, // Доступность самовывоза
"merchant_commission": 7 // Комиссия продавца
}
],
"receiver_contacts": { // Массив данных получателя
"name": "Иван", // Имя
"city": "Алматы", // Город
"address": "улица Пушкина", // Адрес
"house_number": "1", // Дом
"flat_number": "1", // Квартира
"mobile": "7777777777", // Телефон
"email_subscription": false, // Подписан на рассылку
"latitude": 43.23995912806439, // Координаты клиента
"longitude": 76.92646812128322 // Координаты клиента
},
"common_pay_type": "CARD", // Общий способ оплаты
"payment_types": [ // Массив способов оплаты
{
"order_pay_type": "CARD", // Способ оплаты
"invoice_id": "69b41691-f37f-11ef-bd7c-620b74834dd1", // ID счёта
"invoice_status": "approved", // Статус счёта
"pay_type": "CARD", // Подробный тип оплаты - банковская карта
"pay_types_code": "CARD_0_0", // Код способа оплаты
"pay_title": "Банковская карта", // Название способа оплаты
"paid": true, // Статус оплаты
"sum": 30 // Сумма оплаты
}
],
"paid": true, // Статус оплаты заказа
"status": "taken", // Код статуса заказа
"status_title": "Выдан", // Название статуса заказа
"delivery_types": "pickup", // Код способа доставки
"delivery_title": "Самовывоз", // Название способа доставки
"delivery_state": "delivered", // Статус доставки
"delivery_params": { // Параметры доставки
"from_city": "KZ-ALA", // Город отправки
"add_delivery_price_to_total": true, // Добавление доставки к сумме заказа
"timeout_pending_approve": "2025-05-15T11:44:25.096677395Z", // Дата и время истечения обработки заказа
"timeout_awaiting_parcel": "2025-05-15T11:47:25.096677395Z" // Дата и время истечения сборки заказа
},
"estimated_delivery_date": "2025-05-15T16:00:00Z", // Примерная дата доставки
"invoice_is_created": true, // Статус создания заявки
"paidDate": "2025-05-15T11:43:42.409410636Z", // Дата оплаты
"merchantId": "9VYpqYXvl77LkHvenw", // Идентификатор продавца
"city_id": "KZ-ALA", // Город продавца
"status_history": [ // Массив истории статусов заказа
{
"status": "new",
"status_title": "Новый заказ",
"created_on": "2025-05-15T11:43:25.203872702Z"
},
{
"status": "pending_approve",
"status_title": "Ожидает подтверждения",
"created_on": "2025-05-15T11:43:42.40941373Z",
"overdue": true
},
{
"status": "shipment",
"status_title": "На доставке",
"created_on": "2025-05-15T11:53:12.828337179Z"
},
{
"status": "taken",
"status_title": "Выдан",
"created_on": "2025-05-15T11:53:57.995102759Z",
}
],
"delivery_items": [ // Массив данных по товару для доставки
{
"id": "71cc3542-cc29-11ef-90e9-caa3a29f7868", // Идентификатор товара
"name": "Мяч волейбольный Mikasa VLS 300 №5 (тест)", // Название товара
"price": 30, // Цена товара
"merchant_id": "9VYpqYXvl77LkHvenw", // Идентификатор продавца
"weight": 1, // Вес
"height": 20, // Высота
"length": 20, // Длинна
"width": 20, // Ширина
"quantity": 1, // Количество
"options": null, // Вариации
"cities_options": [ // Выбор городов
{
"city_id": "KZ-ALA",
},
{
"city_id": "KZ-AST",
}
],
"stores": [ // Массив с данными по торговым точкам продавца
{
"id": "11", // Идентификатор торговой точки
"merchantId": "11", // Идентификатор продавца
"schedule": [ // Массив с расписанием работы торговой точки
{
"day": "MONDAY",
"isOpen": true,
"openTime": 540,
"closeTime": 1439
},
{
"day": "TUESDAY",
"isOpen": true,
"openTime": 540,
"closeTime": 1380
},
{
"day": "WEDNESDAY",
"isOpen": true,
"openTime": 540,
"closeTime": 1380
},
{
"day": "THURSDAY",
"isOpen": true,
"openTime": 540,
"closeTime": 1080
},
{
"day": "FRIDAY",
"isOpen": true,
"openTime": 540,
"closeTime": 1080
},
{
"day": "SATURDAY",
"isOpen": false,
"openTime": 0,
"closeTime": 0
},
{
"day": "SUNDAY",
"isOpen": false,
"openTime": 0,
"closeTime": 0
}
],
"address": { // Адрес торговой точки
"regionId": "KZ-ALA", // Код региона торговой точки
"street": "проспект Абая", // Улица торговой точки
"streetNum": "44/2", // Дом торговой точки
"aptNum": "" // Кв или офис торговой точки
},
"conditionalId": "PP16", // Внутренний идентификатор торговой точки
"cityId": "KZ-ALA", // Код города торговой точки
"isTradePoint": true, // Статус торговой точки
"isStock": true // Статус склада
},
]
},
"parcel_id": "5667004752278-55306", // Идентификатор заказа
"order_status_stages": [ // Статусы заказа
{
"status": "new",
"title": "Новый заказ",
"created_on": "2025-05-15T11:43:25.203872702Z",
"stage_status": "passed"
},
{
"status": "pending_approve",
"title": "Подтверждение наличия товара",
"created_on": "2025-05-15T11:43:42.40941373Z",
"stage_status": "passed"
},
{
"status": "taken",
"title": "Заказ выдан",
"created_on": "2025-05-15T11:53:57.995102759Z",
"stage_status": "passed"
}
]

Расшифровка:

"basket_id" - идентификатор корзины
"uid" - номер заказа
"version" - версия заказа
"scope" - источник создания
"created_on" - время создания
"updated_on" - время последнего изменения
"own_type" - сервис авторизации клиента
"owner" - идентификатор авторизации клиента
"common_price" - сумма заказа после применения промокодов
"common_old_price" - сумма заказа
"common_quantity" - количество товаров в заказе

Подтверждение наличия товара

Товары которые требуется подтвердить, следует перевести в статус shipment.

Адрес:

POST /v3/shopping-cart/order/{{order_id}}/set-status

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae

Тело запроса:

{
"set_status": "shipment", // Новый статус заказа
"comment": "merchant" // Комментарии
}

Ответ сервера: пустой

{}

Отклонение заказа

Товары которые требуется отклонить, следует перевести в статус cancelledbymerchant.

Адрес:

POST/v3/shopping-cart/order/{{order_id}}/set-status

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae

Тело запроса:

{
"set_status": "cancelled", // Новый статус заказа
"comment": "merchant" // Комментарии
}

Ответ сервера: пустой

{}

Работа с доставкой

Курьерские службы, которые работают с ForteMarket

Готов к выдаче (Самовывоз)

После того, как продавец собрал заказ к выдаче, следует перевести заказ в статус "готов к выдаче".
Метод:

POST/v2/delivery/parcel/{{order_id}}/set-status

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae

Тело запроса:

{
"status": "pending_pickup" // Новый статус заказа
}

Ответ сервера

{
"message": "success" // Сообщение ответа
}

Вызов курьера (Доставка курьерской службой)

После того, как продавец собрал заказ к отправке, следует вызвать курьера:

Метод:

POST/v2/delivery/parcel/{{order_id}}/set-status

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae

Тело запроса

{
"status": "courier_delivery" // Новый статус заказа
}

Ответ сервера

{
"message": "success" // Сообщение ответа
}

На доставке (Доставка продавца)

После того, как продавец собрал заказ к выдаче, следует передать заказ курьеру и с сменить статус заказа на "На доставке"

Метод:

POST/v2/delivery/parcel/{{order_id}}/set-status

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae

Тело запроса

{
"status": "on_delivery" // Новый статус заказа
}

Ответ сервера

{
"message": "success" // Сообщение ответа
}

Выдача товара

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

Отправка SMS

Адрес:

POST/v2/delivery/parcel/sms/send

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae


Тело запроса:

{
"parcel_id": "{{order_id}}" // Идентификатор заказа
}

Ответ сервера:

{
"message": "SMS sent" // Сообщение ответа
}

Метод проверки SMS:


Адрес

POST/v2/delivery/parcel/sms/check

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae


Тело запроса:

{
"parcel_id": "{{order_id}}", // Идентификатор заказа
"sms_code": "111111" // Код из SMS
}

Ответ сервера:

Ответ от сервера:
{
"message": "success" // Сообщение ответа
}

Отклонение заказа

Товары которые требуется отклонить, следует перевести в статус cancelledbymerchant.

Адрес

POST/v3/shopping-cart/order/{{order_id}}/set-status

Тело запроса:

{
"set_status": "returned",
"comment": "merchant"
}

Ответ сервера:

{}

Возврат заказа

В случае, если клиент возвращает заказ, следует обновить статус заказа.

Метод:

POST/v3/shopping-cart/order/{{order_id}}/set-status

Заголовки:

Host: marketapi.forte.kz
Content-Type: application/json
API-KEY: 1aaba5a0-153f-4165-ab42-670ac0b893ae


Тело запроса:

{
"set_status": "returned", // Новый статус заказа
"comment": "merchant" // Комментарии
}

Ответ сервера:

{}