VipCommerce Data Extractor

This Actor extracts data from over 50 Brazilian supermarkets that use the VipCommerce e-commerce platform. It provides access to real-time product prices, inventory information, and store data from major retail chains across Brazil.

The scraper is designed for price monitoring, market research, competitive analysis, and inventory tracking applications.

Quick Start

The Actor operates in four modes that follow a natural workflow:

1. Distribution Centers - Get available store locations for a domain
2. Departments - Get departments for a specific distribution center
3. Categories - Retrieve product categories for a specific location
4. Assortment - Extract product data (prices, inventory, etc.) for a category

Each execution returns one page of data, giving you full control over pagination and data processing.

Operation Modes

Distribution Centers Mode

Returns available distribution centers for a store domain.

{
  "mode": "distribution_centers",
  "domain": "lojahirota.com.br",
  "branch_id": 1,
  "zip_code": "01310-100",
  "request_waiting": 5
}

Categories Mode

Returns product categories available at a specific distribution center.

{
  "mode": "categories", 
  "domain": "lojahirota.com.br",
  "branch_id": 1,
  "distribution_center_id": 5,
  "request_waiting": 5
}

Departments Mode

Returns departments for a specific distribution center.

{
  "mode": "departments",
  "domain": "lojahirota.com.br",
  "branch_id": 1,
  "distribution_center_id": 5,
  "request_waiting": 5
}

Assortment Mode

Returns products for a specific category (one page per execution).

{
  "mode": "assortment",
  "domain": "lojahirota.com.br",
  "branch_id": 1,
  "distribution_center_id": 5,
  "category_id": 61,
  "page": "1",
  "request_waiting": 5
}

Output Format

Distribution Centers

[
  {
    "name": "Centro São Paulo",
    "distribution_center_id": 5,
    "city": "São Paulo",
    "state": "SP",
    "branch_id": 1
  }
]

Departments

[
  {
    "id": 3,
    "name": "Bebidas",
    "slug": "/bebidas",
    "branch_id": 1,
    "distribution_center_id": 1,
    "categories": [
      {
        "id": 246,
        "name": "AGUARDENTES E CACHAÇAS",
        "slug": "/bebidas/aguardentes-e-cachacas"
      },
      {
        "id": 250,
        "name": "CERVEJAS TRADICIONAIS", 
        "slug": "/bebidas/cervejas-tradicionais"
      }
    ]
  }
]

Categories

[
  {
    "name": "Bebidas",
    "category_id": 61,
    "department_id": 5,
    "slug": "/bebidas",
    "branch_id": 1,
    "distribution_center_id": 5
  }
]

Assortment

{
  "records_per_page": 20,
  "items": 890,
  "pages": 45,
  "data": [
    {
      "name": "COCA COLA LATA 350ML",
      "ean": 7894900011517,
      "price_to": 3.99,
      "available": "S",
      "sku": "CC-350",
      "product_id": 12345,
      "brand": "Coca-Cola",
      "category_id": 61,
      "branch_id": 1,
      "distribution_center_id": 5,
      "price_from": 4.99,
      "price_offer": 0.0,
      "qty_min": 1,
      "qty_max": 10,
      "sold_amount": 150,
      "unit_label": "UN",
      "unit_fraction": 1,
      "qty_fraction": 1,
      "price_fraction": 3.99,
      "prioritized_product": "N",
      "main_volume": "350ml",
      "url": "https://lojahirota.com.br/produto/12345",
      "image": "https://cdn.lojahirota.com.br/coca-cola.jpg",
      "created_at": "2024-01-15",
      "hour": "10:30:00"
    }
  ]
}

Recommended Workflow

Follow this sequence for complete data extraction:

1. Distribution Centers → Get available distribution centers
2. Departments → Get departments for a distribution center
3. Categories → Get categories (same endpoint as departments)
4. Assortment → Extract products for specific categories

Working Categories (Tested)

• ID 246: AGUARDENTES E CACHAÇAS (19 products)
• ID 250: CERVEJAS TRADICIONAIS (43 products)

Python Implementation

Install the required packages:

$pip install apify-client pandas matplotlib

Basic Usage

from apify_client import ApifyClient

client = ApifyClient("your_apify_token")

# Get products from a specific store and category
run = client.actor("your_actor_id").call(run_input={
    "mode": "assortment",
    "domain": "lojahirota.com.br",
    "branch_id": 1,
    "distribution_center_id": 5,
    "category_id": 61,
    "page": "1"
})

# Get the results
products = client.dataset(run["defaultDatasetId"]).list_items().items[0]
print(f"Found {len(products['data'])} products")

for product in products['data'][:5]:  # Show first 5 products
    print(f"{product['name']} - R$ {product['price_to']}")

Complete Workflow

from apify_client import ApifyClient
import pandas as pd

# Initialize Apify client
client = ApifyClient("your_apify_token")

# Step 1: Get distribution centers
dc_run = client.actor("your_actor_id").call(run_input={
    "mode": "distribution_centers",
    "domain": "lojahirota.com.br",
    "branch_id": 1,
    "zip_code": "01310-100"
})

