Third-Party Integrations

Overview

Integrations connect Upvendo with external services like delivery platforms (Deliveroo, Uber Eats), POS systems (Square, Hendrickx), and other business tools.

Key Purpose: Connect with external platforms and services.

Purpose

This page lets you view and manage all third-party integrations connected to your Upvendo account, including delivery platforms, POS systems, payment providers, and accounting tools.

Key Concepts

• AbstractThirdPartyIntegrationService: The base class all integrations extend, providing standardized methods for enable, disable, update, getStatus, syncTransactions, processWebhook, and updateTransactionStatus.
• Integration States: Each integration tracks its lifecycle through states: Disconnected, Connecting, Connected, Error, and Paused, with a sync status (pending, in_progress, success, error) and last sync timestamp.
• Order Attribution: Orders received from integrations are tagged with channel (integration name), external_id (platform order ID), and source_data (original payload), enabling tracing and reconciliation.
• Webhook Processing: Delivery platforms (Deliveroo, Uber Eats) push order events via webhooks; each webhook is matched to a location by provider-specific identifiers and dispatched to a background job for processing.
• Menu Sync Pipeline: Menu updates flow through a per-platform transformation step that converts Upvendo's menu structure into the target platform's format (categories, items, modifiers, schedules, prices in cents).

Actions

Enable an Integration

Configure credentials for any supported platform (Deliveroo, Uber Eats, Square, Hendrickx, Exact Online, Moneybird) and activate it for a specific location.

Disable an Integration

Remove the integration for a location, performing provider-specific cleanup (e.g., unlinking stores, revoking tokens) before deleting the credentials.

Sync Menu to Platforms

Push Upvendo menu data to connected delivery and POS platforms. Each platform has its own transformation logic to match its API format requirements.

Monitor Integration Status

View the current state, last sync timestamp, sync status message, and connection health for each active integration from the integrations overview page.

Sync Transactions

Fetch recent transactions from a connected platform for a configurable date range (defaults to last 7 days) and create or update them in Upvendo.

Location

• Backoffice Route: /integrations
• Backend Controller: app/Http/Controllers/Api/IntegrationController.php

---

Delivery Platform Integrations

Deliveroo

Purpose: Receive orders from Deliveroo marketplace.

Fields:

Field	Description
enabled	Enable Deliveroo integration
restaurant_id	Deliveroo restaurant ID
api_key	API key for authentication
auto_accept	Automatically accept orders
menu_sync	Sync menu to Deliveroo

Order Flow:

Deliveroo order placed
        │
        ▼
Webhook received by Upvendo
        │
        ▼
Order created in system
        │
        ▼
Sent to KDS
        │
        ▼
Status updates sent back to Deliveroo

Menu Sync:

• Items synced to Deliveroo
• Prices can differ from in-house
• Availability synced in real-time

---

Uber Eats

Purpose: Receive orders from Uber Eats marketplace.

Fields:

Field	Description
enabled	Enable Uber Eats integration
store_id	Uber Eats store ID
client_id	OAuth client ID
client_secret	OAuth client secret
auto_accept	Automatically accept orders

Order Flow:

Uber Eats order placed
        │
        ▼
Order received via API
        │
        ▼
Order created in system
        │
        ▼
Sent to KDS
        │
        ▼
Status updates sent to Uber Eats

---

POS Integrations

Square

Purpose: Sync with Square POS for unified sales tracking.

Fields:

Field	Description
enabled	Enable Square integration
access_token	Square access token
location_id	Square location ID
sync_items	Sync menu items
sync_orders	Send orders to Square

Features:

• Menu item sync
• Order sync
• Payment processing
• Inventory sync

---

Hendrickx POS

Purpose: Integration with Hendrickx POS system.

Fields:

Field	Description
enabled	Enable Hendrickx integration
api_endpoint	Hendrickx API endpoint
api_key	API key
terminal_id	Terminal identifier

Features:

• Order sync to POS
• Payment terminal integration
• Receipt printing

---

Payment Integrations

Stripe

Purpose: Online payment processing.

Features:

• Card payments
• iDEAL, Bancontact, SOFORT
• Apple Pay, Google Pay
• Terminal payments (Stripe Terminal)
• Refunds

See Payments for full details.

---

Viva Wallet

Purpose: Alternative payment provider.

Features:

• Card payments
• Terminal integration
• European coverage

---

Accounting Integrations

Exact Online

Purpose: Sync transactions to Exact Online accounting.

Fields:

Field	Description
enabled	Enable integration
client_id	OAuth client ID
client_secret	OAuth client secret
division	Exact division code

