CMS connectors

A connector keeps a collection in step with a shop's catalogue. The shop never writes to the search index directly: every change goes into a per-connector journal, and a queue applies the journal to the collection. The journal is also what a rebuild reads, so a document that reached the index some other way can disappear from it at the next rebuild. Use the connector, not a direct import, for anything a CMS owns.

Supported platforms

integrations/catalog.json lists the CMS modules and where each one stands:

The connector API also accepts the providers bitrix24, woocommerce, yml, sitemap and custom. The provider is a label on the connector: every provider writes through the same webhook or pull path described below. To load a Yandex Market feed into a collection without a module, use YML feeds.

Two ways to connect a shop

Neither credential is an API key. A connector secret cannot search or read configuration, and an installation key is rejected by the tenant API. The shop never needs a full key in the browser: the rule from the widget page applies to every CMS module too, and the browser only ever uses a search-scoped key against our API.

Connectors

Create one

In the console, Sources → Add source asks for a name, the target collection, the provider, the sync mode, a schedule and, in pull mode, a pull URL and token. From code, createConnector:

curl -X POST https://api.aacsearch.com/v1/connectors \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Main catalogue","collection":"products","provider":"bitrix","sync_mode":"push"}'

The 201 response carries the signing secret once. Later reads return only secret_preview, and updateConnector never rotates it. Store the id and secret in the module (connector_id / connector_secret).

An organization can have one connector per collection and provider. A second bitrix connector for the same collection is refused, so if the module lost its secret, paste the existing id and secret from Sources into the module rather than creating another connector.

List, inspect and remove connectors

listConnectors (GET /connectors) lists every connector for the organization; getConnector (GET /connectors/{connectorId}) returns one — the secret is never included, only secret_preview. deleteConnector (DELETE /connectors/{connectorId}) removes the connector, its journal and its jobs; documents already indexed stay in the collection.

Before a module goes live it can call handshakeConnector (POST /connectors/handshake) to declare what it is (cms, version), which marketplace edition it runs as (sku) and which capabilities it can provide. The response's effective array is the intersection of what was declared, what the SKU allows and what the organization's plan covers; denied explains each capability left out (not_declared, sku or plan, with the minimum tier for a plan denial). Call it once after install and again on a schedule — it is stateless, so the platform stores nothing from it.

Push: the signed webhook

The shop posts catalogue events to POST /connectors/{connectorId}/webhook (ingestConnectorWebhook). The request carries no API key. It is authenticated by HMAC:

• X-Signature-Timestamp — Unix seconds. A timestamp more than five minutes from the server clock is rejected.
• X-Signature — hex HMAC-SHA256 of timestamp + "." + raw body, keyed with the connector secret. Sign the exact bytes you send; re-encoding the JSON after signing breaks the signature.

BODY='{"events":[{"event":"update","external_id":"42","name":"Cordless drill, 18V","price":84.0},{"event":"delete","external_id":"17"}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$CONNECTOR_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://api.aacsearch.com/v1/connectors/$CONNECTOR_ID/webhook" \
  -H "Content-Type: application/json" \
  -H "X-Signature-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d "$BODY"

The body is either one event object or { "events": [ … ] }:

event, element_id, iblock_id, source_revision and event_id are envelope keys and are not stored on the document. Within one batch, the last event for an external_id wins.

The answer counts what reached the journal and names the apply job:

{ "success": true, "data": { "received": 2, "upserted": 1, "deleted": 1, "job_id": "cnjob_…" } }

What the apply job does

Each accepted batch becomes a connector job (kind: ingest_batch) on a queue. The job reads the journal rows it names. It sends updates to the collection as an emplace import, so the fields you send change and the rest are kept (see write actions), and it deletes removed documents. A job counts as done only when the engine confirms every document. A temporary failure puts the job back in the queue to retry. A missing collection fails the job and puts the connector into error with the message. A job left queued or processing for more than 30 minutes is re-queued by a recovery cron.

So a successful webhook response means "in the journal", not "searchable yet". The job's status says when the collection has caught up.

Pull: for shops that cannot call out

Some hosts block outgoing connections. With sync_mode: "pull" the platform fetches changes from the shop instead:

• pull_url is the shop's change-log endpoint. For the Bitrix module it is https://shop.example/bitrix/tools/aac.search/pull-outbox.php.
• pull_token is sent as X-AACSEARCH-TOKEN and as Authorization: Bearer. It is the module's own pull_token option, not an API key, and the API never returns it (pull_token_set says whether one is stored).
• The request is GET pull_url?afterSequence=<cursor>&limit=100. The response is { items: [{ sequence, externalId, action, data }], hasMore, sequence } (action UPSERT/UPDATE or DELETE/DELETED). The platform stores the cursor and advances it only after the batch is queued.
• Each tick fetches at most 10 pages. The pulled events go through the same journal and apply queue as a job of kind: pull.

schedule_cron must be one of the platform's triggers: */15 * * * * (the default when empty) or 0 3 * * *.

Full and incremental sync

The platform has no "fetch the whole catalogue" call. Both kinds of sync are the shop sending events:

• Incremental — the module sends changed and deleted products as they happen (push) or exposes them in its change log (pull).
• Full — the module re-sends every product as update events. Unchanged documents are harmless to re-send: an update writes the same values again.

In the Bitrix module a full export is the Reindex page, the wizard's first export or a console command; see initial and delta indexing.

CMS installations

A CMS installation manages a shop from the console instead of from the module's settings page. It is used by the Bitrix module from 1.8.1 and by PrestaShop.

The console can also queue three commands for an installation: Reindex catalog (reindex), Sync changes (resync) and Discover catalogs (refresh_capabilities). The module takes one command at a time on a 120-second lease, renewing it and reporting progress. When a lease expires, the next pass resumes the same command. A command is completed when the data reached the journal. The index may still be processing it.

Where to watch sync status

• Sources (/dashboard/sources) lists connectors with problems first: status (idle, syncing, error, paused), last sync, last error, and a quiet badge for an enabled source that has not synced in a day.
• Source detail (/dashboard/sources/{id}) shows the last 30 jobs (listConnectorJobs, GET /connectors/{id}/jobs, statuses queued, processing, ready, error, with per-job stats and error, and limit to page) and the journal (listConnectorDocuments, GET /connectors/{id}/documents, paginated with limit/offset). It refreshes while a job is running.
• CMS stores (/dashboard/integrations/cms) shows each installation's last contact, applied revision, module and CMS versions, last error, and its recent commands with progress.

The console pages are described screen by screen in Console → Data.

Limits and failure codes

A disabled or unknown connector answers 404. Connector traffic is checked against the organization's standing even though it carries no API key. A suspended organization answers 402, an exhausted request quota 429, and a standing that cannot be verified 503. The same checks run again before a queued job writes to the collection.

Deleting a connector removes its journal and jobs. The documents already in the collection stay.

The CMS runtime protocol

Everything above is what your own server or a module's settings page calls. A module also has its own machine-to-machine protocol against /cms/runtime/* and /cms/installations/{id}/commands* — heartbeats, leasing and reporting on the three commands from CMS installations, reading the installation's entitlement and per-source schema, and enqueueing source events, behavioural events and recommendations for a bound source. It authenticates with the installation key, not an API key, and is meant for a CMS module's own code, not for a shop owner to call by hand — see the API reference for the full request and response shapes of each cms operation rather than a hand-written walkthrough here.