docs: create ShopRenter Payment API and API Resources documentation #58

docs/shoprenter_api_resources.md

@@ -0,0 +1,283 @@
+# 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.
+
+## 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
+
+Standard REST operations for order extend data:
+- **GET** `/orderExtends` - List order extends
+- **GET** `/orderExtends/{id}` - Get specific order extend
+- **POST** `/orderExtends` - Create order extend
+- **PUT** `/orderExtends/{id}` - Update order extend
+- **DELETE** `/orderExtends/{id}` - Delete order extend
+
+### Integration Notes
+- Order Extend sits between Order Credit Card and Order History in the API workflow
+- Used to capture detailed shipping and payment metadata
+- Essential for logistics integration and payment reconciliation
+
+## 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
+
+Standard REST operations for customer extend data:
+- **GET** `/customerExtends` - List customer extends
+- **GET** `/customerExtends/{id}` - Get specific customer extend
+- **POST** `/customerExtends` - Create customer extend
+- **PUT** `/customerExtends/{id}` - Update customer extend
+- **DELETE** `/customerExtends/{id}` - Delete customer extend
+
+### Use Cases
+- Storing custom customer attributes
+- Managing extended customer profiles
+- Supporting custom CRM workflows
+- Tracking additional customer preferences
+
+### 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
+
+Standard REST operations for product extend data:
+- **GET** `/productExtends` - List product extends
+- **GET** `/productExtends/{id}` - Get specific product extend
+- **POST** `/productExtends` - Create product extend
+- **PUT** `/productExtends` - Update product extend
+- **DELETE** `/productExtends/{id}` - Delete product extend
+
+### Common Operations
+
+#### Linking Products with Categories
+```
+POST /productExtends
+{
+  "productId": "123",
+  "categoryIds": ["456", "789"]
+}
+```
+
+#### Attaching Images
+```
+POST /productExtends/{id}/images
+{
+  "imageUrl": "https://...",
+  "sortOrder": 1
+}
+```
+
+#### Managing Special Pricing
+```
+PUT /productExtends/{id}
+{
+  "specialPrice": 99.99,
+  "specialPriceStart": "2024-01-01",
+  "specialPriceEnd": "2024-01-31"
+}
+```
+
+#### Batch Upload
+Use batch operations for importing large product catalogs with extended attributes.
+
+#### Category Assignment with External IDs
+Map products to categories using external system identifiers for seamless integration.
+
+### Integration Context
+- Sits between Product Document Relation and Product Image resources
+- Works with core Product Resource for complete catalog management
+- Supports complex e-commerce scenarios requiring extended metadata
+
+## 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.*

docs/shoprenter_payment.md

@@ -0,0 +1,108 @@
+# ShopRenter Payment API Documentation
+
+## Overview
+
+The ShopRenter Payment API is a comprehensive toolkit that enables developers to integrate card payment processing into their applications. The API provides capabilities for both one-time and recurring payments, with built-in support for automatic invoicing and financial tracking.
+
+## Key Features
+
+### Payment Capabilities
+- **One-time card payments** - Process single transactions
+- **Recurring fee payments** - Set up subscription-based billing
+- **Automatic invoicing** - Generate invoices without manual intervention
+- **Financial statistics** - Track income and payment analytics
+- **Payment plan creation** - Configure recurring charge schedules
+
+## Payment Types
+
+### One-Time Payments
+Single transaction processing for immediate charges against customer payment methods.
+
+### Recurring Payments
+Subscription-based billing model that automatically charges customers according to predefined payment plans:
+- Configurable billing cycles
+- Automatic retry on failed payments
+- Customer notification system
+- Plan modification support
+
+## Integration Features
+
+### Invoicing
+- Automatic invoice generation upon successful payment
+- VAT calculation and compliance
+- Billing data management
+- Financial record keeping
+
+### Webhooks & Notifications
+The API supports webhook notifications for:
+- Payment success/failure events
+- Subscription lifecycle events
+- Invoice generation
+- Payment method updates
+
+### Transaction Management
+- Bank card information updates
+- Payment status tracking
+- Transaction history access
+- Refund processing capabilities
+
+## Application Lifecycle
+
+The Payment API documentation covers the complete application lifecycle including:
+1. Setup and configuration
+2. Integration implementation
+3. Testing and validation
+4. Production deployment
+5. Monitoring and maintenance
+6. Application deletion procedures
+
+## Financial Operations
+
+### Billing Data
+- Customer billing information management
+- Multiple currency support
+- VAT rate configuration
+- Pricing structure setup
+
+### Payment Plans
+Create and manage recurring payment schedules with:
+- Flexible billing frequencies
+- Trial period support
+- Grace period configuration
+- Automatic renewal options
+
+## Security & Compliance
+
+The API is designed to handle sensitive financial data with appropriate security measures and compliance standards for processing card payments within the ShopRenter platform.
+
+## Documentation Structure
+
+The complete Payment API documentation is organized into sequential sections:
+1. Introduction and overview
+2. Setup requirements and prerequisites
+3. API basics and fundamentals
+4. Payment implementation guides
+5. Subscription management
+6. Webhook configuration
+7. Testing procedures
+8. Production best practices
+
+## Getting Started
+
+To begin using the ShopRenter Payment API:
+1. Access the developer portal at `https://doc.shoprenter.hu/paymentapi/`
+2. Review setup and configuration requirements
+3. Obtain necessary API credentials
+4. Follow integration guides for your use case
+5. Test in sandbox environment
+6. Deploy to production
+
+## Additional Resources
+
+- Full API documentation: `https://doc.shoprenter.hu/paymentapi/docs/a_introduce.html`
+- Developer GitHub repository (referenced in documentation)
+- Support and technical assistance through ShopRenter developer portal
+
+---
+
+*Note: This documentation provides a high-level overview. For detailed API specifications, authentication methods, endpoint definitions, and code examples, refer to the complete Payment API documentation on the ShopRenter developer portal.*