Home Explore Help
Sign In
fszontagh
/
shopcall
1
1
Fork 0
Files Issues 38 Pull Requests 0 Wiki
Tree: e7488a8585
Branches Tags
shopcall
/
SHOPRENTER_REGISTRATION.md

SHOPRENTER_REGISTRATION.md 13 KB
History Raw

ShopRenter App Registration - ShopCall.ai

Submission Date: 2025-10-31 Contact Email: [Your Contact Email] Company: ShopCall.ai

📧 Email Template for Partner Support

To: partnersupport@shoprenter.hu Subject: New App Registration Request - ShopCall.ai AI Phone Assistant

Tisztelt ShopRenter Partner Csapat!

Szeretnénk regisztrálni alkalmazásunkat a ShopRenter platformra. Az alábbiakban megtalálják a szükséges információkat.

1️⃣ Application Information

Application Name

ShopCall.ai - AI Phone Assistant

Short Description (max 70 characters)

AI-powered phone assistant for automated customer service calls

Full Description (Hungarian)

A ShopCall.ai egy mesterséges intelligencia alapú telefonos asszisztens, amely automatizálja
az ügyfélszolgálati hívásokat. Az alkalmazás integrálódik a ShopRenter webáruházzal, és
valós időben hozzáfér a termékekhez, rendelésekhez és vásárlói adatokhoz, hogy személyre
szabott ügyfélszolgálatot nyújtson.

Funkciók:
- Automatikus kimenő és bejövő hívások kezelése
- Termék információk valós idejű elérése
- Rendelés státusz lekérdezés
- Vásárlói előzmények alapján személyre szabott kommunikáció
- Magyar nyelvű AI asszisztens
- 24/7 elérhetőség

Application Details Link (Website)

https://shopcall.ai

Application Type

Redirected (user redirected to our platform, not iframe)

2️⃣ Technical Endpoints

All endpoints use HTTPS and include HMAC validation for security.

EntryPoint

https://shopcall.ai/integrations
  • This is where users land after successful OAuth installation
  • ShopRenter calls this URL with authentication parameters: shopname, code, timestamp, hmac, app_url
  • Our OAuth callback validates HMAC, exchanges tokens, and redirects to this URL with sr_install parameter
  • Displays integration success page and configuration options
  • Users can configure AI assistant settings and phone numbers

RedirectUri (OAuth Callback)

https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1/oauth-shoprenter-callback
  • OAuth callback endpoint for authorization code exchange
  • Receives: shopname, code, timestamp, hmac, app_url
  • Validates HMAC signature using SHA256
  • Exchanges authorization code for access token
  • Stores credentials securely in database

UninstallUri

https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1/webhook-shoprenter-uninstall
  • Called when app is uninstalled by merchant
  • Receives: shopname, code, timestamp, hmac
  • Validates HMAC signature
  • Cleanup actions:
    • Deactivates store connection
    • Removes stored tokens
    • Stops all automated services
    • Deletes cached product/customer data (GDPR compliance)

3️⃣ Required API Scopes

Scope List

product:read
product:write
customer:read
customer:write
order:read
order:write
category:read
inventory:read
webhook:read
webhook:write

Scope Justifications

product:read

Purpose: Sync product catalog for AI knowledge base Usage: The AI assistant needs to access product information (name, price, stock, description) to answer customer questions about products during phone calls. Example: "Is the XYZ product in stock?" → AI checks product availability in real-time. Data Accessed: Product name, SKU, price, description, stock levels, active status

product:write

Purpose: Future capability to update product information Usage: Enable future features like AI-assisted inventory management or price updates based on customer interactions. Example: Automatically mark products as "low stock" after multiple customer inquiries.

customer:read

Purpose: Access customer contact information and history Usage: Access customer data including email addresses, phone numbers, billing/shipping addresses to enable personalized AI service and direct customer communication. Example: "Hello Mr. Kovács, I see you previously ordered product ABC. Would you like to reorder?" Data Accessed: Email, phone, first name, last name, billing address (including phone), shipping address (including phone), order history, total spent

