# Fahorro — 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.

> Search and browse Farmacias del Ahorro's pharmacy product catalog to find medications, health products, and promotions with detailed information including prices, availability, and product specifications. Filter products by category, brand, and apply advanced search to discover deals and exclusive Marca Propia items.

**Category:** Healthcare | **Website:** [fahorro.com/](https://fahorro.com/) | **Docs:** [parse.bot/marketplace/88742d17-5ee3-4c95-930f-7035510371b4/fahorro-com-api](https://parse.bot/marketplace/88742d17-5ee3-4c95-930f-7035510371b4/fahorro-com-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/fahorro/`
**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

### Filter products

Search or browse products with applied filters including brand, price range, and promotions. If query is provided, performs keyword search with filters; otherwise browses by category_id (defaults to '7404' Farmacia). Filters are ANDed together.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Brand name filter, must match exact brand name from facetEcommBrand values (e.g. 'ASPIRINA'). |
| `category_id` | string | No | Numeric category ID. Used when query is not provided. Defaults to '7404' (Farmacia) if both query and category_id are omitted. |
| `limit` | integer | No | Max results per page. |
| `page` | integer | No | Page number for pagination. |
| `price_max` | string | No | Maximum price filter (numeric string, e.g. '500'). |
| `price_min` | string | No | Minimum price filter (numeric string, e.g. '100'). |
| `promotions_only` | string | No | Set to 'true' to show only products with active promotions. |
| `query` | string | No | Search keyword filter. When provided, uses keyword search instead of category browse. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fahorro/filter-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"brand":"<string>","category_id":"<string>","limit":"<integer>","page":"<integer>","price_max":"<string>","price_min":"<string>","promotions_only":"<string>","query":"<string>"}'
```

### Get categories

Extract all category names and their numeric IDs from the site navigation HTML. Returns the full category tree including pharmacy, beauty, sports, and seasonal categories. No parameters required.

**Estimated cost:** Metered

_No parameters required._

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

### Get category filters

Retrieve available filter facets and price statistics for a given category. Returns facet names, types, and value counts plus min/max price stats. Useful for discovering brand names, price ranges, and boolean filters before calling filter_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Numeric category ID (e.g. '7404' for Farmacia). |

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

### Get category products

Browse products listed under a specific category by numeric ID. Returns paginated results with the same product shape as search. Use get_categories to discover valid IDs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Numeric category ID (e.g. '7404' for Farmacia). Obtain IDs from get_categories endpoint. |
| `limit` | integer | No | Max results per page. |
| `page` | integer | No | Page number for pagination. |

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

### Get marca propia products

Retrieve products under the Marca Farmacias del Ahorro private label (own brand). Returns products where ownBrand is true. Equivalent to filter_products with the ownBrand filter applied.

**Estimated cost:** Metered

_No parameters required._

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

### Get product details

Retrieve full product details by parsing the HTML product page. Accepts either a full URL or a url_key slug (from search results). Returns name, price, SKU, brand, description, specification attributes, and images. At least one of url or url_key must be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | No | Full product URL (e.g. 'https://www.fahorro.com/aspirina-analgesico-40-tabletas.html'). |
| `url_key` | string | No | Product URL slug from ecommUrlKey field (e.g. 'aspirina-analgesico-40-tabletas'). |

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

### Get promotions

Retrieve products that currently have active promotions in the Farmacia category. Returns the same product shape as search/browse endpoints. Equivalent to filter_products with promotions_only='true'.

**Estimated cost:** Metered

_No parameters required._

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

### Get suggestions

Retrieve top trending search terms from the site. Returns globally popular search terms regardless of the query parameter value. Useful for discovering what products are currently trending.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Partial search term (used as API parameter but results reflect global trends, not query-specific suggestions). |

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

### Search products

Full-text keyword search across the product catalog. Returns paginated results from the Empathy.co search API. Each result includes SKU, title, current/previous price, brand, image URL, and URL key for detail lookup. Pagination via page number; facets and stats are included alongside results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results per page. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword (e.g. 'aspirina', 'vitamina c'). |

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

## 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.