Com APItottus.com.pe ↗
Access Tottus Peru supermarket data: search products, browse categories, fetch product details, and retrieve current promotions via 5 structured endpoints.
What is the Com API?
The Tottus Peru API provides structured access to the tottus.com.pe supermarket catalog across 5 endpoints, covering product search, category browsing, detailed product pages, and homepage promotions. The search_products endpoint accepts keyword queries with optional brand and delivery-type filters, returning paginated product listings alongside facet objects that describe all available refinements.
curl -X GET 'https://api.parse.bot/scraper/e9df91f2-0213-48b2-9c59-a8ae5ac30e1e/search_products?page=1&brand=tottus&query=leche&delivery_type=express' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tottus-com-pe-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Tottus Peru SDK — product search, category browsing, and detail drill-down."""
from parse_apis.tottus_peru_api import Tottus, DeliveryType, ProductNotFound
client = Tottus()
# Search for products with express delivery filter
for product in client.catalogs.search(query="arroz", delivery_type=DeliveryType.EXPRESS, limit=3):
print(product.display_name, product.brand, product.prices[0].price[0])
# Browse a specific category (Arroz = CATG16815)
for product in client.categories.browse(category_id="CATG16815", limit=3):
print(product.display_name, product.brand)
# Drill into detail of first search result
product = client.catalogs.search(query="leche", limit=1).first()
if product:
try:
detail = product.details(slug="leche-uht-tottus-entera-tripack-bolsa-800-ml")
print(detail.name, detail.brand_name)
for spec in detail.attributes.specifications:
print(spec.name, spec.value)
except ProductNotFound as exc:
print(f"Product gone: {exc}")
# List all top-level categories
for category in client.categories.list(limit=5):
print(category.item_name, category.item_url)
print("exercised: catalogs.search / categories.browse / product.details / categories.list")
Full-text search over Tottus Peru product catalog. Returns paginated product listings with pricing, availability, and media URLs, plus facet filters (category, price range, brand) for progressive refinement. 48 products per page. Brand and delivery_type filters narrow server-side; finer filtering is client-side over the returned list.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| brand | string | Brand name to filter by, lowercase (e.g., 'tottus', 'xiaomi') |
| queryrequired | string | Search keyword (e.g., 'leche', 'arroz', 'smartphone') |
| delivery_type | string | Filter by delivery speed: 'express' or 'standard' |
{
"type": "object",
"fields": {
"facets": "array of facet filter objects with name, type, and available values for refinement",
"products": "array of product objects with productId, displayName, brand, prices, availability, mediaUrls, and measurements",
"pagination": "object with count (total results), perPage, totalPerPage, and currentPage"
},
"sample": {
"data": {
"facets": [
{
"name": "Categoría",
"type": "SINGLE_SELECT_AS_LINK",
"values": [
{
"count": 259,
"title": "Desayunos"
}
]
}
],
"products": [
{
"brand": "TOTTUS",
"skuId": "145417876",
"prices": [
{
"type": "internetPrice",
"price": [
"11.99"
],
"symbol": "S/ "
}
],
"mediaUrls": [
"https://media.tottus.com.pe/tottusPE/43553621_1/public"
],
"productId": "145417875",
"displayName": "Leche UHT Tottus Entera Tripack Bolsa 800 mL",
"availability": {
"expressShipping": "Envío rápido"
}
}
],
"pagination": {
"count": 437,
"perPage": 48,
"currentPage": 1,
"totalPerPage": 48
}
},
"status": "success"
}
}About the Com API
Product Search and Category Browsing
The search_products endpoint accepts a required query string and optional brand, delivery_type (express or standard), and page parameters. Each response includes a products array — where each item carries productId, displayName, brand, prices, availability, and media URLs — plus a facets array describing all filterable dimensions and a pagination object with count, perPage, totalPerPage, and currentPage fields. The browse_category endpoint mirrors this structure but navigates by category_id (e.g., CATG17605) rather than keyword, with an optional category_slug for URL alignment.
Product Details and Category Hierarchy
The get_product_details endpoint requires both a product_id and a slug obtained from search or browse results. It returns a full product record including a variants array (each with prices, media, availability, and specifications), attributes containing a specifications list and size chart, a breadCrumb array that maps the full category path with id, label, and link, plus a description string and brandName. An optional variant_id parameter narrows the response to a specific SKU. The get_categories endpoint requires no inputs and returns the complete navigation tree: top-level category objects with item_name, item_url, second_level_categories, and highlight_level_categories, suitable for building or syncing a local category map.
Promotions
The get_promotions endpoint requires no inputs and returns the current homepage state: a containers array of CMS blocks with key and component configurations representing active banners and featured deal placements, alongside a featured_products array of recommended product objects (which may be empty depending on the active campaign). This is useful for monitoring promotional cadence or tracking which products Tottus is currently featuring.
The Com API is a managed, monitored endpoint for tottus.com.pe — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tottus.com.pe changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tottus.com.pe API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a price-comparison tool by querying
search_productswith a keyword and extractingpricesfields across matching SKUs. - Sync a local product catalog by iterating
browse_categorywith knowncategory_idvalues obtained fromget_categories. - Monitor brand presence on the Tottus platform by filtering
search_productsresults by thebrandparameter. - Track promotional activity by polling
get_promotionsto detect changes in homepage banners and featured product placements. - Display full product pages in a third-party app using
get_product_detailsto retrievevariants,attributes, andbreadCrumbdata. - Identify delivery availability for specific products by filtering
search_productswithdelivery_typeset toexpressorstandard. - Build a category navigation tree for a Tottus-backed storefront using the nested hierarchy from
get_categories.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Tottus have an official public developer API?+
What does `get_product_details` return beyond basic pricing?+
variants array where each variant includes prices, media URLs, availability status, and specifications. The attributes field adds a structured specifications list and size chart. The breadCrumb array provides the full category path, and a description string carries product copy. The brandName field is also returned at the top level.How does pagination work across the search and browse endpoints?+
search_products and browse_category return a pagination object containing count (total matching items), perPage, totalPerPage, and currentPage. Pass the page integer parameter to advance through result pages. Neither endpoint currently supports adjusting page size — perPage reflects the fixed page size returned by the source.Does the API return customer reviews or ratings for products?+
Is data limited to a specific region or store location within Peru?+
delivery_type filter in search_products (express or standard) is the closest proxy for availability differentiation, but it does not map to specific store branches. You can fork the API on Parse and revise it to add location-based filtering if that data surface becomes available.