README

Unified marketplace OAuth and credential management for TikTok Shop, Shopee, and Lazada in Laravel applications. The package stores application credentials (API keys, secrets, redirect URLs) separately from shop records (per-seller OAuth tokens), merges them for API calls, and ships with web UI routes, JSON API routes, and Blade views.

Requirements

PHP ^8.2
Laravel ^11, ^12, or ^13 (Illuminate components)
Guzzle ^7

Installation

composer require ndkode/marketplace-integrator

Laravel will auto-discover Ndkode\MarketplaceIntegrator\Providers\MarketplaceServiceProvider.

Publish assets (optional)

php artisan vendor:publish --tag=marketplace-integrator-config
php artisan vendor:publish --tag=marketplace-integrator-migrations
php artisan vendor:publish --tag=marketplace-integrator-views

Migrations are also loaded automatically from the package; publishing copies them into your app if you prefer to own the migration files.

php artisan migrate

Configuration

Environment variables (see config/marketplace-integrator.php after publishing):

Variable	Purpose
`MARKETPLACE_TABLE_NAME`	Credentials table (default: `marketplace_credentials`)
`MARKETPLACE_SHOPS_TABLE_NAME`	Shops table (default: `marketplace_shops`)
`MARKETPLACE_ROUTE_PREFIX`	Web UI prefix (default: `marketplace-integrator`)
`MARKETPLACE_API_PREFIX`	API prefix (default: `api/marketplace-integrator`)
`TIKTOK_SHOP_BASE_URL`, `TIKTOK_SHOP_TOKEN_BASE_URL`, `TIKTOK_SHOP_AUTH_URL`	TikTok Shop endpoints
`SHOPEE_BASE_URL`	Shopee Open Platform base URL (sandbox vs production)

Lazada uses regional hosts derived from the region field on the credential (no separate auth_url in config).

Credentials vs shops

Credential — One row per marketplace app integration: app key/secret, OAuth redirect URL, and other app-level fields defined by each driver.
Shop — Child rows under a credential: seller/shop identifiers and access/refresh tokens after OAuth.

For API calls, use MarketplaceShop::toCredentialData(), which merges the parent credential’s app fields with the shop’s tokens into a single CredentialData DTO.

OAuth redirect URL

Configure the redirect URL in your marketplace developer console to match the package callback route, for example:

https://your-domain.test/{web-prefix}/oauth/{marketplace}/callback

where {marketplace} is tiktok_shop, shopee, or lazada. The same URL must be stored on the credential (per driver field definitions). If Shopee returns a callback without state, the package can resolve the pending credential from session (set when starting the redirect).

Routes

Web (middleware from config('marketplace-integrator.routes.middleware'), default web):

GET/POST …/credentials — CRUD for credentials (resource)
Nested: credentials/{credential}/shops/{shop} — show, test, toggle active, destroy
GET …/oauth/{credential}/redirect — start OAuth (marketplace-integrator.oauth.redirect)
GET …/oauth/{marketplace}/callback — OAuth callback (marketplace-integrator.oauth.callback)

API (default api middleware, prefix api/marketplace-integrator):

GET marketplaces, GET marketplaces/{marketplace}/fields
apiResource for credentials
Nested credentials/{credential}/shops — index, show, test, toggle, destroy

Route names are prefixed with marketplace-integrator. (web) and api.marketplace-integrator. (API).

Using drivers in code

Resolve the manager and set merged credentials from a shop model:

use Ndkode\MarketplaceIntegrator\MarketplaceManager;
use Ndkode\MarketplaceIntegrator\Models\MarketplaceShop;

/** @var MarketplaceManager $marketplace */
$marketplace = app(MarketplaceManager::class);

$shop = MarketplaceShop::query()->with('credential')->findOrFail($id);

$driver = $marketplace->driver($shop->credential->marketplace);
$driver->setCredentials($shop->toCredentialData());

// Call driver methods as implemented per marketplace (authorize, refresh, test connection, etc.)

You may bind the Marketplace facade manually in config/app.php (or bootstrap) if you prefer Marketplace::driver(...) — the package registers the marketplace container alias for MarketplaceManager.

Events

Event	When
`Ndkode\MarketplaceIntegrator\Events\MarketplaceConnected`	Shop connected / tokens stored
`Ndkode\MarketplaceIntegrator\Events\MarketplaceDisconnected`	Shop disconnected
`Ndkode\MarketplaceIntegrator\Events\TokenRefreshed`	Tokens refreshed
`Ndkode\MarketplaceIntegrator\Events\CredentialsUpdated`	Credential payload updated

Payloads use MarketplaceShop where applicable.

Custom drivers

Implement Ndkode\MarketplaceIntegrator\Contracts\MarketplaceDriverContract, extend AbstractMarketplaceDriver if helpful, and register the class in config('marketplace-integrator.drivers').

Development

composer install
./vendor/bin/pest

License

MIT. See package metadata.

ndkode / marketplace-integrator

Maintainers

Package info

Statistics

Security