Connectors

What a connector is

A connector is a small Fastify service that:

1. Accepts gateway requests authenticated with X-Synchronity-Connector-Key.
2. Translates them into the storefront's native API call (Woo REST, Shopify UCP, your custom endpoints).
3. Reshapes the response into AMPS — the unified protocol the gateway speaks.

The gateway never talks to a storefront directly. It only talks to connectors.

Just want to connect your store? This page is the architecture / build-your-own reference. To connect a WooCommerce or custom store from the portal, follow the Connect your store guides.

Built-in connectors

Each connector is independently deployable and communicates with the gateway over HTTPS.

Registering a site

1. Deploy the connector with its own env (GATEWAY_URL, CONNECTOR_BASE_URL, AGENTMESH_CONNECTOR_KEY, plus whatever your storefront needs).

2. Register the site with the gateway. The merchant calls:

   curl -X POST https://api.synchronity.app/v1/register-site \
     -H 'authorization: Bearer <merchant_token>' \
     -H 'content-type: application/json' \
     -d '{
       "name": "Pronto Partners",
       "platform": "shopify",
       "connector_base_url": "https://shopify-connector.example.com",
       "api_key": "<raw connector key>",
       "prohibited_goods_attested": true
     }'

   The gateway HMAC-hashes the raw key (so the raw key only lives in the connector's env from then on), stores the site record, and returns the new site_id.

   prohibited_goods_attested is required and must be true. It is your confirmation that the store sells physical goods and does not deal in the categories listed at Prohibited & Restricted Goods. Registration is rejected without it.

3. Agents discover the site via list_sites. Done.

Writing a new connector

The REST-generic connector is the starting point, and the Shopify connector is the canonical example of reshaping a platform-native payload into AMPS.

1. Start from the REST-generic connector.
2. Implement the HTTP routes the gateway expects (/products/search, /cart/create, /checkout/execute, …) — the full contract ships with the connector reference.
3. Make sure every response conforms to the AMPS protocol. The gateway rejects anything it doesn't recognise.
4. Validate the connector key against your own env on every request.
5. Deploy. Register. Test.

Why connectors instead of direct integrations?

Three reasons:

• Connector keys never leak. Merchant credentials live in one place — the connector's env. The gateway never sees them.
• Per-platform isolation. A bug in the Shopify normalizer can't break WooCommerce traffic. Each connector is a separate process.
• Capability discovery. Connectors publish a manifest (GET /manifest) telling the gateway what they support — manage_cart, execute_checkout, apply_coupon. Sites are flagged accordingly; agents only see capabilities the underlying connector supports.