distribution_centers = client.dataset(dc_run["defaultDatasetId"]).list_items().items
print(f"Found {len(distribution_centers)} distribution centers")

# Step 2: Get departments for first DC
departments_run = client.actor("your_actor_id").call(run_input={
    "mode": "departments",
    "domain": "lojahirota.com.br", 
    "branch_id": 1,
    "distribution_center_id": distribution_centers[0]["id"]
})

departments = client.dataset(departments_run["defaultDatasetId"]).list_items().items
print(f"Found {len(departments)} departments")

# Step 3: Get categories for first DC
categories_run = client.actor("your_actor_id").call(run_input={
    "mode": "categories",
    "domain": "lojahirota.com.br",
    "branch_id": 1,
    "distribution_center_id": distribution_centers[0]["distribution_center_id"]
})

categories = client.dataset(categories_run["defaultDatasetId"]).list_items().items
print(f"Found {len(categories)} categories")

# Step 3: Get all products for first category
first_category = categories[0]
all_products = []
page = 1

while True:
    products_run = client.actor("your_actor_id").call(run_input={
        "mode": "assortment",
        "domain": "lojahirota.com.br",
        "branch_id": 1,
        "distribution_center_id": distribution_centers[0]["distribution_center_id"],
        "category_id": first_category["category_id"],
        "page": str(page)
    })
    
    result = client.dataset(products_run["defaultDatasetId"]).list_items().items[0]
    
    if not result["data"]:  # No more products
        break
        
    all_products.extend(result["data"])
    print(f"Page {page}: {len(result['data'])} products")
    
    if page >= result["pages"]:  # Last page reached
        break
        
    page += 1

# Convert to DataFrame for analysis
df = pd.DataFrame(all_products)
print(f"\nTotal products extracted: {len(df)}")
print(f"Price range: R$ {df['price_to'].min():.2f} - R$ {df['price_to'].max():.2f}")
print(f"Available products: {len(df[df['available'] == 'S'])}")

Data Analysis

# Analyze the extracted data
import matplotlib.pyplot as plt

# Price distribution
plt.figure(figsize=(10, 6))
df['price_to'].hist(bins=50)
plt.title('Product Price Distribution')
plt.xlabel('Price (R$)')
plt.ylabel('Number of Products')
plt.show()

# Top brands
top_brands = df['brand'].value_counts().head(10)
print("Top 10 Brands:")
print(top_brands)

# Export to CSV
df.to_csv('vipcommerce_products.csv', index=False)
print("Data exported to vipcommerce_products.csv")

How It Works

This Actor extracts one page of data per execution, giving you full control over pagination and data processing. The output format matches the original VipCommerce API structure, making it easy to integrate into existing applications.

Supported Stores

This Actor works with over 50 Brazilian supermarkets that use the VipCommerce platform, including:

• Atacadão São Roque (Bahia)
• Carvalho Super Shop (Piauí)
• Hirota Food Market (São Paulo)
• Casa Aurora Supermercados (Mato Grosso)

The Actor supports stores across all 26 Brazilian states plus the Federal District, covering both major chains and regional supermarkets. To check if a specific store is supported, simply try its domain - if it uses VipCommerce, it will work.

⚙️ Parameters

Parameter	Type	Required	Description
mode	string	✅	Operation mode: distribution_centers, departments, categories, assortment
domain	string	✅	Store domain (e.g., "lojahirota.com.br")
branch_id	integer	✅	Branch ID (default: 1)
zip_code	string	🔸	ZIP code for distribution centers (default: "01310-100")
distribution_center_id	integer	🔸	Required for categories and assortment modes
category_id	integer	🔸	Required for assortment mode
page	string	🔸	Page number for assortment (default: "1")
request_waiting	integer	✅	Request delay in seconds (min: 3, default: 5)

Use Cases

• Price Monitoring - Track competitor pricing across multiple stores
• Market Research - Analyze product availability and pricing trends
• Competitive Analysis - Monitor competitor product assortments
• Regional Analysis - Compare pricing between different Brazilian states
• Inventory Tracking - Monitor stock levels and product availability

Technical Details

• Platform: VipCommerce e-commerce platform
• Rate Limiting: Configurable delays (minimum 3 seconds)
• Error Handling: Returns empty structures on errors
• Data Format: Structured JSON output

Authentication

No authentication setup is required. The Actor comes pre-configured with all necessary credentials to access VipCommerce stores. Simply provide your Apify token when using the API client, and you're ready to start extracting data.

Data Privacy

This Actor follows data privacy best practices by excluding sensitive information such as email addresses, phone numbers, and detailed addresses from the output. Only publicly available business information is extracted.

Features

• 50+ Validated Stores - All stores are tested and working
• Real-time Data - Get current prices and inventory information
• Rate Limited - Respectful scraping with configurable delays
• Error Handling - Graceful handling of failed requests
• Privacy Compliant - No sensitive data collected
• Simple Integration - Works with any programming language