# Shufersal — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-shufersal-co-il-api-64e96103/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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.paywithlocus.com/api/wrapped/parse-shufersal-co-il-api-64e96103/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shufersal-co-il-api-64e96103/get_files \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shufersal-co-il-api-64e96103/get_products_from_file \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shufersal-co-il-api-64e96103/get_stores \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```