Bicops Partner APIv1

Genel bakış

Ürün, stok ve fiyat verisi bu API ile Bicops’a gönderilir. Sipariş ve finans verisi aynı API üzerinden alınır. Toplu istekler kuyrukta işlenir; yanıt 202 ve bir iş kimliğidir (batchId).

Sürüm: /v1. Alan adları değişmez. Yanıt mesajları İngilizcedir; code alanı sabittir.

• JSON, UTF-8, ISO-8601 (UTC)
• Her yanıtta X-Request-Id başlığı bulunur
• Hatalı satırlar reddedilir, geçerli satırlar işlenir
• Aynı sourceId ile gönderilen kayıt güncellenir

Kimlik doğrulama

Her istekte X-Api-Key ve X-Api-Secret başlıkları gönderilir. Anahtar Bicops tarafından tanımlanır; gizli anahtar yalnızca oluşturulurken görüntülenir.

Satıcı kimliği anahtardan alınır. Gövdede satıcı kimliği gönderilmez. Anahtar yalnızca kendi hesabının verisine erişir. Yetkiler kapsam ile belirlenir (catalog:read, catalog:write, orders:read).

IP izin listesi ve son kullanma tarihi tanımlanabilir. Yenileme sırasında iki anahtar birlikte aktif olabilir.

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

Bağlantı testi: GET /v1/me. Yanıtta anahtarın kapsamları ve limitleri yer alır.

Anahtar tipleri

İki tip anahtar vardır ve kapsamları farklıdır. Yanlış tiple çağrılan servis 403 döner.

Başlangıç

1. Bağlantı testi

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

2. Ürün gönderimi (en fazla 1.000 kayıt). Yanıt: 202 ve 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. İş kaydı sorgusu: durum, sayılar, satır hataları.

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. Stok ve fiyat güncellemesi (en fazla 5.000 kayıt).

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}]}]}'

Katalog

POST /v1/catalog/products kayıtları sourceId ile ekler veya günceller. Yalnızca değişen kayıtlar işlenir.

Alanlar

PATCH /v1/catalog/stock ve PATCH /v1/catalog/prices yalnızca stok ve fiyat günceller. Öncelikli kuyrukta işlenir.

Pasife alma: DELETE /v1/catalog/products/{sourceId} veya POST /v1/catalog/products/deactivate.

GET /v1/catalog/products kayıtların Bicops tarafındaki durumunu döner.

Dosya ile aktarım

Tam katalog için NDJSON dosyası kullanılır (her satırda bir kayıt). gzip önerilir. Dosya doğrudan depolama alanına yüklenir.

1. POST /v1/catalog/imports: uploadUrl ve batchId alınır
2. Dosya HTTP PUT ile uploadUrl adresine yüklenir
3. POST /v1/catalog/imports/{batchId}/complete: işleme başlar
4. GET /v1/catalog/batches/{batchId}: ilerleme izlenir

# 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>"

Dosya biçimi

• Her satır bağımsız bir JSON nesnesidir. Satırlar arasında virgül ve köşeli parantez yoktur.
• Dosya UTF-8 kodlanır, satır sonu \n olmalıdır. Boş satırlar atlanır.
• Zorunlu tek alan sourceId (sizin stok kodunuz). Gönderilmeyen alan mevcut değerini korur.
• Bozuk satır yalnız kendisi reddedilir, dosyanın kalanı işlenir. Nedenler GET /v1/catalog/batches/{id}/errors ucunda listelenir.
• stock ve warehouses birlikte gönderilirse stock, depo stoklarının toplamına eşit olmalıdır.
• Dosyada olmayan ürün silinmez. Pasife almak için o ürünü status: 0 ile gönderin.

Örnek dosya

{"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}

Örnek NDJSON dosyasını indir

dryRun=true dosyayı yazmadan doğrular. 1.000.000 kayıt için ilk aktarım yaklaşık 15 dakikadır.

İş kayıtları

Her toplu istek bir iş kaydı oluşturur. GET /v1/catalog/batches/{id} durum, sayı ve süreleri döner. /errors satır hatalarını, /errors.csv aynı listeyi CSV olarak verir.

Sayılar: received, accepted, rejected, changed. Aynı veri tekrar gönderilirse changed = 0 olur.

API Servisleri

Tüm servisler /v1 altındadır. Yazma servisleri için ilgili kapsam gerekir.

Siparişler

Kargo

İade ve iptal

Fatura

Finans

Webhook ve olaylar

Raporlar

Kurumsal (şube anahtarı)

Hata kodları

Hata yanıtı: { code, message, details[], requestId }. code sabittir; message İngilizce açıklamadır.

{
  "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 durum kodları

Kayıt kodları (iş hata raporu)

Limitler

• Ürün: 1.000 kayıt / istek. Stok ve fiyat: 5.000 kayıt / istek. Gövde: 6 MB.
• İstek sıklığı: anahtar başına 600 istek / dakika. Aşımda 429.
• Bekleyen iş: satıcı başına 10. Aşımda 429.
• Dosya: kayıt sınırı yok, en fazla 2 GB (gzip).
• Yükleme adresi 15 dakika geçerlidir.

İstek günlüğü

GET /v1/logs/requests son 30 günün isteklerini döner: uç, durum, süre, requestId, batchId.

Referans

• Swagger UI
• OpenAPI 3 şeması (JSON)
• Postman koleksiyonu (tüm servisler, örnek gövdeler)
• Destek: support@bicops.tr. requestId ve batchId belirtiniz.