Public API vs internal MiniTill routes

Overview

• MiniTill maintains an API route registry that classifies routes as public-ready, internal-only, or private/dangerous.
• Only public-ready routes are part of the supported Developer API contract and included in public OpenAPI/Postman documentation.
• Examples of intentionally internal routes include Billing operations, member/invitation management, Till Closing internals, marketplace-settlement internals, Xero OAuth/sync, KDS device management/polling, printer/bridge routes, onboarding, and user-profile routes.
• POS PIN/unlock and payment-provider credential/settings routes are explicitly private/dangerous and must never be treated as public integrations.
• Consumer Online Ordering submission routes and native device-local workflows are also not equivalent to a third-party server API contract.

When to use this

• Use this boundary whenever a developer discovers a working URL in browser/network logs or source code and wonders whether it is safe to integrate against.

Step-by-step

1. Search the public API Reference/OpenAPI first.
2. If the route is documented there, use its scopes/schema.
3. If it is absent, do not build a production external dependency on it.
4. Request a supported public endpoint when a real integration need is missing.
5. Keep native hardware/device responsibilities in the appropriate MiniTill native client/bridge.

Common mistakes

• Do not scrape Back Office endpoints or reuse browser session cookies for third-party automation.
• Do not call private terminal/PIN/device routes from an external server.
• Do not assume /api/v1 in the URL alone means 'public API'.

Troubleshooting

• If an undocumented route changes, it may be internal by design; move the integration to a documented public route.
• If a required capability is genuinely absent from the public contract, treat it as a product/API request rather than bypassing the boundary.