customer:write

Purpose: Update customer records with call interaction data Usage: Add call notes, tags, and interaction history to customer profiles for merchant reference and improved service. Example: After a support call, the AI adds a note: "Customer prefers SMS notifications for order updates."

order:read

Purpose: Access order details and customer contact information Usage: Answer customer inquiries about order status and access customer email and phone numbers from order data for follow-up communication. Example: "Where is my order SR-2024-001?" → AI provides current order status, tracking, and customer contact details. Data Accessed: Order number, status, total, currency, customer email, customer phone, billing/shipping addresses (including phones), line items

order:write

Purpose: Update order information after calls Usage: Add call summaries, customer requests, and delivery notes to orders for merchant reference. Example: After a call about delivery preferences, the AI adds a note: "Customer requested morning delivery."

category:read

Purpose: Organize products by category for better recommendations Usage: Enable the AI to suggest related products and navigate product categories effectively during customer conversations. Example: "I'm looking for phone accessories" → AI can browse category structure to suggest relevant products.

inventory:read

Purpose: Access real-time stock availability information Usage: Provide accurate stock information during calls and suggest alternatives for out-of-stock items. Example: "Product XYZ is currently out of stock, but we have similar product ABC available."

webhook:read

Purpose: List existing webhook registrations Usage: Check for existing webhooks before creating new ones to avoid duplicates and manage webhook lifecycle. Example: During setup, verify if webhooks are already registered for this store. Critical Note: ⚠️ Our code calls listWebhooks() function - this scope is REQUIRED!

webhook:write

Purpose: Set up real-time synchronization Usage: Register webhooks for order/create, product/update, customer/update events to keep AI knowledge base synchronized in real-time. Example: When a product goes out of stock, webhook updates AI immediately so it doesn't offer unavailable products.

4️⃣ Visual Assets

Application Logo

  • Dimensions: 250x150px (exact)
  • Format: PNG with transparency
  • Location: /shopcall.ai-main/public/images/shoprenter-app-logo.png
  • Status: ⚠️ Logo file needs to be created (design pending)

Design Requirements:

  • Professional appearance
  • Clear "ShopCall.ai" branding
  • Readable at small sizes
  • Compatible with light and dark backgrounds
  • Follows ShopRenter design guidelines

5️⃣ Test Store Request

Test Store Details

Requested Store Name:

shopcall-test-store

Expected URL:

shopcall-test-store.shoprenter.hu

Test Store Request Form:

https://www.shoprenter.hu/tesztigenyles/?devstore=1

Purpose:

  • Test OAuth flow implementation
  • Validate HMAC signature verification
  • Test API integration (products, orders, customers)
  • Verify webhook functionality
  • Test uninstall process
  • Ensure Hungarian language support

6️⃣ Technical Architecture Summary

Backend Platform

  • Technology: Supabase Edge Functions (Deno/TypeScript)
  • Deployment: Supabase Cloud (serverless)
  • Database: Supabase PostgreSQL
  • Security: HMAC SHA256 validation, Row-Level Security (RLS)

OAuth Implementation

  • Flow: Authorization Code Grant
  • Token Management: Automatic refresh with 5-minute expiry buffer
  • Security: Timing-safe HMAC comparison, timestamp validation (5-minute window)
  • Storage: Encrypted tokens in Supabase database

Data Synchronization

  • Initial Sync: Triggered on first connection (products, orders, customers)
  • Scheduled Sync: Automated hourly sync using pg_cron
  • Real-time Sync: Webhooks for immediate updates
  • Caching: Local cache in database for fast AI responses

