$kind: http-request
description: |-
  Starts a full Hiboutik → database synchronization **in the background** and answers immediately: the request never waits for the sync to end.

  **What it syncs**, in dependency order: brands → categories → suppliers → products (with their versions and stocks) → customers (with their addresses and orders). New brands, categories and products get their slug at the end of their step.

  **Hiboutik is the source of truth**: brands, categories, suppliers, products and customers missing from Hiboutik are deleted from the database (orders are never deleted). A failed Hiboutik call deletes nothing. A failing item is logged and skipped; the sync goes on and logs a summary at the end. Follow its progress in the server logs.

  **One sync at a time**, across all instances (Postgres advisory lock): a call while a sync is running answers `409`.

  **Cost**: a sync uses roughly one Hiboutik API call per customer, plus a few per entity type. Hiboutik allows 10,000 calls per month per shop; when its rate limit is reached, the sync stops.

  **Responses**
  - `202` sync started.
  - `409` a sync is already running (on this instance or another one).
  - `429` rate limit: 5 calls per minute per IP on this route. `Retry-After` gives the seconds to wait.
  - `503` this instance is shutting down: retry, another instance can take the call.
  - `500` unexpected error (e.g. database unreachable); details are in the server logs only.

  No body, no parameters.
url: "{{baseUrl}}/sync"
method: POST
headers:
  Accept: application/json
examples: ./.resources/syncHiboutik.resources/examples
order: 1000