# ShopRenter API Resources Documentation

## Overview

This document covers the ShopRenter Developer API resources with focus on authentication and extended resources for orders, customers, and products.

**⚠️ Read-Only Integration**: This integration only uses GET methods to retrieve data. We do not create, update, or delete any data on ShopRenter stores.

## Authentication

The ShopRenter API uses OAuth 2.0 authentication. Based on the existing implementation in this project:

### OAuth 2.0 Flow
1. **Authorization Request** - Direct user to ShopRenter authorization page
2. **Authorization Grant** - User approves application access
3. **Token Exchange** - Exchange authorization code for access token
4. **Token Refresh** - Refresh expired access tokens using refresh token

### Token Management
- **Access Token**: Used for API authentication (stored in `stores.api_key`)
- **Refresh Token**: Used to obtain new access tokens (stored in `stores.api_secret`)
- **Token Expiration**: Monitored via `stores.token_expires_at`
- **Automatic Refresh**: Implemented in `_shared/shoprenter-client.ts`

### API Endpoints
- **Base URL**: `https://{shopname}.api.shoprenter.hu`
- **API Version**: Uses ShopRenter REST API
- **Authentication Header**: `Authorization: Bearer {access_token}`

## Order Extend Resource

The Order Extend Resource provides extended order management capabilities with support for shipping and payment method details.

### Purpose
Extends standard order data with additional delivery and payment information specific to Hungarian and European logistics providers.

### Key Properties

#### Shipping Method Extension (`shippingMethodExtension`)
Identifies the delivery service provider. Supported values include:

**Parcel Services:**
- `dhl_express` - DHL Express delivery
- `dpd` - DPD parcel service
- `gls_parcel_shop` - GLS parcel shop pickup
- `gls_parcel_locker` - GLS automated locker
- `gls_shipping_point` - GLS shipping point
- `mpl` - Magyar Posta (Hungarian Post)
- `foxpost` - FoxPost automated parcel machines

**Specialized Delivery:**
- `sameday` - Sameday courier service
- `wolt` - Wolt courier service
- `wseship_home_delivery` - WSEship home delivery

**Collection Points:**
- `easybox` - EasyBox locker system
- `pick_pack_point` - Pick Pack Point locations
- `receiving_point` - Generic receiving points

**ShopRenter Go Solutions:**
- `shoprenter_go_gls_home_delivery` - Integrated GLS home delivery
- `shoprenter_go_gls_parcel_point` - Integrated GLS parcel point
- `shoprenter_go_gls_parcel_locker` - Integrated GLS locker

#### Payment Method Code (`paymentMethodCode`)
Specifies the payment processor or method used. Supported values include:

**Card Payments:**
- `payu` - PayU gateway
- `otp_simplepay` - OTP SimplePay
- `otp_bank_card` - OTP Bank card payment
- `cib_bank` - CIB Bank gateway
- `barion` - Barion payment system
- `kh_bank` - K&H Bank gateway
- `stripe` - Stripe payment processor

**Alternative Methods:**
- `paypal` - PayPal
- `bank_transfer` - Direct bank transfer
- `cash_on_delivery` - Cash on delivery
- `sofort` - Sofort banking

**Installment Plans:**
- `instacpay` - InstaCPay installments
- `pastpay` - PastPay deferred payment
- `subscription` - Subscription-based payment

**Regional Solutions:**
- `paysafecard` - Paysafecard vouchers
- `paysafecash` - Paysafecash payment
- `mbh_credit` - MBH Bank credit
- `otp_szep_card` - OTP SZÉP card (Hungarian benefit card)

### API Endpoints (Read-Only)

**Note**: This integration uses read-only access to order extend data.

Available GET endpoints:
- **GET** `/orderExtends` - List all order extends
  - Supports pagination and filtering
  - Returns array of order extend objects
- **GET** `/orderExtends/{id}` - Get specific order extend by ID
  - Returns single order extend object
  - Includes full shipping and payment method details

### Integration Notes
- **Read-only access**: We only retrieve data, no modifications
- Order Extend provides detailed shipping and payment metadata
- Essential for understanding logistics providers and payment methods used

## Customer Extend Resource

The Customer Extend Resource provides additional customer data beyond the standard Customer Resource.

### Purpose
Extends basic customer information with supplementary fields for enhanced customer relationship management and analytics.

### Key Features
- Extended customer properties beyond core fields
- Additional metadata storage
- Integration with Customer Resource and Customer Group Resource