Deployed Edge Functions (8 total)

  1. oauth-shoprenter-init - OAuth flow initialization
  2. oauth-shoprenter-callback - OAuth callback handler
  3. webhook-shoprenter-uninstall - Uninstall webhook handler
  4. shoprenter-products - Product sync endpoint
  5. shoprenter-orders - Order sync endpoint
  6. shoprenter-customers - Customer sync endpoint
  7. shoprenter-sync - Manual sync trigger
  8. shoprenter-scheduled-sync - Automated background sync

7️⃣ Security & Compliance

GDPR Compliance

Security Measures

  • ✅ HMAC validation on all requests (SHA256)
  • ✅ Timestamp validation (5-minute window to prevent replay attacks)
  • ✅ HTTPS-only communication
  • ✅ Rate limiting (5 requests/second per ShopRenter guidelines)
  • ✅ Secure token storage with encryption
  • ✅ Automatic token refresh before expiry
  • ✅ Row-level security on database

8️⃣ Support & Documentation

Developer Contact

Merchant Support

  • Support Email: support@shopcall.ai
  • Language: Hungarian and English
  • Hours: Monday-Friday, 9:00-17:00 CET

Integration Documentation

  • Setup guide in Hungarian
  • Video tutorials
  • FAQ section
  • Troubleshooting guide

9️⃣ Implementation Status

✅ Completed

  • OAuth 2.0 flow with HMAC validation
  • All 8 Edge Functions deployed and tested
  • Database schema implemented
  • Token management with automatic refresh
  • Product/Order/Customer sync
  • Webhook handlers (uninstall, product updates, order updates)
  • Frontend integration UI (ShopRenterConnect.tsx)
  • Scheduled background sync (pg_cron)
  • Per-store sync configuration
  • Comprehensive error handling and logging
  • GDPR compliance measures

🔄 Pending

  • Logo design and creation (250x150px PNG)
  • Test store approval from ShopRenter
  • Production OAuth credentials (ClientId, ClientSecret, AppId)
  • Final testing with approved test store
  • App Store listing approval

🔟 Additional Information

Rate Limiting

Our implementation respects ShopRenter's rate limiting guidelines:

  • Maximum 5 requests per second per store
  • Exponential backoff on rate limit errors
  • Request queuing to prevent API overload

Webhooks to Register

After installation, we will register webhooks for:

  • order/create - New order notifications
  • order/update - Order status changes
  • product/update - Product information changes
  • product/delete - Product removal notifications

Data Retention

  • Product cache: Updated hourly + real-time webhooks
  • Order data: Retained for 90 days
  • Customer data: Retained while store is active
  • Call logs: Retained for 12 months
  • All data deleted within 30 days after uninstall

✅ Pre-submission Checklist

  • Application name and description prepared (Hungarian)
  • All technical endpoints configured with HTTPS
  • OAuth flow fully implemented and tested
  • HMAC validation implemented
  • Database schema created
  • All Edge Functions deployed to production
  • Error handling and logging implemented
  • GDPR compliance measures implemented
  • Logo created (250x150px PNG) ⚠️ Pending
  • Privacy policy published
  • Terms of service published
  • Support email configured
  • Test store requested

📝 Notes for Partner Support Review

  1. Backend Architecture: We use Supabase Edge Functions (Deno/TypeScript) instead of traditional Node.js/Express. This provides better scalability and security.

  2. Domain Format: All API requests will use {shopname}.shoprenter.hu format (NOT .myshoprenter.hu).

  3. Token Management: Our implementation includes automatic token refresh to ensure uninterrupted service.

  4. Scheduled Sync: We use PostgreSQL pg_cron for automated hourly synchronization, supplemented by real-time webhooks.

  5. Hungarian Language: Our AI assistant is fully trained in Hungarian language and understands Hungarian e-commerce terminology.

  6. Ready for Testing: All technical implementation is complete. We are ready to begin testing as soon as we receive test store access and OAuth credentials.

Thank you for reviewing our application!

Köszönjük szépen! ShopCall.ai Team

Document Version: 1.0 Created: 2025-10-31 Status: Ready for Submission (pending logo)