Connector specification

A connector is the code in your platform that talks to TechTur POS. Every connector — TechTur's own and third parties' — follows this contract.

1. Identity

A connector is an Application registered in the Developer console. Its clientId is its identity.
A TechTur platform connector is an application linked to a registered Platform (by a TechTur administrator during review). Only linked applications can hold platform:* scopes.
The connector declares itself in a manifest, techtur-pos.connector.json, validated against CONNECTOR_MANIFEST_SCHEMA.json. Upload it in the console (Manifest tab) or POST /api/v1/developer/applications/{id}/manifest.

2. Manifest

{
  "$schema": "https://pos.techtursolutions.com/schemas/techtur-pos.connector.schema.json",
  "manifestVersion": 1,
  "platform": { "id": "rekadijo", "name": "RekaDijo", "websiteUrl": "https://rekadijo.techtursolutions.com" },
  "connector": { "version": "1.0.0", "sdk": "@techtur-pos/sdk@0.1.0" },
  "posApiVersion": "v1",
  "auth": { "method": "client_credentials", "identity": "launch_ticket" },
  "scopes": ["platform:identity", "platform:businesses", "products:write", "products:read", "inventory:read", "orders:write", "orders:read"],
  "capabilities": {
    "identity": true,
    "products": { "direction": "to_pos", "mode": ["initial", "incremental", "manual"] },
    "inventory": { "direction": "from_pos", "mode": ["webhook"] },
    "orders": { "direction": "to_pos", "mode": ["webhook"] }
  },
  "businessMapping": { "model": "one_business_per_account", "externalIdField": "Business.id" },
  "events": ["inventory.changed", "order.updated", "integration.disconnected"],
  "webhooks": { "url": "https://example.com/hooks/techtur-pos", "verifiesSignature": true, "idempotentOnEventId": true },
  "dataOwnership": { "product.name": "source", "variant.price": "source", "stock.onHand": "pos", "variant.barcodes": "pos" },
  "retry": { "maxAttempts": 8, "backoff": "exponential" },
  "disconnect": { "onDisconnect": "stop_sync" }
}

Validation rejects unknown scopes and events; warnings flag capability/scope mismatches.

3. Capabilities

Capability	Meaning	Endpoints
`identity`	Users of your platform reach POS without a second sign-up	SSO and account linking
`products` `to_pos`	You are the catalogue source	`PUT …/sync/products`
`inventory` `from_pos`	POS is the stock authority; you mirror it	`GET …/stock`, `inventory.changed`
`orders` `to_pos`	Online orders flow into POS	`POST/PATCH …/orders`
`metrics`	You report usage for the TechTur Control Centre	`POST /api/v1/platform/metrics`

Connect only what makes sense. Free TechTur Tools, for example, declares metrics only.

4. Business mapping

A platform business ↔ a POS business is a BusinessPlatformLink (platform, externalBusinessId) → businessId, created only with the business owner's consent. See Business and tenant mapping.

5. Record mapping

Every synced record has an ExternalMapping (application, business, entityType, externalId) ↔ internalId, for product, variant, category and customer. Always address records by your own IDs; never store POS IDs as your primary key.

6. Data ownership

Each field has one owner. Defaults:

Field	Owner
`product.name`, `product.description`, `product.imageUrl`, `product.category`, `product.isActive`	source platform
`variant.price`, `variant.sku`	source platform
`variant.costPrice`, `variant.barcodes`	POS (the source may add barcodes, never remove)
`stock.onHand`	POS

The business can change ownership (for example make price POS-owned so in-store prices differ). A field owned by the other system is never silently overwritten: if your sync sends a different value for a POS-owned field, POS keeps its value and records a SyncConflict that a person resolves under Integrations.

7. Synchronisation direction and modes

initial — a full push on first connection (batches of 200).
incremental — push changed records; unchanged payloads are detected by hash and skipped.
webhook — react to POS events (see Webhooks).
scheduled — periodic reconciliation (recommended daily).
manual — a "Sync now" action in your admin.

8. Retry behaviour

Retry 429, 5xx and network errors with exponential backoff and the same idempotency key. Never retry 4xx (other than 429) without changing the request. The SDK does this.

9. Conflict resolution

Ownership decides. Where both systems legitimately change the same thing — stock — POS is authoritative and the platform reads it back.

10. Disconnect behaviour

When a business disconnects your app (or you revoke it), tokens stop working immediately and POS emits integration.disconnected to your endpoints. Stop syncing that business; keep data you already hold according to your own retention policy. Data in POS stays.

11. Health monitoring

GET /api/v1/platform/me as a credentials check.
Register a healthUrl for your platform: the Control Centre checks it every five minutes.
Watch API requests and Deliveries in the console.