Update to Zid | زد

{
  "description": "Keep a Zid store's stock in line with an ERP, POS, warehouse system or spreadsheet such as Rewaa, Foodics, Odoo, Zoho Inventory, Qoyod, Daftra or Business Central. Use to compare quantities by SKU and location, apply a stock file or physical count to Zid, record received or damaged stock, or check why two systems disagree.",
  "included_files": [
    {
      "relative_path": "references/systems.md",
      "size_in_bytes": 3773
    }
  ],
  "name": "stock-sync",
  "skill_md_contents": "---\nname: stock-sync\ndescription: Keep a Zid store's stock in line with an ERP, POS, warehouse system or spreadsheet such as Rewaa, Foodics, Odoo, Zoho Inventory, Qoyod, Daftra or Business Central. Use to compare quantities by SKU and location, apply a stock file or physical count to Zid, record received or damaged stock, or check why two systems disagree.\n---\n\n# Stock sync\n\nCompares the stock in another system with Zid's, product by product and location\nby location, then brings Zid in line with whichever system the merchant names as\nthe source of truth.\n\n## Ground rules\n\n- The merchant's explicit instructions take precedence over this skill.\n- One system owns each quantity. Before writing, find out whether a connector\n  already pushes stock into Zid (step 1). Writing beside a connector makes the\n  two overwrite each other, so with one in place this skill reports and leaves\n  the fixing to the owning system.\n- Show the full change list and apply it after the merchant agrees. When a\n  manage tool answers `confirmation_required`, compare its plan with what the\n  merchant approved: if they match, repeat the call with its `plan_id`; if not,\n  show the plan and ask again.\n- Other systems' credentials (API keys, passwords, tokens) stay in that system or\n  in the merchant's automation tool. Work from the files the merchant shares.\n\n## 1. Find the source and the owner\n\n1. Ask which system holds the true stock, or read it from the file the merchant shares.\n2. `zid_account.list_installed_apps` shows whether that system's connector is\n   installed. Look the system up in [references/systems.md](references/systems.md)\n   for which way its connector moves stock and how to export its stock.\n3. Locations: `zid_inventory.list_locations`. Agree which source warehouse or\n   branch maps to which Zid location; one source location can feed only one Zid location.\n\nDone when you can name the owner of the quantities and the location mapping.\n\n## 2. Read both sides\n\n- **Source**: the merchant's export. Find the SKU, barcode, quantity and location\n  columns by matching values against Zid's SKUs, not by header names. Read\n  identifiers as text so leading zeros survive. Note whether the quantity is an\n  ending balance or a movement (+/-); the references say which for each system.\n- **Zid**: `zid_products.list_products` with `pageSize` 100 and every page (or\n  `search` for one SKU or barcode; `locationIds` limits it to the mapped\n  locations). For each product in scope, `zid_products.list_stock` with\n  `productId` gives its quantity at each location; for a product with variants,\n  `zid_catalog.list_variants` with `productId` and `locationIds` gives each\n  variant's stock. For catalogs of more than a few hundred products,\n  `zid_catalog_manage.export_products` with `locationIds` emails the merchant the\n  dashboard's product export; ask them to share it and compare the two files.\n\n## 3. Match and compare\n\nMatch each source row to a Zid product or variant by SKU, then by barcode. Map\neach variant to its own row. Convert cartons or\npacks to the unit Zid sells before comparing.\n\nPut each row in one class:\n\n- equal;\n- differs: show Zid quantity, source quantity and the difference;\n- unlimited in Zid: the product does not track stock; changing it is a separate decision;\n- bundle: its stock comes from its products, so leave it out;\n- only in source / only in Zid: list them, with likely matches when a SKU differs only by spacing or case;\n- invalid: negative, blank or non-numeric quantity.\n\nDone when every source row and every tracked Zid product at the mapped locations\nsits in one class and the counts add up.\n\n## 4. Apply\n\nPick the path that matches what the numbers mean:\n\n| The numbers are | Use | Notes |\n| --- | --- | --- |\n| A physical count | `zid_inventory_manage.create_stock_count` with `locationId`, `name` and `start` true counts every tracked product at the location. For some products only, create it with `isPartial` true, add them with `zid_inventory_manage.update_stock_count` (`stockCountId`, `productIds`), then start it with `countStatus` `in_progress`. Enter counts with `zid_inventory_manage.record_counted_quantities` (`stockCountId`, `counts` of `productId` and `count`, up to 500 per call) and apply with `zid_inventory_manage.complete_stock_count` | Applies counted minus expected, so sales made during the count are kept. Completing cannot be undone. |\n| Exact balances from the source | `zid_inventory_manage.update_location_stock` with `locationId` and `products` (`productId`, `availableQuantity`, `isInfinite`) | Replaces the quantities. Orders placed between reading the source and writing are overwritten, so run it right after the export. |\n| One product across locations | `zid_products_manage.bulk_update_stock` with `productId` and `stocks` (`location`, `availableQuantity`, `isInfinite`) | |\n| Movements: stock received, damaged, returned | `zid_products_manage.adjust_stock` with `productId`, `locationId`, `quantityChange` (signed, not 0) and `adjustmentReason` | Refuses to go below 0 and refuses unlimited stock. |\n\n## 5. Verify\n\nRead `zid_products.list_stock` with `productId` again for the changed products and report the counts\nper class before and after. `zid_inventory.list_stock_history` (last 60 days, by\n`locationId` or `productId`) shows who or what changed a quantity, which explains\nmost \"the numbers keep drifting\" questions.\n\n## Output\n\nA table of SKU, product, location, Zid quantity, source quantity, difference and\nclass, followed by counts per class, the changes applied, and the rows that need\nthe merchant (unmatched SKUs, bundles, unlimited stock, invalid quantities).\n\nTo repeat the sync on a schedule, use the `zid-ops` skill.\n"
}