Bicops Partner APIv1

Обзор

Данные о товарах, остатках и ценах передаются в Bicops через этот API. Данные о заказах и расчётах получаются через тот же API. Массовые запросы обрабатываются из очереди; ответ — 202 и идентификатор пакета (batchId).

Версия: /v1. Имена полей не меняются. Сообщения ответов на английском языке; поле code стабильно.

• JSON, UTF-8, ISO-8601 (UTC)
• Каждый ответ содержит заголовок X-Request-Id
• Некорректные записи отклоняются, корректные обрабатываются
• Запись с тем же sourceId обновляется

Аутентификация

Каждый запрос содержит заголовки X-Api-Key и X-Api-Secret. Ключ выпускается Bicops; секрет отображается только при создании.

Идентификатор продавца определяется ключом. В теле запроса он не передаётся. Ключ имеет доступ только к своей учётной записи. Права задаются областями (catalog:read, catalog:write, orders:read).

Можно задать список разрешённых IP и срок действия. При ротации два ключа могут быть активны одновременно.

X-Api-Key: 2c1d5c7e-2a1b-4c1e-9d7a-2b6f0e3c9a11
X-Api-Secret: 4Qb…(base64url, 43 chars)
Content-Type: application/json
X-Request-Id: optional-your-correlation-id

Проверка соединения: GET /v1/me. В ответе — области и лимиты ключа.

Типы ключей

Есть два типа ключей с разным охватом. Вызов сервиса не тем типом возвращает 403.

Начало работы

1. Проверка соединения

curl -s https://partner.bicops.tr/v1/me \
  -H "X-Api-Key: 2c1d5c7e-2a1b-4c1e-9d7a-2b6f0e3c9a11" \
  -H "X-Api-Secret: <your-secret>"

2. Передача товаров (до 1 000 записей). Ответ: 202 и batchId.

curl -s -X POST https://partner.bicops.tr/v1/catalog/products \
  -H "X-Api-Key: <key>" -H "X-Api-Secret: <secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "sourceId": "SACHS 317 572",
      "name": "AMORTISOR ON AUDI A3 / GOLF V",
      "brand": "SACHS",
      "producerCode": "317 572",
      "oemCodes": ["1T0413031CN", "1T0413031CK"],
      "equivalentCodes": ["FEBI 106124"],
      "price": 3869.60, "currency": "TRY", "pricesIncludeVat": false,
      "stock": 12,
      "warehouses": [{ "code": "ANK", "stock": 8 }, { "code": "IZM", "stock": 4 }],
      "minOrder": 1, "packageAmount": 1, "unit": "AD", "desi": 3.2,
      "images": ["https://cdn.example.com/317572.jpg"],
      "status": 1
    }]
  }'

HTTP/1.1 202 Accepted
X-Request-Id: 7c0e1c5a-…
{
  "batchId": 1042, "status": "queued",
  "received": 1, "accepted": 1, "rejected": 0, "warnings": 0,
  "chunks": 1, "dryRun": false, "issues": [], "requestId": "7c0e1c5a-…"
}

3. Запрос записи пакета: статус, счётчики, ошибки строк.

curl -s https://partner.bicops.tr/v1/catalog/batches/1042 -H "X-Api-Key: <key>" -H "X-Api-Secret: <secret>"
curl -s https://partner.bicops.tr/v1/catalog/batches/1042/errors.csv -H "X-Api-Key: <key>" -H "X-Api-Secret: <secret>" -o errors.csv

4. Обновление остатков и цен (до 5 000 записей).

curl -s -X PATCH https://partner.bicops.tr/v1/catalog/stock \
  -H "X-Api-Key: <key>" -H "X-Api-Secret: <secret>" -H "Content-Type: application/json" \
  -d '{"items":[{"sourceId":"SACHS 317 572","stock":9,"warehouses":[{"code":"ANK","stock":5},{"code":"IZM","stock":4}]}]}'

Каталог

POST /v1/catalog/products добавляет или обновляет записи по sourceId. Обрабатываются только изменённые записи.

Поля

PATCH /v1/catalog/stock и PATCH /v1/catalog/prices обновляют только остатки и цены. Обрабатываются в приоритетной очереди.

Деактивация: DELETE /v1/catalog/products/{sourceId} или POST /v1/catalog/products/deactivate.

GET /v1/catalog/products возвращает состояние записей на стороне Bicops.

Импорт файла

Полный каталог передаётся файлом NDJSON (одна запись в строке). Рекомендуется gzip. Файл загружается непосредственно в хранилище.

1. POST /v1/catalog/imports: получить uploadUrl и batchId
2. Загрузить файл методом HTTP PUT по адресу uploadUrl
3. POST /v1/catalog/imports/{batchId}/complete: начать обработку
4. GET /v1/catalog/batches/{batchId}: отслеживать ход

