Building Apps on Ewity

Ewity Apps go far beyond online ordering. An installed app gets role-scoped
access to the merchant's whole business — catalogue, customers, sales and
bills, quotations, inventory, purchases, expenses — through one gateway, plus
the ability to render its own UI inside the merchant's POS console and to
receive signed webhooks for everything that happens in the shop.

Merchants discover and install apps from the App Store inside Ewity POS.
You build once; every Ewity business can install.

The pieces

Piece	What it does
Apps API (`https://api.ewitypos.com/apps-v1`)	Role-scoped access to the v1 API surface — the same API the Ewity POS itself uses. Full reference in the Ewity Apps API section of the sidebar.
Scopes	Roles your app requests (e.g. `r/read-customer`, `r/create-bill`, `r/history-bill`). Merchants see and approve exactly this list at install.
App UI	JSON-described screens rendered natively in the POS console — or your fully custom UI embedded in Ewity. See App UI.
Webhooks	Signed event deliveries — bills, customers, products, quotations, orders, installs. See Webhooks for Apps.
Developer portal	developers.ewity.com — create apps, pick scopes, manage webhooks, test in sandboxes, go live.

Install flow & credentials

In the portal, create an app and select the roles it needs under
Permissions. Set its category (Ordering Platforms, Payments, Loyalty,
Accounting) so it lists in the right App Store section.
A merchant installs your app from the in-POS App Store and approves the
requested roles. Ewity creates a dedicated, scoped user for that
install — every API call your app makes runs as that user, so permission
enforcement and audit attribution work exactly like they do for staff.
You receive an app.installed webhook whose install.store_id identifies
the install. That id is your tenant key.

Every Apps API request carries two headers:

Authorization: Bearer YOUR_APP_API_KEY
X-Ewity-Store: STORE_ID_OF_THE_INSTALL

The API key is minted with the app (Credentials tab in the portal); the store
id selects which merchant install the request acts on.

If your app needs merchants to hold an account on your platform (a wallet,
a books organisation, a delivery account), configure a Connect URL — Ewity
collects a pairing code during install and the install arrives linked to
external_account_id on your side.

Request conventions

JSON over HTTPS. Paths mirror the v1 API: GET /apps-v1/customers,
POST /apps-v1/sales/bills, and so on.
Lists paginate with page and limit (default 20) and sort with
order_by=<field> or order_by=<field>:desc. Column filters use
q_<column>=<value> query params. List responses look like
{ "pagination": { "total", "pageSize", "current", "lastPage" }, "data": [...] }.
Errors return a JSON body with code, errorCode and a human message.
Rate limit: 300 requests/minute per app.

What apps can never do

Role scopes do the day-to-day enforcement, but some surfaces are hard-blocked
for every app regardless of approved roles: session/authentication endpoints,
reading or changing role assignments, managing API tokens, creating,
updating or deleting users (or changing passwords), changing permission
levels, the app management APIs (listing, installing, re-authorizing or
uninstalling apps — reads included), reports (the reporting endpoints are
blocked and report roles are not requestable), writing settings, and
modifying platform installations. If you call one of these the gateway
returns 403 with an explanation.

Changing scopes later

Editing your requested roles bumps your app's scopes version. Existing
installs keep working with the roles they already approved and are prompted to
re-authorize; new roles only activate per-install once the merchant
approves the new set.

Going live

Sandbox-test against up to 10 real businesses you whitelist, then submit for
listing from the portal's Go live tab. To list, your app needs a name, a
40+ character description, a logo, a category, a website, and a
developer contact (name + support email).