Laravel client
What it does
The opotopo/seller-api-laravel package uploads the catalog of a Laravel site to the platform: it creates and updates listings, uploads files, withdraws items that dropped out of the catalog, receives purchase and order notifications, hands the buyer a key from your own licensing system and handles orders. No submission code is needed — mapping a site model to a platform item in the configuration is enough.
The package is built on the PHP client: the mapping, synchronization, rejections and notification handling are its own; this article covers the Laravel wiring.
The package is open source under the MIT license: code and releases — github.com/AdzerKI/seller-api-laravel, supported PHP and Laravel versions — the package page on Packagist.
Installation
composer require opotopo/seller-api-laravel
php artisan vendor:publish
php artisan migrate
The migration creates the opotopo_items table — items and their listings — and the opotopo_files table — uploaded files.
Site environment
OPOTOPO_API_KEY— a key of the "API" section with the write listings, remove listings and file upload permissions, plus deliver purchase data for data delivery and read orders and fulfill orders for ordersOPOTOPO_ORGANIZATION_ID— the seller organization; without it items are created on behalf of the key organization, for a personal key — on behalf of its ownerOPOTOPO_PUBLISH—falsekeeps new items as draftsOPOTOPO_SCHEDULE— the synchronization cron expression; an empty value removes the scheduleOPOTOPO_WEBHOOK_SECRET— the signing secret of the notification address; with it the package receives notificationsOPOTOPO_WEBHOOK_PATH— the notification path on the site,opotopo/webhooksby defaultOPOTOPO_URL— the platform API address
Catalogs
The catalogs key in config/opotopo.php holds the site catalogs by name: an Eloquent model with its selection and file disk plus the item mapping of the PHP client.
'catalogs' => [
'drawings' => [
'model' => App\Models\Drawing::class,
'scope' => 'published',
'disk' => 'public',
'category' => 'opotopo_category_id',
'fields' => [
'sku' => 'article',
'title' => 'name',
'description' => 'description',
'price' => 'price',
],
'attributes' => [
'Load capacity, t' => 'capacity',
],
'images' => [
'cover' => 'cover_path',
'second' => 'second_photo_path',
'gallery' => 'photo_paths',
],
'model3d' => [
'url' => 'model_url',
'orientation' => 'model_orientation',
],
'variants' => [
['name' => 'Drawings', 'price' => 'price', 'files' => 'drawing_paths'],
['name' => 'Drawings + 3D', 'price' => 'price_with_model', 'files' => 'drawing_paths', 'includes_3d_model' => true],
],
],
],
model— the Eloquent model class,scope— the local scope selecting the catalog- a value path is a model attribute: a dot follows a relation, a computed value is a model accessor
- a media file is a path on the
diskdisk or anSplFileInfo
Synchronization
php artisan opotopo:sync
php artisan opotopo:sync
php artisan opotopo:sync
The package schedules itself by OPOTOPO_SCHEDULE; the site server needs the Laravel scheduler running (schedule:run). Runs never overlap. The command prints the run summary, a table of rejections and a table of git sources of package items — the deploy key and webhook address for setting up the repository, version fetch failures; item submission and rejection codes — the PHP client.
Purchases and data delivery
- In the "Webhooks" block of the "API" section add the address
https://your-site/opotopo/webhookswith the "New order" and "Purchase revoked" events, and put its signing secret intoOPOTOPO_WEBHOOK_SECRET. - Listen to the application events:
use Illuminate\Support\Facades\Event;
use Opotopo\SellerApi\SellerApiClient;
use Opotopo\SellerApi\Webhooks\PurchaseCreated;
use Opotopo\SellerApi\Webhooks\PurchaseRevoked;
Event::listen(function (PurchaseCreated $purchase) {
if ($purchase->delivery === 'DATA') {
app(SellerApiClient::class)->deliverData($purchase->fulfillmentId, License::issue($purchase->purchaseId));
}
});
Event::listen(fn (PurchaseRevoked $revoked) => License::revoke($revoked->purchaseId));
- A notification becomes an application event once; an exception in a listener answers the platform with an error, and it retries the delivery
- The package keeps delivery marks in the application cache; signature verification and data delivery — the PHP client
Orders
Add the "Order status changed" event to the notification address and listen to it:
use Opotopo\SellerApi\Webhooks\FulfillmentStatusChanged;
Event::listen(fn (FulfillmentStatusChanged $changed) => Order::syncStatus($changed->fulfillmentId, $changed->status));
Listing, handing over and cancelling orders and shipment documents — the app(SellerApiClient::class) methods of the PHP client.
Did not find the answer to your question?
Create a request