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 orders
  • OPOTOPO_ORGANIZATION_ID — the seller organization; without it items are created on behalf of the key organization, for a personal key — on behalf of its owner
  • OPOTOPO_PUBLISH — false keeps new items as drafts
  • OPOTOPO_SCHEDULE — the synchronization cron expression; an empty value removes the schedule
  • OPOTOPO_WEBHOOK_SECRET — the signing secret of the notification address; with it the package receives notifications
  • OPOTOPO_WEBHOOK_PATH — the notification path on the site, opotopo/webhooks by default
  • OPOTOPO_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 disk disk or an SplFileInfo

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

  1. In the "Webhooks" block of the "API" section add the address https://your-site/opotopo/webhooks with the "New order" and "Purchase revoked" events, and put its signing secret into OPOTOPO_WEBHOOK_SECRET.
  2. 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.

Was this article helpful?

Did not find the answer to your question?

Create a request