Zum Inhalt springen

Integrations

Building a plugin

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

This guide shows how to build a platform plugin on top of the Searcio API, for WordPress and WooCommerce, Magento, Shopify or a custom platform. The patterns apply to every platform, and concrete WordPress and Magento examples follow.

What a plugin must do

flowchart TD
    subgraph Backend["Server side (trusted)"]
        Cfg["1. Configuration<br/>store keys, test connection"]
        Sync["2. Sync<br/>full + incremental"]
    end
    subgraph Frontend["Browser (untrusted)"]
        UI["3. Search UI<br/>results + autocomplete"]
    end
    Cfg --> Sync
    Sync -->|"documents indexed"| SC[(Searcio)]
    UI -->|"search key"| SC
  1. Configuration. Get the site id, write key, write secret and search key onto the site, either automatically (with zero-friction connect, below) or by having the site owner paste them in, and verify them with the health endpoint.
  2. Sync. Send the catalogue or content once (a full sync), then keep it current as items are created, updated and deleted (incremental sync).
  3. Search UI. Replace or extend the storefront search, using the public search key.

Rather than sending the site owner to Searcio to register, create an account and copy four credentials into your plugin, call POST /api/v1/connect from your plugin's own server as soon as the owner clicks "Connect" and accepts your consent checkboxes. The owner needs no Searcio login and enters no keys.

flowchart LR
    A["Owner clicks Connect<br/>+ accepts consent"] --> B["POST /api/v1/connect<br/>(server-to-server)"]
    B --> C{"admin_email already<br/>a Searcio user?"}
    C -- No --> D["Account + site created instantly<br/>keys returned in the response"]
    C -- Yes --> E["status: pending_claim<br/>email sent to that address"]
    D --> F["Plugin stores keys,<br/>starts syncing immediately"]
    E --> G["Owner clicks the emailed link,<br/>picks/creates an account,<br/>copies keys in from the dashboard"]

Request

http
POST /api/v1/connect HTTP/1.1
Host: search.example.com
Content-Type: application/json

{
  "platform": "wordpress",
  "site_name": "My Shop",
  "site_url": "https://my-shop.example.com",
  "verify_url": "https://my-shop.example.com/wp-json/searcio/v1/verify",
  "admin_email": "owner@my-shop.example.com",
  "admin_name": "Ada Owner",
  "idempotency_key": "3b7e2b6e-2f7a-4e2e-9d9d-6f6e2b1a9c3f",
  "consents": { "terms_privacy": true, "dpa": true }
}
Field Required Notes
platform Yes wordpress, woocommerce, magento, shopify, or custom.
site_name Yes
site_url Yes Used to detect a second connection of the same site; see below.
verify_url No Your plugin's own domain verification callback (see below). Any URL on your site: WordPress plugins use .../wp-json/..., Magento .../rest/V1/... and so on. Without it, verification is skipped.
admin_email Yes Determines which of the two flows below runs.
admin_name No Falls back to the part of admin_email before the @.
idempotency_key Yes A UUID your plugin generates once and persists. Safe to retry the exact same request with the same key.
consents.terms_privacy Yes Must be true: the owner accepted the terms of service and the privacy policy. This is the only mandatory checkbox.
consents.dpa No true, false or omitted. Acceptance of the data processing agreement is recorded only when true.

Before you show your consent checkboxes, fetch the links to Searcio's legal documents so you can link to them. A document that is not available comes back as null:

http
GET /api/v1/connect
json
{
  "legal": {
    "terms": "https://searcio.com/terms",
    "privacy": "https://searcio.com/privacy",
    "dpa": "https://searcio.com/dpa"
  }
}

Show the terms and privacy checkbox as required and the data processing agreement checkbox as optional, each linking to its document when a URL is present. The same legal object is also part of the successful connect response below.

Response for a new email address (201)

json
{
  "site_id": 4821,
  "write_key": "wk_...",
  "write_secret": "...",
  "search_key": "sk_...",
  "plan": "Free",
  "status": "provisioning",
  "legal": { "terms": "https://...", "privacy": "https://...", "dpa": null }
}

