Choose an integration path with concrete contracts
Start by choosing the surface you need to connect. The maintained developer page shows request bodies, 200 success responses, 4xx and 5xx error examples, and rate-limit counts instead of making partners reverse-engineer restaurant, menu, table, payment, and support behavior from app pages.
- Hosted menu links open public restaurant menus, table tags, QR menus, NFC menus, and Quick Pay locations without API credentials.
- Partner APIs are for approved server-to-server integrations that need credentials, scoped access, and production certification.
- Endpoint examples include the visible HTTP status, JSON response body, required headers, and retry/idempotency notes.
- Webhooks should be used for asynchronous status changes such as order, payment, table-session, delivery, or POS events when an integration is approved.
- POS and delivery connectors should preserve money, fulfillment, and customer-data boundaries instead of turning tbltap into the merchant, courier, bank, or payment processor.
Access model
Developer access is intentionally gated until the public credential, sandbox, rate-limit, and certification flows are complete. The docs page should be the maintained entry point, but it must not promise self-serve production access before the product supports it.
- Public docs can be read without signing in.
- API credentials are partner-scoped and should be issued only through an approved tbltap process.
- Production access should require reviewed use case, scoped credentials, webhook replay plan, and live-safe smoke evidence.
- Secrets, API keys, webhook signing secrets, card data, cookies, and customer PII must never be posted in public docs or support requests.
Operational contracts
Developer docs should make integration safety visible in the same place as endpoint examples.
- Use idempotency keys for mutating requests that create orders, payments, deliveries, dispatches, or external state.
- Read rate-limit headers such as X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After before retrying.
- Clients should branch on stable error codes in the shared error envelope rather than matching prose.
- Treat payment state as authoritative only after processor-backed confirmation and tbltap server state agree.
- Keep public menu media on tbltap-approved static variants and do not emit third-party, signed, original-only, or Supabase render URLs.
- Use webhooks and retry-safe reconciliation instead of polling tight loops or assuming every network timeout means a mutation failed.