Bicops Partner APIv1

Overzicht

Product-, voorraad- en prijsgegevens worden via deze API naar Bicops gestuurd. Order- en financiële gegevens worden via dezelfde API opgehaald. Bulkverzoeken worden uit een wachtrij verwerkt; het antwoord is 202 met een batch-id (batchId).

Versie: /v1. Veldnamen wijzigen niet. Antwoordberichten zijn in het Engels; het veld code is stabiel.

• JSON, UTF-8, ISO-8601 (UTC)
• Elk antwoord bevat de header X-Request-Id
• Ongeldige records worden afgewezen, geldige verwerkt
• Een record met dezelfde sourceId wordt bijgewerkt

Authenticatie

Elk verzoek bevat de headers X-Api-Key en X-Api-Secret. De sleutel wordt door Bicops uitgegeven; het geheim wordt alleen bij aanmaak getoond.

De verkoperidentiteit komt uit de sleutel. In de body wordt geen verkoper-id verzonden. Een sleutel heeft alleen toegang tot het eigen account. Rechten worden bepaald door scopes (catalog:read, catalog:write, orders:read).

Een IP-allowlist en vervaldatum kunnen worden ingesteld. Bij rotatie kunnen twee sleutels actief zijn.

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

Verbindingstest: GET /v1/me. Het antwoord bevat de scopes en limieten van de sleutel.

Sleuteltypen

Er zijn twee sleuteltypen met een verschillend bereik. Een dienst die met het verkeerde type wordt aangeroepen geeft 403.

Aan de slag

1. Verbindingstest

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

2. Producten aanleveren (maximaal 1.000 records). Antwoord: 202 en 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. Batchrecord opvragen: status, tellingen, rijfouten.

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. Voorraad en prijzen bijwerken (maximaal 5.000 records).

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

Catalogus

POST /v1/catalog/products voegt records toe of werkt ze bij op sourceId. Alleen gewijzigde records worden verwerkt.

Velden

PATCH /v1/catalog/stock en PATCH /v1/catalog/prices werken alleen voorraad en prijzen bij. Verwerkt in de prioriteitswachtrij.

Deactiveren: DELETE /v1/catalog/products/{sourceId} of POST /v1/catalog/products/deactivate.

GET /v1/catalog/products geeft de status van de records aan Bicops-zijde.

Bestandsimport

Een volledige catalogus wordt als NDJSON-bestand verzonden (één record per regel). gzip wordt aanbevolen. Het bestand wordt rechtstreeks naar de opslag geüpload.

1. POST /v1/catalog/imports: uploadUrl en batchId verkrijgen
2. Bestand uploaden met HTTP PUT naar uploadUrl
3. POST /v1/catalog/imports/{batchId}/complete: verwerking starten
4. GET /v1/catalog/batches/{batchId}: voortgang volgen

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

Bestandsformaat

• Elke regel is een zelfstandig JSON-object. Tussen de regels staan geen komma’s of vierkante haken.
• Het bestand is UTF-8-gecodeerd en regels eindigen met \n. Lege regels worden overgeslagen.
• Alleen sourceId (uw voorraadcode) is verplicht. Een veld dat u weglaat behoudt de huidige waarde.
• Een ongeldige regel wordt op zichzelf geweigerd en de rest van het bestand wordt verwerkt. Redenen staan in GET /v1/catalog/batches/{id}/errors.
• Als stock en warehouses samen worden verzonden, moet stock gelijk zijn aan de som van de magazijnvoorraden.
• Producten die in het bestand ontbreken worden niet verwijderd. Stuur zo’n product met status: 0 om het te deactiveren.

Voorbeeldbestand

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

Voorbeeld-NDJSON-bestand downloaden

dryRun=true valideert het bestand zonder te schrijven. De eerste import van 1.000.000 records duurt ongeveer 15 minuten.

Batchrecords

Elk bulkverzoek maakt een batchrecord aan. GET /v1/catalog/batches/{id} geeft status, tellingen en duur. /errors geeft rijfouten; /errors.csv dezelfde lijst als CSV.

Tellingen: received, accepted, rejected, changed. Bij identieke gegevens is changed = 0.

Endpoints

Alle endpoints staan onder /v1. Schrijf-endpoints vereisen de bijbehorende scope.

Orders

Verzending

Retouren en annuleringen

Facturen

Financiën

Webhooks en gebeurtenissen

Rapporten

Zakelijk (filiaalsleutel)

Foutcodes

Foutantwoord: { code, message, details[], requestId }. code is stabiel; message is een Engelse omschrijving.

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

Recordcodes (batchfoutrapport)

Limieten

• Producten: 1.000 records per verzoek. Voorraad en prijzen: 5.000 records per verzoek. Body: 6 MB.
• Verzoeksnelheid: 600 verzoeken per minuut per sleutel. Daarboven 429.
• Wachtende batches: 10 per verkoper. Daarboven 429.
• Bestand: geen recordlimiet, maximaal 2 GB (gzip).
• De upload-URL is 15 minuten geldig.

Verzoeklogboek

GET /v1/logs/requests geeft de verzoeken van de laatste 30 dagen: endpoint, status, duur, requestId, batchId.

Referentie

• Swagger UI
• OpenAPI 3-schema (JSON)
• Postman-collectie (alle endpoints, voorbeeldbody’s)
• Support: support@bicops.tr. Vermeld requestId en batchId.