أدلة المطورين باللغة الإنجليزية.

Postman collections

Ready-to-import Postman collections for every POS GROVE API category. Each request comes with its path and query parameters, an example body, a saved example answer and the permission it needs — so you can make your first call in a couple of minutes.

Overview

  • POS API — your own POS GROVE installation (https://your-store/api/v1): 94 requests in 15 categories. Download one category, or all of them in one collection with a folder per category.
  • Domain & wallet API — POS GROVE (https://update.posgrove.com/api/v1): 19 requests for domains, DNS, nameservers, orders and the wallet.
  • Format: Postman Collection v2.1. The collections are generated from the same source as this reference (openapi.json), so they always match it.
  • Every collection signs requests for you and checks that each answer has the standard { "success": … } envelope (see the Tests tab).

Import into Postman

From a file: download a collection below, then in Postman choose Import (or press Ctrl/⌘ + O) and drop the file in.

From a link (nothing to download; importing the same link again later offers to replace your copy with the latest version): choose Import, paste the link and press Enter. For example, every POS API endpoint:

https://posgrove.com/docs/postman/pos-api-all.postman_collection.json

Then open the collection, go to Variables and set baseUrl (and your key or token — next section). Save with Ctrl/⌘ + S.

Sign in

CollectionbaseUrlCredential
POS APIYour POS GROVE address followed by /api/v1, e.g. https://shop.example.com/api/v1Paste an API key (Online store → API & Webhooks) into accessToken, or run Sign in → Get an access token with a username and password: the token (valid 12 hours) is saved into accessToken automatically.
Domain & wallet APIAlready set to https://update.posgrove.com/api/v1Create a key under Account → Developer API and paste it (pgk_…) into apiKey.

Requests that need no credential (getting a token, listing domain prices) are set to No auth. Treat keys and tokens like passwords: keep them out of shared workspaces and exported collections, or store them in an environment variable marked secret.

POS API, by category

Each category collection works on its own: it includes the Get an access token request in a Sign in folder.

CategoryRequestsWhat it coversDownload
All POS API endpoints94Every category in one collection, one folder per category.Download
Authentication4Get an access token with a username and password, or use an API key created in Online store > API & Webhooks. Send either as `Authorization: Bearer <token>` (API keys may also use `X-API-Key`).Download link
Users5Staff accounts. Password hashes, two-factor secrets and session data are never returned. API keys need the `admin` scope.Download link
Stores2Stores (branches). Without the pos.stores permission you only see the store your account is assigned to. API keys need the `pos` scope.Download link
Products8Products, variants, prices and stock. Reading needs pos.products or pos.pos; changes need pos.products. Cost prices are only shown with pos.products. API keys need the `pos` scope.Download link
Orders & refunds8Sales orders and refunds. Reading needs pos.sales or pos.pos; selling needs pos.pos. Orders are created in your store with catalogue prices. API keys need the `pos` scope.Download link
Customers6CRM customers, with loyalty balances. Reading needs crm.customers (or pos.pos, for looking up customers at the till); changes need crm.addcustomer. API keys need the `crm` scope.Download link
CRM6Leads (crm.leads), support tickets (crm.view), the loyalty report (crm.loyalty) and a customer timeline. API keys need the `crm` scope.Download link
HR7Employees (hr.employees), attendance (hr.attendance), leave (hr.leaves) and payroll (hr.payroll). Read only. API keys need the `hr` scope.Download link
Finance21Read-only access to the Finance module. Each list needs the matching Finance permission (e.g. financial.finexpenses). API keys need the `finance` scope.Download link
Projects5Projects (project.project) and tasks (project.alltask), limited to the ones you take part in. API keys need the `projects` scope.Download link
Reports3Sales reports (pos.report or pos.sales). Cancelled and refunded orders are left out. Default period: the last 30 days. API keys need the `reports` scope.Download link
Admin3Activity log, permissions and settings. API keys need the `admin` scope.Download link
Notifications2Your own in-app notifications (the bell). No extra permission needed. API keys need the `notifications` scope, or plain read/write.Download link
Webhooks12Send events to other systems. Each delivery is a signed JSON POST (see the X-Webhook-Signature header: HMAC-SHA256 of "<timestamp>.<body>" with the webhook secret), retried with growing delays when the receiver is down. Needs pos.onlinestore; API keys need the `admin` scope.Download link
AI assistant2Questions about sales, stock, customers, finance, HR and projects, answered from this installation's data without any internet service. API keys need the `ai` scope (or plain read) plus the scope of the data asked about.Download link

Domain & wallet API

Search, register, renew and manage domains, DNS and nameservers, paid from your POS GROVE wallet. Paid from your POS GROVE wallet; see the Domain & wallet API reference for prices, errors and limits.

Download the collection (19 requests)

https://posgrove.com/docs/postman/domain-wallet-api.postman_collection.json

Environments

Optional. Use an environment when you work with more than one store (for example a test and a live installation): import it, fill in the values, and pick it in the top-right corner of Postman. Environment values take priority over the collection's variables.

Tips

  • Path values such as :id are filled in on the request's Params tab. Optional query parameters are listed there too, switched off — tick the ones you need.
  • Requests that change data (POST, PUT, PATCH, DELETE) work on your real data. Try them on a test store first.
  • For PATCH requests the body starts empty: send only the fields you change. The request's description lists the fields.
  • Each request's Examples show a typical successful answer.
  • Run a whole folder with the Collection Runner to smoke-test an installation after an update.
  • Permission and scope notes in each description tell you what the user or API key must be allowed to do; a missing permission answers 403.

Other API tools

Insomnia, Bruno, Hoppscotch and Thunder Client import Postman v2.1 collections directly. Tools that prefer OpenAPI (Swagger UI, Stoplight, code generators) can use openapi.json.