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

> Browse Natura's complete product catalog, search for items by category or keyword, and retrieve detailed product information including prices, descriptions, ingredients, and customer reviews. Supports category navigation, faceted filtering, and paginated search results.

**Category:** E-commerce | **Website:** [natura.com.br/](https://natura.com.br/) | **Docs:** [parse.bot/marketplace/26d67432-c6df-4190-b23f-737108fde5e2/natura-com-br-api](https://parse.bot/marketplace/26d67432-c6df-4190-b23f-737108fde5e2/natura-com-br-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/natura/`
**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 category filters

Get available filter refinements and sort options for a category or search query. Useful for building faceted navigation interfaces. Returns total product count, available refinements (brand, gender, fragrance family, product type, price range), and all sort options. At least one of query or category_id should be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category ID to get filters for (e.g. 'perfumaria', 'presentes'). Obtain valid IDs from list_categories. |
| `query` | string | No | Search query to get filters for |

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

### Get product details

Get detailed information for a specific product including full description, usage instructions, pricing with installments, images, fragrance family, gender target, category classification, and product benefits. Returns a single product object keyed by product_id.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product ID (e.g. 'NATBRA-95572'). Obtain from search_products results. |

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

### Get product reviews

Get user reviews for a specific product, including aggregated rating, total review count, recommendation percentage, rating distribution by star level, individual reviews with comments, and an AI-generated summary with topic sentiment analysis. Paginated by page number.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-based) |
| `page_size` | integer | No | Number of reviews per page |
| `product_id` | string | Yes | Product ID (e.g. 'NATBRA-43135'). Obtain from search_products results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/natura/get-product-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","page_size":"<integer>","product_id":"<string>"}'
```

### List categories

Retrieve the full category navigation hierarchy including main menu categories with nested subcategories, product counts per category, footer links, and top navigation elements. Returns the complete site navigation tree in a single call — no pagination.

**Estimated cost:** Metered

_No parameters required._

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

### Search products

Search for products by keyword or category ID. Returns paginated results with product details (name, price, rating, images, brand, availability), available refinements for faceted filtering, and sort options. At least one of query or category_id should be provided for meaningful results. Pagination is offset-based via the start parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category ID to filter by (e.g. 'perfumaria', 'promocoes', 'presentes'). Obtain valid IDs from list_categories. |
| `count` | integer | No | Number of results per page (max 48) |
| `query` | string | No | Search keyword (e.g. 'perfume', 'desodorante') |
| `sort` | string | No | Sort order for results. |
| `start` | integer | No | Pagination offset (0-based item index) |

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

## Next steps

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