Bicops Partner APIv1

Oversigt

Produkt-, lager- og prisdata sendes til Bicops via denne API. Ordre- og økonomidata hentes via samme API. Masseanmodninger behandles fra en kø; svaret er 202 med et batch-id (batchId).

Version: /v1. Feltnavne ændres ikke. Svarbeskeder er på engelsk; feltet code er stabilt.

• JSON, UTF-8, ISO-8601 (UTC)
• Hvert svar indeholder headeren X-Request-Id
• Ugyldige poster afvises, gyldige behandles
• En post med samme sourceId opdateres

Godkendelse

Hver anmodning indeholder headerne X-Api-Key og X-Api-Secret. Nøglen udstedes af Bicops; hemmeligheden vises kun ved oprettelsen.

Sælgeridentiteten kommer fra nøglen. Der sendes intet sælger-id i body. En nøgle har kun adgang til sin egen konto. Rettigheder styres af scopes (catalog:read, catalog:write, orders:read).

Der kan angives en IP-allowlist og en udløbsdato. Ved rotation kan to nøgler være aktive.

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

Forbindelsestest: GET /v1/me. Svaret indeholder nøglens scopes og grænser.

Nøgletyper

Der findes to nøgletyper med forskelligt omfang. En tjeneste, der kaldes med den forkerte type, returnerer 403.

Kom i gang

1. Forbindelsestest

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

2. Send produkter (højst 1.000 poster). Svar: 202 og 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. Hent batchposten: status, optællinger, rækkefejl.

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. Opdater lager og priser (højst 5.000 poster).

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 tilføjer eller opdaterer poster efter sourceId. Kun ændrede poster behandles.

Felter

PATCH /v1/catalog/stock og PATCH /v1/catalog/prices opdaterer kun lager og priser. Behandles i prioritetskøen.

Deaktivering: DELETE /v1/catalog/products/{sourceId} eller POST /v1/catalog/products/deactivate.

GET /v1/catalog/products viser posternes status hos Bicops.

Filimport

Et komplet katalog sendes som NDJSON-fil (én post pr. linje). gzip anbefales. Filen uploades direkte til lageret.

1. POST /v1/catalog/imports: få uploadUrl og batchId
2. Upload filen med HTTP PUT til uploadUrl
3. POST /v1/catalog/imports/{batchId}/complete: start behandlingen
4. GET /v1/catalog/batches/{batchId}: følg fremdriften

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

Filformat

• Hver linje er et selvstændigt JSON-objekt. Der er ingen kommaer eller firkantede parenteser mellem linjerne.
• Filen er UTF-8-kodet, og linjer slutter med \n. Tomme linjer springes over.
• Kun sourceId (dit varenummer) er påkrævet. Et felt, du udelader, beholder sin nuværende værdi.
• En ugyldig linje afvises for sig, og resten af filen behandles. Årsager findes i GET /v1/catalog/batches/{id}/errors.
• Hvis stock og warehouses sendes sammen, skal stock svare til summen af lagerbeholdningerne.
• Produkter, der mangler i filen, slettes ikke. Send et sådant produkt med status: 0 for at deaktivere det.

Eksempelfil

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

Download NDJSON-eksempelfil

dryRun=true validerer filen uden at skrive. Den første import af 1.000.000 poster tager ca. 15 minutter.

Batchposter

Hver masseanmodning opretter en batchpost. GET /v1/catalog/batches/{id} giver status, optællinger og varighed. /errors giver rækkefejl; /errors.csv samme liste som CSV.

Optællinger: received, accepted, rejected, changed. Ved identiske data er changed = 0.

Endpoints

Alle endpoints ligger under /v1. Skrive-endpoints kræver det tilhørende scope.

Ordrer

Forsendelse

Returneringer og annulleringer

Fakturaer

Økonomi

Webhooks og hændelser

Rapporter

Erhverv (afdelingsnøgle)

Fejlkoder

Fejlsvar: { code, message, details[], requestId }. code er stabil; message er en engelsk beskrivelse.

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

Postkoder (batchfejlrapport)

Grænser

• Produkter: 1.000 poster pr. anmodning. Lager og priser: 5.000 poster pr. anmodning. Body: 6 MB.
• Anmodningshastighed: 600 anmodninger pr. minut pr. nøgle. Derover 429.
• Ventende batches: 10 pr. sælger. Derover 429.
• Fil: ingen postgrænse, højst 2 GB (gzip).
• Upload-URL’en er gyldig i 15 minutter.

Anmodningslog

GET /v1/logs/requests viser anmodningerne fra de sidste 30 dage: endpoint, status, varighed, requestId, batchId.

Reference

• Swagger UI
• OpenAPI 3-skema (JSON)
• Postman-samling (alle endpoints, eksempel-bodies)
• Support: support@bicops.tr. Angiv requestId og batchId.