write_secret appears only in this response, so store it immediately, just as when a site is created in the Searcio dashboard. status: provisioning means the account is active and can be used right away. The site's domain ownership is verified in the background (see below), and that check never blocks or restricts the keys you have just received.

Response for a registered email address (201)

json
{ "status": "pending_claim" }

Nothing is created or disclosed yet, because an anonymous request cannot prove that you control that inbox. An email is sent to admin_email with a link that signs the owner in and lets them choose which of their accounts to connect the site to, or create a new one. Show the owner a message such as "An account already exists for this email address. Check your inbox to finish connecting." They finish in the Searcio dashboard and copy the keys into your plugin, exactly as in the manual configuration described below.

Idempotency & duplicate protection

  • Generate idempotency_key once per site and store it with the keys. Repeating a request with the same site_url and idempotency_key within 24 hours returns the original response instead of an error, so it is safe to retry when a response was lost to a network failure.
  • A site_url can be connected automatically once. A second attempt with a different idempotency_key returns 409. This is intentional: it stops anyone from claiming a domain they do not control. If your plugin loses its stored keys, the owner should sign in to the Searcio dashboard instead of your plugin calling /connect again.

Rate limits & errors

/connect has its own limits, much tighter than the rest of the API: 20 requests per hour per IP address, 5 per day per domain and 5 per day per recipient email address. See Errors & rate limits.

Domain ownership verification (informational)

If you sent a verify_url, Searcio calls it in the background after a connection for a new email address: GET {verify_url}?token=<hmac>. The token is added to any query string your URL already has, so /?rest_route=/searcio/v1/verify (the form WordPress uses without pretty permalinks) works too. Your endpoint replies {"write_key": "<the write key you were issued>"} when the token is valid. The expected token is hmac_sha256(write_key, <the service's secret key>). Only a genuine installation that holds the write key can answer correctly, so the reply proves that the plugin really runs on that domain.

The callback works on any platform. Expose it wherever suits yours: a WordPress REST route (.../wp-json/searcio/v1/verify), a Magento web API endpoint (.../rest/V1/searcio/verify), a Shopify app proxy or any URL on a custom site. Verification is best effort and never blocks anything: your keys and the account stay exactly as they are if it fails or if you leave out verify_url. It only marks the site as verified. It is recommended for a publicly distributed plugin and optional otherwise.

Give the owner a quick way to manage their plan from the plugin:

http
POST /api/v1/sites/{site}/upgrade-link HTTP/1.1
X-Write-Key: wk_...
X-Write-Secret: ...
json
{ "status": "link_sent" }

For security, the passwordless sign-in link is emailed to the account owner rather than returned in the response. The write credentials that authenticate this request may belong to a team member who is not the owner (for example an editor who set the site up), and returning a sign-in link for the owner's account would give them the owner's access. Show a message such as "We've emailed you a link to manage your plan." The link can be used once and expires after 10 minutes.

Disconnecting

When the owner disconnects (or uninstalls) the plugin, call:

http
DELETE /api/v1/sites/{site}/disconnect HTTP/1.1
X-Write-Key: wk_...
X-Write-Secret: ...
json
{ "status": "disconnected" }

This permanently deletes the site and its search index. It is the counterpart of /connect, so nothing is left behind. The write and search keys stop working immediately, and the domain can be connected automatically again. Clear the keys your plugin stores once you receive the disconnected response.

1. Configuration & connection test

If you do not use zero-friction connect, store the four values on your server, and never expose the write credentials to the browser. When they are saved, call /health to check them:

php
// Pseudocode shared by all platforms
function searcio_test_connection(string $base, int $siteId, string $wk, string $ws): array {
    $res = http_get("$base/sites/$siteId/health", [
        'X-Write-Key'    => $wk,
        'X-Write-Secret' => $ws,
    ]);
    if ($res->status === 200) {
        $body = json_decode($res->body, true);
        return ['ok' => true, 'documents' => $body['usage']['documents']];
    }
    return ['ok' => false, 'status' => $res->status];
}

Show the result, for example "Connected: 12,450 of 50,000 documents indexed", or a clear error for 401 and 403.

2. A minimal API client

A small reusable client keeps the rest of the plugin clean:

php
final class SearcioClient
{
    public function __construct(
        private string $base,      // https://searcio.com/api/v1
        private int $siteId,
        private string $writeKey,
        private string $writeSecret,
    ) {}

    /** @param array<int,array<string,mixed>> $docs (max 1000) */
    public function bulkUpsert(array $docs): array
    {
        return $this->send('POST', "/documents", ['documents' => $docs]);
    }

    public function upsert(string $id, array $fields): array
    {
        return $this->send('PUT', "/documents/" . rawurlencode($id), $fields);
    }

    public function delete(string $id): array
    {
        return $this->send('DELETE', "/documents/" . rawurlencode($id));
    }

    public function health(): array
    {
        return $this->send('GET', "/health");
    }

    private function send(string $method, string $path, ?array $body = null): array
    {
        $ch = curl_init("{$this->base}/sites/{$this->siteId}{$path}");
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => [
                'X-Write-Key: ' . $this->writeKey,
                'X-Write-Secret: ' . $this->writeSecret,
                'Content-Type: application/json',
                'Accept: application/json',
            ],
            CURLOPT_POSTFIELDS => $body !== null ? json_encode($body) : null,
            CURLOPT_TIMEOUT    => 15,
        ]);
        $raw    = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return ['status' => $status, 'body' => json_decode($raw, true) ?? []];
    }
}