# 1
curl -s -X POST https://partner.bicops.tr/v1/catalog/imports -H "X-Api-Key: <key>" -H "X-Api-Secret: <secret>" \
  -H "Content-Type: application/json" -d '{"format":"ndjson","gzip":true}'
# → {"batchId":1043,"uploadUrl":"https://files.bicops.tr/partner-raw/…","expiresInSec":900}
# 2
curl -s -X PUT "<uploadUrl>" -H "Content-Type: application/octet-stream" --data-binary @catalog.ndjson.gz
# 3
curl -s -X POST https://partner.bicops.tr/v1/catalog/imports/1043/complete -H "X-Api-Key: <key>" -H "X-Api-Secret: <secret>"

Формат файла

• Каждая строка — самостоятельный объект JSON. Между строками нет запятых и квадратных скобок.
• Файл в кодировке UTF-8, конец строки \n. Пустые строки пропускаются.
• Обязательное поле только одно — sourceId (ваш складской код). Непереданное поле сохраняет текущее значение.
• Ошибочная строка отклоняется сама по себе, остальной файл обрабатывается. Причины доступны в GET /v1/catalog/batches/{id}/errors.
• Если переданы и stock, и warehouses, значение stock должно равняться сумме складских остатков.
• Товары, отсутствующие в файле, не удаляются. Чтобы деактивировать товар, отправьте его со status: 0.

Пример файла

{"sourceId":"SACHS 317 572","name":"AMORTISOR ON AUDI A3 / GOLF V","brand":"SACHS","producerCode":"317 572","previousCode":"317 571","oemCodes":["1T0413031CN","1T0413031CK"],"equivalentCodes":["FEBI 106124"],"barcodes":["4054228012345"],"price":3869.6,"currency":"TRY","pricesIncludeVat":false,"stock":12,"warehouses":[{"code":"ANK","stock":8},{"code":"IST","stock":4}],"minOrder":1,"packageAmount":1,"boxAmount":2,"unit":"AD","desi":3.2,"weight":1.25,"images":["https://cdn.satici.com/317572.jpg"],"categoryHint":"Amortisor","vehicleHint":"VW Golf V 2003-2008","status":1}
{"sourceId":"MANN W 712/95","name":"YAG FILTRESI","brand":"MANN","oemCodes":["W 712/95","1109AY"],"price":210.5,"currency":"TRY","stock":0,"status":1}
{"sourceId":"BOSCH 0986495255","name":"FREN BALATASI ON","brand":"BOSCH","oemCodes":["0986495255"],"price":1250,"currency":"TRY","stock":6,"warehouses":[{"code":"IZM","stock":6}],"status":1}
{"sourceId":"SACHS 317 571","status":0}

Скачать пример файла NDJSON

dryRun=true проверяет файл без записи. Первый импорт 1 000 000 записей занимает около 15 минут.

Записи пакетов

Каждый массовый запрос создаёт запись пакета. GET /v1/catalog/batches/{id} возвращает статус, счётчики и длительности. /errors возвращает ошибки строк; /errors.csv — тот же список в CSV.

Счётчики: received, accepted, rejected, changed. При повторной отправке тех же данных changed = 0.

Методы

Все методы находятся под /v1. Для методов записи требуется соответствующая область.

Заказы

Доставка

Возвраты и отмены

Счета

Финансы

Webhook и события

Отчёты

Корпоративный контур (ключ филиала)

Коды ошибок

Ответ с ошибкой: { code, message, details[], requestId }. code стабилен; message — описание на английском языке.

{
  "code": "VALIDATION_FAILED",
  "message": "Request body validation failed",
  "details": [{ "field": "items.0.price", "code": "INVALID_FIELD", "message": "price must not be less than 0" }],
  "requestId": "7c0e1c5a-…"
}

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

Коды записей (отчёт об ошибках пакета)

Лимиты

• Товары: 1 000 записей в запросе. Остатки и цены: 5 000 записей в запросе. Тело: 6 МБ.
• Частота: 600 запросов в минуту на ключ. При превышении — 429.
• Ожидающие пакеты: 10 на продавца. При превышении — 429.
• Файл: без ограничения по записям, до 2 ГБ (gzip).
• Адрес загрузки действителен 15 минут.

Журнал запросов

GET /v1/logs/requests возвращает запросы за последние 30 дней: метод, статус, длительность, requestId, batchId.

Справочник

• Swagger UI
• Схема OpenAPI 3 (JSON)
• Коллекция Postman (все методы, примеры тел)
• Поддержка: support@bicops.tr. Укажите requestId и batchId.