Integrations
Building a plugin
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- 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.
- Sync. Send the catalogue or content once (a full sync), then keep it current as items are created, updated and deleted (incremental sync).
- Search UI. Replace or extend the storefront search, using the public search key.
Zero-friction connect (recommended)
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
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. |
Fetching the consent-screen links
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:
GET /api/v1/connect{
"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)
{
"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)
{ "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_keyonce per site and store it with the keys. Repeating a request with the samesite_urlandidempotency_keywithin 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_urlcan be connected automatically once. A second attempt with a differentidempotency_keyreturns409. 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/connectagain.
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.
Plan management link
Give the owner a quick way to manage their plan from the plugin:
POST /api/v1/sites/{site}/upgrade-link HTTP/1.1
X-Write-Key: wk_...
X-Write-Secret: ...{ "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:
DELETE /api/v1/sites/{site}/disconnect HTTP/1.1
X-Write-Key: wk_...
X-Write-Secret: ...{ "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:
// 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:
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
/healthfirst. - Incremental sync: hook into your platform's lifecycle events, so each
change sends a single
PUT(orDELETE). 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.
5. Storefront search
Use the search key from the browser. Storefront search has two parts: results and autocomplete.
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
suggestby about 200 ms. - Render
hits[].source(title, url, image, price and so on), and showfacets.typesas filters. - Show the
highlightsnippets, or sendhighlight=falseif 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
keyas a query parameter, not in theX-Search-Keyheader, from the storefront's own domain (the key works on no other).GETsearches 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):
// 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.xmlsection under Stores → Configuration for the base URL, the site id and the keys. Store the secret as anobscure(encrypted) field. - Incremental sync: a plugin or observer on
Magento\Catalog\Model\ResourceModel\Product::saveand::deletethat callsupsertordelete. 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 sendsPOST /documentsbatches. - Storefront: a frontend module or Knockout component that calls the search endpoints in place of the catalogue search results.
// 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
/healthwhen 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.
-
429is 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_keyis 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 /disconnectand clears the stored keys, so uninstalling leaves nothing behind.