GROperator

Enable the API

Using the API takes two switches and one key. The first switch is on the platform side, the second is in your company settings, and the key is created in the dashboard by a company admin.

The platform (GROperator) decides which companies may use the API. The channel is called API integration. If it has not been granted to your company, the dashboard page for API access tells you so and asks you to contact the platform, and every API call answers 403 channel_disabled.

A company admin opens Settings, Company and finds the section Shipment creation channels and integration (in the Arabic dashboard: قنوات إنشاء الشحنات والربط). Turn on API integration (الربط البرمجي). While the channel is off, existing keys stop working too, and no new key can be created.

  1. Open Settings, API access (الربط البرمجي).
  2. Create a key and give it a name that says what uses it, for example Website or Google Sheets.
  3. Choose its scopes (see the table below). Give the key only what the integration needs. A key can never carry more than the admin who creates it: if you request a scope whose underlying dashboard permissions you do not personally hold, the creation is refused.
  4. Optionally set an expiry date.
  5. Save. The dashboard shows the key (it starts with lmc_live_) and the secret.

The secret is shown once. Copy it into your server's secret store right away. If you lose it, revoke the key and create a new one: the platform stores only a one-way hash of the secret and cannot show it again.

Revoked and expired keys answer 401 unauthorized. A company can hold at most 20 active keys, so revoke the ones you no longer use. A revoked key can then be deleted.

A scope is a permission attached to a key. A scope that only writes does not include reading: an integration that creates shipments and then reads them back needs both shipments:write and shipments:read.

ScopeWhat it allowsEndpoints
shipments:read
Read shipments
List shipments and read their details, tracking timeline, label and the status catalogue.
  • GET /shipments
  • GET /shipments/statuses
  • GET /shipments/{trackingNumber}
  • GET /shipments/{trackingNumber}/label
  • GET /shipments/{trackingNumber}/tracking
shipments:write
Write shipments
Create, update and cancel shipments. Does not include reading: add shipments:read too.
  • POST /shipments
  • PUT /shipments/{trackingNumber}
  • POST /shipments/{trackingNumber}/cancel
merchants:read
Read merchants
List merchants and read their details and saved addresses.
  • GET /merchants
  • GET /merchants/{id}
  • GET /merchants/{id}/addresses
merchants:write
Write merchants
Create and update merchants and manage their saved addresses. Does not include reading.
  • POST /merchants
  • PUT /merchants/{id}
  • POST /merchants/{id}/addresses
  • PUT /merchants/{id}/addresses/{addressId}
  • DELETE /merchants/{id}/addresses/{addressId}
  • POST /merchants/{id}/addresses/{addressId}/primary
geography:read
Read geography
Countries, cities, districts, address validation (resolve) and coverage.
  • GET /geography/cities
  • GET /geography/countries
  • GET /geography/coverage
  • GET /geography/coverage/cities
  • GET /geography/districts
  • GET /geography/resolve
pricing:read
Read pricing
Quote the price of a shipment.
  • POST /pricing/quote
branches:read
Read branches
List the branches of the company and read one branch.
  • GET /branches
  • GET /branches/{id}
webhooks:manage
Manage webhooks
Create, list, test, rotate and delete webhook subscriptions, and read the event catalogue.
  • GET /merchants/{merchantId}/webhooks
  • POST /merchants/{merchantId}/webhooks
  • DELETE /merchants/{merchantId}/webhooks/{id}
  • POST /merchants/{merchantId}/webhooks/{id}/rotate-secret
  • POST /merchants/{merchantId}/webhooks/{id}/test
  • GET /webhooks/events

Calling an endpoint without its scope answers 403 forbidden with details.requiredScope naming the missing one. GET /auth/me and the two sign-in endpoints need no scope.

GET /auth/me
curl "https://api.goldrock.live/api/public/v1/auth/me" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

A 200 answer confirms the credentials, the scopes and the channel. Then continue with Authentication for the security rules, or go straight to the quickstart.

If you prefer to act as a user (or give merchants a login), no key is needed: the user signs in with POST /auth/login. The API channel must still be on for the company. See Authentication.