# Shufersal — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Find real-time product prices and daily promotions across all Shufersal stores in Israel, then browse detailed catalog information including categories, pricing, and discount details. Compare offers between locations and stay updated on current deals through the official Israeli Price Transparency portal.

**Category:** Food & Dining | **Website:** [shufersal.co.il/](https://shufersal.co.il/) | **Docs:** [parse.bot/marketplace/64e96103-2eb6-47de-ba4a-cc0d00aa49ce/shufersal-co-il-api](https://parse.bot/marketplace/64e96103-2eb6-47de-ba4a-cc0d00aa49ce/shufersal-co-il-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/shufersal/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get categories

Retrieve the fixed list of transparency data categories. Categories scope which file type is returned by get_files: Prices (incremental daily delta), PricesFull (complete daily snapshot), Promos (incremental), PromosFull (complete snapshot), and Stores (branch metadata).

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shufersal/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get files

Retrieve available transparency data files (GZ-compressed XML) for a given store and category. Returns file metadata including a time-limited Azure Blob download URL consumed by get_products_from_file. Files refresh daily; download URLs expire within hours.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category ID. Accepted values: '1' (Prices Incremental), '2' (PricesFull), '3' (Promos Incremental), '4' (PromosFull), '5' (Stores). |
| `store_id` | string | No | Store ID from get_stores (e.g. '413' for Shufersal Online). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shufersal/get-files \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","store_id":"<string>"}'
```

### Get products from file

Download and parse a transparency data file (GZ-compressed XML) to extract product pricing or promotion records. The file_url is obtained from get_files and is time-limited. For price files, returns items with codes, names, and prices. For promo files, returns promotions with descriptions and discount rates. Supports keyword filtering and result limiting.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_url` | string | Yes | The download_url of the GZ file obtained from get_files endpoint. |
| `limit` | integer | No | Maximum number of results to return. |
| `query` | string | No | Search keyword to filter products by name or item code (case-insensitive). Omitting returns all items up to the limit. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shufersal/get-products-from-file \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"file_url":"<string>","limit":"<integer>","query":"<string>"}'
```

### Get stores

Retrieve all Shufersal store locations and their internal IDs from the Israeli Price Transparency portal. Each store has a numeric ID used to scope file queries via get_files. The list is stable day-to-day; caching is safe.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shufersal/get-stores \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.