Skip to content
TechTur POS

AI agent integration guide

For Claude Code, Codex or any coding agent asked to connect an existing application to TechTur POS. Follow the steps in order and write down what you find; the final step is a report.

Sources of truth — use only these

  1. This Developer Centre (or docs/integrations/ in the techtur-pos repository).
  2. The OpenAPI document: https://pos.techtursolutions.com/developers/openapi.json.
  3. The connector manifest schema: /developers/connector-manifest.schema.json.
  4. The SDK @techtur-pos/sdk (source: packages/sdk in techtur-pos).
  5. The starter: examples/techtur-pos-connector-template/.

If an endpoint is not in the OpenAPI document, it does not exist. Do not invent routes, fields or scopes.

Never

  • Connect to a TechTur POS database. Integrations use the HTTP API only.
  • Hard-code credentials, or commit .env files or secrets.
  • Trust a businessId, userId or role that arrives from a browser; resolve them server-side.
  • Treat equal email addresses as the same person.
  • Circumvent authentication, CSRF or tenant checks in either application.
  • Disable or bypass the host application's existing business rules (payment flows, quotation flows, moderation).
  • Write fields the other system owns (see data ownership).
  • Create transactions without an idempotency key or externalRef.
  • Claim the integration works without running the tests in step 22–24.

Steps

Understand the host application

  1. Inspect the architecture: framework, folder layout, how it deploys, where server code runs.
  2. Identify the authentication system: session type, where the current user is read, how roles are checked.
  3. Understand user roles: which roles are owners, managers, staff.
  4. Identify the tenant concept: business, shop, seller, organisation — and its ID field.
  5. Map the product catalogue: model names, price fields (VAT basis!), images, active flags, soft deletes.
  6. Identify variants: sizes/colours as rows, or options/modifiers as add-ons.
  7. Understand inventory: is stock physical, a per-day capacity, or not tracked? Who changes it?
  8. Inspect orders and payments: statuses, when an order counts as paid, how refunds work.

Read the contract 9. Read Connector specification. 10. Read the OpenAPI document for the endpoints you will call.

Build 11. Add @techtur-pos/sdk; configure it from environment variables (TECHTUR_POS_BASE_URL, TECHTUR_POS_CLIENT_ID, TECHTUR_POS_CLIENT_SECRET, TECHTUR_POS_WEBHOOK_SECRET). Add them to the host's .env.example without values. 12. Write a mapping module: host models → SyncProductInput, host orders → CreateOrderInput. Keep it pure and unit-tested. 13. Implement identity: launch tickets for a TechTur platform (SSO), or OAuth for third parties (Authentication). 14. Establish business mapping: store nothing you can resolve; use platform.resolveBusiness(externalId) or the OAuth business_id. 15. Configure permissions: request the minimum scopes; write the manifest; validate it. 16. Product sync: initial full sync (batches of 200), then incremental on create/update/delete in the host. 17. Inventory: read from POS; subscribe to inventory.changed; never decrement locally for orders you pushed. 18. Orders: push when the host considers an order real (paid, or accepted-unpaid → reserve). Use the host's order id as externalRef. 19. Webhooks: an endpoint that verifies signatures on the raw body, de-duplicates on event id, acknowledges fast and works asynchronously. 20. Navigation: add a POS entry to the host's existing menu for roles that may use it, in the host's design language. The entry calls your server, which mints a launch ticket and redirects. 21. Preserve existing workflows: POS calls are side effects after the host's own transaction commits; a POS outage must not break checkout in the host — queue and retry.

Prove it 22. Integration tests in the host against the POS sandbox: product sync (and resync unchanged), order idempotency, webhook verification (good, forged, stale), disconnect handling. 23. Tenant isolation: a user of business A cannot trigger a sync or launch for business B; a foreign businessId gets 404. 24. Error handling: simulate 429/500/network failure; confirm retries reuse the idempotency key and nothing is duplicated. 25. Update the host's docs: environment variables, how to run a manual sync, where errors are logged. 26. Write the integration completion report (template below).

Completion report template

Host application: <name, repo, commit>
Auth model found: <…>    Tenant model: <…>    Role mapping: <host role → POS role>
Scopes requested: <…>    Manifest validated: yes/no
Implemented: identity / products / inventory / orders / webhooks / navigation
Data ownership: <field → owner>
Tests run: <command> → <pass/fail counts>; sandbox business id <…>
Not done / blocked: <… and why>
Environment variables added: <names only>
Risks: <…>