3. Mapping your entities to documents

Choose a stable id scheme and a type for each kind of entity, and map their fields to the document schema:

Your entity id type title Useful custom fields
WooCommerce product product-{ID} product product name price, sku, categories, in_stock, url, image
WordPress post post-{ID} post post title excerpt→content, url, tags
Magento product product-{entity_id} product name price, sku, url, image, is_salable

Keep ids deterministic, so an update replaces the same document. Prefix them with the type to avoid collisions between kinds of entity.

4. Full vs. incremental sync

flowchart LR
    subgraph Full["Full sync (initial / repair)"]
        A["Page through all entities"] --> B["POST /documents in batches of ~500"]
    end
    subgraph Incr["Incremental (keep fresh)"]
        C["on save/publish"] --> D["PUT /documents/{id}"]
        E["on delete/unpublish"] --> F["DELETE /documents/{id}"]
    end
  • Full sync: run it when the site is first connected, and offer it as a "sync everything again" button. Page through your data and send batches of a few hundred documents (at most 1000), within the document limit, which you can read from /health first.
  • Incremental sync: hook into your platform's lifecycle events, so each change sends a single PUT (or DELETE). This keeps the index current without a full sync.
  • Removing stale documents: to remove items that were deleted while the plugin was offline, run a full sync and then delete the ids that no longer exist on your side. Keep track of the ids you sent to make this possible.

Run syncs in the background (with cron or a queue) so your platform's back office stays fast, and limit your own rate to under 300 requests per minute.

Use the search key from the browser. Storefront search has two parts: results and autocomplete.

javascript
const BASE = "https://searcio.com/api/v1";
const SITE = 123;
const KEY  = "sk_live_xyz"; // public, locked to your domain

async function search(q, { type, page = 1, perPage = 20 } = {}) {
  const params = new URLSearchParams({ q, page, per_page: perPage, key: KEY });
  if (type) params.set("type", type);
  const res = await fetch(`${BASE}/sites/${SITE}/search?${params}`);
  if (!res.ok) throw new Error(`search ${res.status}`);
  return res.json(); // { total, hits, facets, ... }
}