### API Endpoints (Read-Only)

**Note**: This integration uses read-only access to customer extend data.

Available GET endpoints:
- **GET** `/customerExtends` - List all customer extends
  - Supports pagination and filtering
  - Returns array of customer extend objects
- **GET** `/customerExtends/{id}` - Get specific customer extend by ID
  - Returns single customer extend object
  - Includes all extended customer properties

### Use Cases
- Reading custom customer attributes
- Accessing extended customer profiles
- Retrieving additional customer metadata
- Viewing customer preferences and custom fields

### Related Resources
- **Customer Resource** - Base customer data
- **Customer Group Resource** - Customer segmentation
- **Order Resource** - Customer purchase history

## Product Extend Resource

The Product Extend Resource provides extended product management capabilities for advanced catalog operations.

### Purpose
Extends standard product data with additional attributes, relationships, and metadata for complex product catalogs.

### Key Features

#### Product Relationships
- **Category Linking** - Associate products with multiple categories
- **Image Management** - Attach and manage product images
- **Attribute Management** - Define custom product attributes
- **Batch Operations** - Bulk product updates and imports

#### Special Features
- **Special Pricing** - Promotional pricing and discounts
- **Product of the Day** - Featured product promotions
- **External Identifiers** - Map to external system IDs
- **Document Relations** - Link products to related documents

### API Endpoints (Read-Only)

**Note**: This integration uses read-only access to product extend data.

Available GET endpoints:
- **GET** `/productExtends` - List all product extends
  - Supports pagination and filtering
  - Returns array of product extend objects
- **GET** `/productExtends/{id}` - Get specific product extend by ID
  - Returns single product extend object
  - Includes category links, images, attributes, and pricing

### Data Available via GET

When reading product extend data, you can access:

#### Category Associations
- Product-to-category mappings
- Multiple category assignments per product
- Category hierarchy information

#### Product Images
- Image URLs and metadata
- Sort order for display
- Primary and additional images

#### Special Pricing
- Promotional pricing information
- Special price start and end dates
- Discount details

#### Extended Attributes
- Custom product attributes
- Additional product metadata
- External system identifiers

#### Product Relationships
- Related products
- Product documents
- Cross-references to other resources

### Integration Context
- **Read-only access**: We retrieve extended product data without modifications
- Complements core Product Resource for complete catalog information
- Provides access to extended metadata for analytics and display purposes

## Synchronization

The ShopRenter API supports automated data synchronization:

### Manual Sync
Triggered via Edge Function: `shoprenter-sync`
- Syncs products, orders, and customers
- Stores data in cache tables
- Updates `last_synced_at` timestamp

### Scheduled Sync
Automated via `shoprenter-scheduled-sync` Edge Function:
- Runs hourly via pg_cron
- Configurable per store via `store_sync_config`
- Logs execution to `sync_logs` table

### Sync Configuration
Control sync behavior per store:
- Enable/disable sync
- Set frequency (15min, 30min, hourly, 6hours, daily)
- Choose resources to sync (products, orders, customers)

## Data Storage

### Cache Tables
Synced data is stored in dedicated cache tables:

**Products**: `shoprenter_products_cache`
- Product ID, name, pricing, inventory
- Categories, images, variants
- Last sync timestamp

**Orders**: `shoprenter_orders_cache` (if exists)
- Order details and line items
- Shipping and payment information
- Customer data

**Customers**: `shoprenter_customers_cache` (if exists)
- Customer profiles
- Contact information
- Order history references

### Token Management
Tokens stored in `shoprenter_tokens` table:
- Access token and refresh token
- Expiration tracking
- Shop domain and scopes
- Sync status

## Rate Limiting

The ShopRenter API client implements:
- Rate limiting (5 requests/second)
- Retry logic with exponential backoff
- Automatic pagination for large datasets

## Error Handling

The API client provides:
- Automatic token refresh on 401 errors
- Retry on transient failures
- Detailed error logging
- Graceful degradation

## API Reference Links

- **Main API Documentation**: `https://doc.shoprenter.hu/api/`
- **Order Extend**: `https://doc.shoprenter.hu/api/order_extend.html`
- **Customer Extend**: `https://doc.shoprenter.hu/api/customer_extend.html`
- **Product Extend**: `https://doc.shoprenter.hu/api/product_extend.html`

---

*Note: This documentation covers the key resources used in ShopCall.ai integration. For complete API specifications and additional resources, refer to the official ShopRenter Developer Documentation.*
