Bicops Partner APIv1

Aperçu

Les données de produits, de stock et de prix sont envoyées à Bicops par cette API. Les données de commandes et de finance sont récupérées par la même API. Les requêtes en masse sont traitées depuis une file ; la réponse est 202 avec un identifiant de lot (batchId).

Version : /v1. Les noms de champs ne changent pas. Les messages de réponse sont en anglais ; le champ code est stable.

• JSON, UTF-8, ISO-8601 (UTC)
• Chaque réponse contient l’en-tête X-Request-Id
• Les enregistrements invalides sont rejetés, les valides traités
• Un enregistrement envoyé avec le même sourceId est mis à jour

Authentification

Chaque requête contient les en-têtes X-Api-Key et X-Api-Secret. La clé est émise par Bicops ; le secret n’est affiché qu’à la création.

L’identité du vendeur est déduite de la clé. Aucun identifiant vendeur n’est envoyé dans le corps. Une clé n’accède qu’à son propre compte. Les droits sont définis par des scopes (catalog:read, catalog:write, orders:read).

Une liste d’IP autorisées et une date d’expiration peuvent être définies. Deux clés peuvent être actives pendant une rotation.

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

Test de connexion : GET /v1/me. La réponse liste les scopes et limites de la clé.

Types de clé

Il existe deux types de clé avec des portées différentes. Un service appelé avec le mauvais type renvoie 403.

Premiers pas

1. Test de connexion

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

2. Envoi des produits (jusqu’à 1 000 enregistrements). Réponse : 202 et 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. Consultation de l’enregistrement de lot : statut, compteurs, erreurs de ligne.

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. Mise à jour des stocks et des prix (jusqu’à 5 000 enregistrements).

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

Catalogue

POST /v1/catalog/products crée ou met à jour les enregistrements via sourceId. Seuls les enregistrements modifiés sont traités.

Champs

PATCH /v1/catalog/stock et PATCH /v1/catalog/prices ne mettent à jour que les stocks et les prix. Traités dans la file prioritaire.

Désactivation : DELETE /v1/catalog/products/{sourceId} ou POST /v1/catalog/products/deactivate.

GET /v1/catalog/products renvoie l’état des enregistrements côté Bicops.

Import par fichier

Le catalogue complet est envoyé sous forme de fichier NDJSON (un enregistrement par ligne). gzip est recommandé. Le fichier est téléversé directement dans le stockage.

1. POST /v1/catalog/imports : obtenir uploadUrl et batchId
2. Téléverser le fichier en HTTP PUT vers uploadUrl
3. POST /v1/catalog/imports/{batchId}/complete : lancement du traitement
4. GET /v1/catalog/batches/{batchId} : suivi

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

Format du fichier

• Chaque ligne est un objet JSON autonome. Il n’y a ni virgule ni crochet entre les lignes.
• Le fichier est encodé en UTF-8 et les lignes se terminent par \n. Les lignes vides sont ignorées.
• Le seul champ obligatoire est sourceId (votre code de stock). Un champ non transmis conserve sa valeur actuelle.
• Une ligne mal formée est rejetée seule et le reste du fichier est traité. Les motifs figurent dans GET /v1/catalog/batches/{id}/errors.
• Si stock et warehouses sont envoyés ensemble, stock doit être égal à la somme des quantités par dépôt.
• Les produits absents du fichier ne sont pas supprimés. Pour désactiver un produit, envoyez-le avec status: 0.

Fichier d’exemple

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

Télécharger le fichier NDJSON d’exemple

dryRun=true valide le fichier sans écriture. Le premier import de 1 000 000 d’enregistrements prend environ 15 minutes.

Enregistrements de lot

Chaque requête en masse crée un enregistrement de lot. GET /v1/catalog/batches/{id} renvoie statut, compteurs et durées. /errors renvoie les erreurs de ligne ; /errors.csv la même liste en CSV.

Compteurs : received, accepted, rejected, changed. Le renvoi de données identiques donne changed = 0.

Points d’accès

Tous les points d’accès sont sous /v1. Les écritures exigent le scope correspondant.

Commandes

Expédition

Retours et annulations

Factures

Finance

Webhooks et événements

Rapports

Entreprise (clé d’agence)

Codes d’erreur

Réponse d’erreur : { code, message, details[], requestId }. code est stable ; message est une description en anglais.

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

Codes de statut HTTP

Codes d’enregistrement (rapport d’erreurs du lot)

Limites

• Produits : 1 000 enregistrements par requête. Stocks et prix : 5 000 enregistrements par requête. Corps : 6 Mo.
• Cadence : 600 requêtes par minute et par clé. Au-delà : 429.
• Lots en attente : 10 par vendeur. Au-delà : 429.
• Fichier : sans limite d’enregistrements, 2 Go max. (gzip).
• L’URL de téléversement est valable 15 minutes.

Journal des requêtes

GET /v1/logs/requests renvoie les requêtes des 30 derniers jours : point d’accès, statut, durée, requestId, batchId.

Référence

• Swagger UI
• Schéma OpenAPI 3 (JSON)
• Collection Postman (tous les points d’accès, corps d’exemple)
• Support : support@bicops.tr. Indiquer requestId et batchId.