Accounting & books sync

Hand it to an agent

This prompt briefs an AI coding agent to implement the entire recipe against the live docs — authentication, every endpoint, and webhooks.

Build an accounting sync service between Ewity and <accounting system>, as an Ewity App.

Setup: an Ewity app exists with API key <EWITY_APP_KEY> and approved scopes r/history-bill + r/read-expenses. Base URL https://api.ewitypos.com/apps-v1 — every request needs headers Authorization: Bearer <EWITY_APP_KEY> and X-Ewity-Store: <store_id> (one store id per merchant install). Docs: https://ewity-api.readme.io/docs/building-apps and the Apps API reference at https://ewity-api.readme.io/reference.

1) Webhook receiver: POST endpoint that verifies X-Ewity-Signature (t=<ts>,v1=<hex hmac_sha256(secret, "{t}.{raw_body}")>, constant-time compare, reject |now-t| > 300s), dedupes on envelope id, and handles: app.installed (persist install.store_id, start onboarding → ask the merchant to pick the target ledger in <accounting system>), app.uninstalled (deactivate), bill.created (enqueue a journal post), bill.voided / bill.refunded (enqueue reversals — the envelope links the parent bill), payment.created (settle receivables; settled_bill: true = receivable cleared), payment.reversed (re-open the receivable), expense.created / expense.updated (sync purchases), and register_session.closed (batch-post the session's takings via GET /sales/bills/location/{location_id}?q_register_session_id={id}).
2) Journal mapper: GET /sales/bills/{id} for the full bill; produce a journal entry: revenue per line (tax-exclusive), tax liability from taxes[], discounts/fees as their own lines, and a receivable/settlement line per payment method. Refund/void bills post as reversals — branch on the bill type.
3) Expense sync: nightly GET /expenses per install (filter to since-last-sync with q_ params + order_by), map to purchases/expense claims in <accounting system>.
4) Nightly reconciliation: page through GET /sales/bills/location/all (order_by=id:desc, q_ filters) since the last synced bill per install and post anything missed; log discrepancies instead of double-posting (idempotency key = bill id).
5) Ops: per-install sync state, exponential backoff on <accounting system> rate limits, and a small status page per merchant (last sync, pending queue, errors).

…or follow the build, step by step

1. 1

   Create the app & request read scopes

   In the developer portal, create an app, set its category to Accounting, and request only the read roles you need.

   • Request `r/history-bill` (bill history), `r/read-expenses` and — if you post daily summaries rather than individual bills — `r/day-summary-report`. Merchants see exactly this list at install; the smaller it is, the more installs you get.
   • Set Configuration → Category to Accounting so the app lists in the right App Store section, and fill in your website + developer contact (required to go live).
   • No Connect URL is needed unless merchants must link an account on your side; if they do, configure one and Ewity will collect the pairing code at install.

   Read the docs for this step
2. 2

   Handle installs

   Each merchant install gives you a store id — that's your tenant key.

   • POST{your_webhook_url}Receive app.installed / app.uninstalled

   • Add a webhook endpoint subscribed to `app.installed`, `app.reauthorized` and `app.uninstalled`. The envelope's `install.store_id` is the value you send back as the `X-Ewity-Store` header on every API call for that merchant.
   • Store the mapping install → your books entity (company file, organisation, ledger) at this point — ask the merchant to pick the target in your onboarding UI.

   Read the docs for this step
3. 3

   Pull bills, payments & expenses

   Read the ledger through the Apps API gateway as the merchant's scoped user.

   • GET/apps-v1/sales/bills/location/allList bills (paginated, filterable)
   • GET/apps-v1/sales/bills/{id}Bill detail with lines & payments
   • GET/apps-v1/expensesList expenses

   • Every call carries `Authorization: Bearer <your app API key>` plus `X-Ewity-Store: <store_id>`; the gateway executes it as a dedicated per-install user, so merchant-side audit logs attribute activity to your app.
   • Lists use `page` / `limit` (default 20) / `order_by=field:desc`; filter server-side with `q_` params — `q_register_session_id` on the bills list is how you pull exactly one closed session's bills.
   • Map bill lines to your journal shape: tax-inclusive line totals with a `taxes[]` breakdown, discounts and fees as their own components, and payments (possibly partial, possibly multiple methods) recorded against the bill.

   Read the docs for this step
4. 4

   Stay current with webhooks + a nightly sweep

   The sales-cycle events keep the books live; the sweep is the safety net.

   • POST{your_webhook_url}Receive the sales-cycle events

   • Subscribe to the sales-cycle events: `bill.created` (post the journal as each sale lands), `bill.voided` / `bill.refunded` (post reversals — the payload links the parent bill), `payment.created` / `payment.reversed` (receivables; `settled_bill: true` is the moment a receivable clears), and `expense.created` / `expense.updated`. Verify the `X-Ewity-Signature` on every delivery and dedupe on the envelope `id`.
   • `register_session.closed` is the day-close trigger the built-in accounting integrations key on: fetch the session's bills with `q_register_session_id` and post the day's takings in one batch if you prefer batch posting over per-bill journals.
   • Run a nightly reconciliation pull per install (bills since last sync) so a missed delivery can never silently skew the books.

   Read the docs for this step