Sync:

• Daily transaction export
• Invoice creation
• Payment reconciliation

---

Moneybird

Purpose: Sync with Moneybird accounting.

Fields:

Field	Description
enabled	Enable integration
api_token	API token
administration_id	Administration ID

---

Business Logic

Integration Status

Integration States:
├── Disconnected: Not configured
├── Connecting: Authentication in progress
├── Connected: Active and working
├── Error: Connection issue
└── Paused: Temporarily disabled

Order Attribution

Order received from integration
        │
        ▼
Create transaction with:
├── channel = integration name
├── external_id = platform order ID
└── source_data = original order data
        │
        ▼
Process normally through system

Menu Sync

Menu updated in Upvendo
        │
        ▼
For each connected platform:
├── Convert to platform format
├── Send updates via API
└── Handle conflicts/errors

---

Business Rules

• Enabling an integration for a location that already has one for the same provider throws an error, preventing duplicate integrations per location per provider.
• Transaction sync defaults to the last 7 days if no date range is specified, and updates the sync status to "in_progress" during the operation and "success" or "error" upon completion.
• Webhook payloads must contain provider-specific identifiers (e.g., site_id for Deliveroo, store_id for Uber Eats); missing identifiers cause the webhook to be rejected or silently logged.
• When Square POS is connected, it overrides both Stripe (online payments) and Viva Wallet (kiosk terminals), routing all payment flows through Square's API exclusively.
• Each integration's credentials and settings are scoped per location and per vendor, allowing multi-location businesses to configure different integrations per location.

FAQs

• Can I connect the same platform to multiple locations? Yes, each location has its own integration record with separate credentials and settings. The same Deliveroo, Uber Eats, or Square account can be linked to multiple locations.
• What happens if a webhook fails? Webhook processing errors are logged with the full payload and error details. The system does not retry automatically; the platform may resend the webhook based on its own retry policy.
• Do I need to sync menus manually every time I make a change? Yes, menu sync is currently a manual operation triggered from the backoffice. Automatic sync on menu change is not yet implemented for all platforms.
• Can I use multiple delivery platforms at the same time? Yes, Deliveroo, Uber Eats, and other delivery platforms operate independently and can all be active simultaneously for the same location.
• How do I know if an integration is working? Check the integration status on the overview page, which shows the current state, last sync time, and any error messages for each connected platform.

Troubleshooting

Problem: Orders not coming through

Causes:

1. Integration disabled
2. API credentials invalid
3. Webhook URL incorrect
4. Platform issue

Solutions:

1. Enable integration
2. Verify credentials
3. Check webhook configuration
4. Check platform status

---

Problem: Menu not syncing

Causes:

1. Sync disabled
2. API rate limits
3. Data format issues

Solutions:

1. Enable menu sync
2. Wait and retry
3. Check item data validity

---

Problem: Order status not updating

Causes:

1. Webhook failures
2. API authentication expired
3. Network issues

Solutions:

1. Check webhook logs
2. Refresh authentication
3. Verify network connectivity

---

Examples

Deliveroo Setup

{
  "integration": "deliveroo",
  "enabled": true,
  "config": {
    "restaurant_id": "12345",
    "api_key": "dk_live_xxxxx",
    "auto_accept": true,
    "menu_sync": true,
    "prep_time_buffer": 5
  }
}

Uber Eats Setup

{
  "integration": "uber_eats",
  "enabled": true,
  "config": {
    "store_id": "store-uuid",
    "client_id": "client-id",
    "client_secret": "client-secret",
    "auto_accept": false
  }
}

Square Setup

{
  "integration": "square",
  "enabled": true,
  "config": {
    "access_token": "sq0atp-xxxxx",
    "location_id": "LOCATION_ID",
    "sync_items": true,
    "sync_orders": true,
    "sync_inventory": false
  }
}

---

Integration Comparison

Feature	Deliveroo	Uber Eats	Square
Order Receive	✓	✓	✓
Menu Sync	✓	✓	✓
Price Override	✓	✓	✓
Inventory Sync	✓	✓	✓
Auto-Accept	✓	✓	N/A
Status Updates	✓	✓	✓
Refunds	Via Platform	Via Platform	✓

---

Best Practices

Setup

1. Test in sandbox/test mode first
2. Verify all credentials
3. Configure webhooks correctly
4. Test order flow end-to-end

Operations

1. Monitor integration status daily
2. Check for failed orders
3. Keep credentials secure
4. Update when platforms change APIs

Menu Management

1. Keep menus in sync
2. Use consistent naming
3. Handle price differences clearly
4. Disable unavailable items promptly