Skip to content

Kaufland Articles Endpoints

Base path: /api/v1/multi + router prefix /kaufland/articles → full base: /api/v1/multi/kaufland/articles

Summary: Endpoints to sync Kaufland units into the repricer DB, calculate Kaufland-specific min/max prices and expected profit using configured margin rules, and push minimum/listing prices back to Kaufland (and Plenty). Includes cron control for scheduled runs.

Auth: Bearer JWT required for all endpoints.

Notes: Heavy operations (sync, recalc, export) run in background tasks; they broadcast progress via WebSocket (notify_clients) and use the KauflandService which enforces Kaufland's rate limits (default 111 req/sec). Price values in Kaufland API are cents (integers) — the service converts to/from euros when persisting DB records.

Endpoints

  • POST /cron/start — Start or update Kaufland repricer cron job
  • Body/Query: schedule (cron expression, default 0 8 * * *)
  • Response: CronStartResponse with message and schedule

  • Behavior: registers a kaufland_repricer_cron job via CronJobManager that runs the canonical workflow (sync → recalc → export).

  • POST /cron/stop — Stop Kaufland cron job

  • Response: CronStopResponse

  • GET /cron/status — Get cron job status

  • Response: CronStatusResponse with status, expression, last_run_at, next_run_at, active.

  • POST /recalculate — Recalculate pricing for all articles (background)

  • Response: 200 { "message": "Recalculation started in background" }

  • Runs: recalculate_articles(db, sku=None) in background.

  • POST /recalculate/{sku} — Recalculate pricing for specific SKU (background)

  • Path param: sku (string)

  • Response: 200 { "message": "Recalculation started in background", "sku": "<SKU>" }

  • POST /send_minimum_prices/{sku} — Push calculated min/listing prices to Kaufland (background)

  • Path param: sku (use all to export all eligible items)
  • Query/body: optional storefront filter (e.g., de)
  • Behavior: For each eligible article, calls KauflandService.patch_unit_data() with minimum_price and listing_price (values converted to cents). On success the Kaufland details are updated in DB; on failure an error_message is persisted.

  • Also attempts to update Plenty (Plenty_Manager.change_price_by_sku) for the kaufland channel when Plenty credentials are active.

  • POST /sync/{sku} — Sync units from Kaufland into DB (background)

  • Path param: sku (use all to sync all units)
  • Query: storefront (default de) — selects storefront to import.
  • Behavior: Fetches all units via KauflandService.get_all_units(), enriches category data via get_categories_tree() and assign_categories_to_units(), fetches buybox info per product, and upserts KauflandDetails record for each SKU. Removes DB Kaufland details that no longer exist in Kaufland.

Core workflows (implementation notes)

  • Cron workflow (kaufland_repricer_runner → cron_job_wrapper):
  • sync_articles_from_api(storefront, db) — retrieves current units and upserts Kaufland details.
  • recalculate_articles(db, storefront) — calculates minimum_price, maximum_price, expected_profit, and assigns margin_rule_id.

  • send_min_prices_to_kaufland(db, storefront) — pushes minimum_price/listing_price to Kaufland and updates Plenty.

  • Recalculation logic (recalculate_articles):

  • Reads brutto_buy_price (gross buy price) and converts it to net using the shop VAT (vat_pct / 100).
  • Uses variable_fee_pct and fixed_fee (from Kaufland KauflandDetails) plus package_cost to compute floor prices.
  • Two helper calculations:
    • Price from margin pct: solves for P in margin equation using net buy price and fees.
    • Price from absolute profit: solves for P so that absolute profit >= configured min_min_profit.
  • minimum_price = max(price_for_min_margin, price_for_min_profit) rounded to 2 decimals.
  • maximum_price = floor(calculated_max_price) + 0.90 (ensures .90 endings).
  • expected_profit computed from current listing price (if present).

  • Persists minimum_price, maximum_price, margin_rule_id, expected_profit, and updates status to UPDATE_NEEDED when values changed.

  • Export logic (send_min_prices_to_kaufland):

  • Validates required fields: brutto_buy_price, minimum_price, maximum_price, and id_unit.
  • Calls KauflandService.patch_unit_data(id_unit, storefront, update_data) where update_data contains cents integers for minimum_price and listing_price.
  • On success, clears error_message and sets DB status to ACTIVE if previously not UPDATE_NEEDED.
  • If Plenty is configured, the flow attempts Plenty_Manager.change_price_by_sku(sku, new_price, channel='kaufland') to keep Plenty in sync.

Errors & telemetry

  • Background tasks log summary counts (created, updated, deleted, successful, failed) and emit WebSocket task_status messages with source=kaufland.
  • On partial failures (missing fields, API errors) the endpoint persists error_message on the KauflandDetails record so frontends can surface problems.

Examples

  • Recalculate all SKUs (background):
curl -X POST "http://localhost:8000/api/v1/multi/kaufland/articles/recalculate" \
  -H "Authorization: Bearer <TOKEN>"
  • Recalculate single SKU:
curl -X POST "http://localhost:8000/api/v1/multi/kaufland/articles/recalculate/B07SKU123" \
  -H "Authorization: Bearer <TOKEN>"
  • Sync storefront de (background):
curl -X POST "http://localhost:8000/api/v1/multi/kaufland/articles/sync/all?storefront=de" \
  -H "Authorization: Bearer <TOKEN>"
  • Push minimum/listing prices for all SKUs:
curl -X POST "http://localhost:8000/api/v1/multi/kaufland/articles/send_minimum_prices/all" \
  -H "Authorization: Bearer <TOKEN>"
  • Endpoint implementation: backend/service_multi-repricer/app/api/v1/endpoints/kaufland_articles.py
  • Kaufland API wrapper: backend/service_multi-repricer/app/services/kaufland/kaufland_service.py
  • Kaufland rate limiter: backend/service_multi-repricer/app/services/kaufland/rate_limiter.py

Generated: reference for Kaufland article endpoints and workflows used by service_multi-repricer.

Kaufland Articles Endpoints

Router prefix: /kaufland/articles → full base: /api/v1/multi/kaufland/articles

Summary: Cron control, sync and recalc endpoints for Kaufland article flows. TODO: expand with detailed method list, parameters and examples.

Implementation: backend/service_multi-repricer/app/api/v1/endpoints/kaufland_articles.py

TODO: Populate detailed method table and examples.