async function suggest(q, limit = 5) {
  const params = new URLSearchParams({ q, limit, key: KEY });
  const res = await fetch(`${BASE}/sites/${SITE}/search/suggest?${params}`);
  return res.ok ? (await res.json()).suggestions : [];
}
  • Debounce suggest by about 200 ms.
  • Render hits[].source (title, url, image, price and so on), and show facets.types as filters.
  • Show the highlight snippets, or send highlight=false if your cards do not, which makes every search faster.
  • Add <link rel="preconnect" href="https://searcio.com" crossorigin> to the storefront's pages, so the first search does not wait for the connection to the API to be set up.
  • Send the key as a query parameter, not in the X-Search-Key header, from the storefront's own domain (the key works on no other). GET searches sent this way need no preflight. Requests that post JSON (the assistant) are preflighted, and a preflight carries no custom headers, so the key has to be in the URL for the site to be identified. See Preflights.
  • Fail gracefully: on any error, fall back to the platform's native search.

WordPress and WooCommerce example

Incremental sync hooks (on the server):

php
// Push on save/publish
add_action('save_post_product', function ($postId) {
    if (wp_is_post_revision($postId)) return;
    $p = wc_get_product($postId);
    if (!$p || $p->get_status() !== 'publish') return;

    searcio_client()->upsert("product-{$postId}", [
        'type'       => 'product',
        'title'      => $p->get_name(),
        'content'    => wp_strip_all_tags($p->get_description()),
        'url'        => get_permalink($postId),
        'image'      => wp_get_attachment_url($p->get_image_id()),
        'price'      => (float) $p->get_price(),
        'sku'        => $p->get_sku(),
        'in_stock'   => $p->is_in_stock(),
        'categories' => wp_get_post_terms($postId, 'product_cat', ['fields' => 'names']),
    ]);
}, 20);

// Remove on trash/delete
add_action('wp_trash_post', fn ($id) =>
    get_post_type($id) === 'product' && searcio_client()->delete("product-{$id}"));

Full sync runs through WP-Cron: page through the products and send batches of about 500. Build the search box with the JavaScript above, and enqueue it with the public search key.

Magento 2 example

  • Configuration: a system.xml section under Stores → Configuration for the base URL, the site id and the keys. Store the secret as an obscure (encrypted) field.
  • Incremental sync: a plugin or observer on Magento\Catalog\Model\ResourceModel\Product::save and ::delete that calls upsert or delete. Prefer an asynchronous queue (RabbitMQ or cron), so checkout and saves in the admin area stay fast.
  • Full sync: a custom indexer (Magento\Framework\Indexer) that pages through the product collection and sends POST /documents batches.
  • Storefront: a frontend module or Knockout component that calls the search endpoints in place of the catalogue search results.
php
// Simplified observer
class SyncProduct implements \Magento\Framework\Event\ObserverInterface
{
    public function execute(\Magento\Framework\Event\Observer $observer): void
    {
        $product = $observer->getEvent()->getProduct();
        $this->client->upsert("product-{$product->getId()}", [
            'type'  => 'product',
            'title' => $product->getName(),
            'url'   => $product->getProductUrl(),
            'price' => (float) $product->getFinalPrice(),
            'sku'   => $product->getSku(),
            'image' => $this->imageHelper->getUrl($product),
        ]);
    }
}

Hardening checklist

  • Write key and secret are stored on the server only and never sent to the browser.
  • The storefront searches from the domain the site was connected with (with or without www); another domain or subdomain of the shop is added by support.
  • The connection is verified with /health when the keys are saved.
  • Syncs run in the background and stay under 300 requests per minute.
  • Batches hold at most 1000 documents, and the document limit is checked before a large sync.
  • 429 is handled: back off on a rate limit, and tell the user about a plan limit.
  • The search UI falls back to the native search on errors.
  • A "sync everything again" button exists for recovery.
  • Key rotation is supported in the settings (new credentials can be entered).
  • With /connect: idempotency_key is generated once and stored with the keys, not regenerated for every request.
  • With /connect: the wording of the consent checkboxes (terms and privacy, data processing agreement) is reviewed by your own legal counsel before you publish the plugin.
  • A disconnect or uninstall hook calls DELETE /disconnect and clears the stored keys, so uninstalling leaves nothing behind.