GROperator

Conventions

The rules below apply to every endpoint, so you only learn them once.

Every endpoint lives under /api/public/v1. The version is part of the path. The generated OpenAPI document is also served live at /api/public/v1/openapi.json. Write clients that ignore response fields they do not know, so that new optional fields never break them.

  • Requests and responses are JSON, encoded as UTF-8. Send Content-Type: application/json on requests with a body. The only exception is the shipping label, which is a PDF.
  • Field names are camelCase.
  • Enums are strings, never numbers: "serviceType": "delivery", "serviceTier": "sameDay", "status": "outForDelivery". The allowed values of every enum are listed in the schemas and in the field tables of the reference.
  • Identifiers are UUIDs, except the shipment tracking number, which is a string that identifies a shipment in every route.
  • Names exist in both languages: place and status objects carry nameAr and nameEn (or statusLabelAr and statusLabelEn). Pick whichever fits your interface; you do not need Accept-Language for that.
  • Moments are ISO 8601 in UTC, for example 2026-01-15T09:30:00Z. Convert to the local time zone in your own interface.
  • estimatedDeliveryDate is a date without time, yyyy-MM-dd.
  • Date filters such as createdFrom and createdTo take the same ISO 8601 form.

List endpoints take page (starting at 1, default 1) and pageSize (default 25, at most 100; larger values are clamped to 100) and return the same envelope:

JSON
{
  "items": [],
  "page": 1,
  "pageSize": 25,
  "totalCount": 0,
  "totalPages": 0
}

Loop until page reaches totalPages. A few endpoints that return a short, complete list (statuses, webhook events, a merchant's addresses) return a plain array instead; the reference shows which.

Accept-Language decides the language of the error message: Arabic by default, English when the header prefers English (Accept-Language: en). When the message is English, the Arabic text is kept in details.messageAr. The code never changes, so branch on the code, not on the text.

Limits work in two stages:

  1. Per client IP address, before authentication: by default 600 requests per minute. IPv6 addresses are grouped by their /64 prefix, so rotating addresses inside one prefix does not give a fresh allowance. The platform can change this ceiling.
  2. Per verified caller, after authentication: by default 120 requests per minute, counted per API key, or per user for password logins. Only a verified identity selects this bucket: an X-API-Key header that fails verification never does.

Sign-in is limited separately: 30 requests per minute for login and 10 for refresh, per IP address (IPv6 by /64).

Both stages answer the same way. Over the limit the API answers 429 rate_limited with a Retry-After header (seconds) and details.retryAfterSeconds:

JSON
{
  "code": "rate_limited",
  "message": "Too many requests. Retry after the time given in the Retry-After header.",
  "status": 429,
  "details": {
    "retryAfterSeconds": 23,
    "messageAr": "طلبات كثيرة جداً. أعد المحاولة بعد المدة الموضحة في ترويسة Retry-After."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Wait for the time given, then retry. To stay well below the limit: cache lists that rarely change (countries, cities, districts, statuses), prefer webhooks over polling, and spread bulk jobs over time.

Numbers have upper bounds that match what the system can store; a larger value is refused with 400 validation_failed and a message such as Weight is too large. on that field:

Field Allowed
parcel.weightKg greater than 0, at most 9,999,999
parcel.lengthCm, widthCm, heightCm greater than 0, each at most 100,000
parcel.pieces 1 to 1000
parcel.declaredValue, payment.codAmount 0 or more, at most 999,999,999,999

POST /shipments, POST /merchants and POST /merchants/{id}/addresses accept an optional Idempotency-Key header (X-Idempotency-Key is accepted as an alias). It makes a retry safe: if a request times out and you do not know whether it was created, send it again with the same key.

  • The key is 1 to 128 printable characters without spaces. Use something stable that comes from your own data, such as order-1001, not a fresh random value on every attempt.
  • The same key with the same request within 24 hours returns the first response, with the header Idempotent-Replayed: true. No second shipment is created.
  • The same key with a different body answers 409 idempotency_key_reused.
  • Keys are scoped to your company and to the credential (API key or user). Only successful (2xx) responses are remembered, so a request that failed can be corrected and sent again with the same key.
  • If the idempotency store is briefly unavailable, the request runs without that protection rather than failing.
JSON
{
  "code": "idempotency_key_reused",
  "message": "This Idempotency-Key was already used with a different request body.",
  "status": 409,
  "details": {
    "messageAr": "تم استخدام مفتاح منع التكرار مع طلب مختلف."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Every response that is not 2xx has the same body:

JSON
{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "status": 400,
  "details": { "errors": { "recipient.phone": ["Recipient phone is required."] } },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
Field Meaning
code A stable code for programs. Generic codes such as unauthorized, or business codes in the form area.reason such as shipment.not_found
message A readable text in the language described above. Show it to a developer, not blindly to an end customer
status The HTTP status, repeated
details Extra data that depends on the code, or null
traceId Quote it when you contact support
Status When
400 The body or query is invalid: validation_failed, with details.errors mapping each field path (for example recipient.phone) to its messages. Also ambiguous_credentials when a request carries both a bearer token and an API key
401 Credentials missing or wrong: unauthorized
403 The credential lacks a scope (forbidden, with details.requiredScope), the API channel is off (channel_disabled), or the company is suspended (tenant_blocked)
404 The resource does not exist, for example shipment.not_found
409 A conflict, for example idempotency_key_reused or merchant.possible_duplicate
422 The request is well formed but a business rule or a place failed, for example shipment.cannot_cancel or geo_city_not_found
429 Too many requests: rate_limited
500 An unexpected error: internal_error
Code What to do
unauthorized Check both headers (or the bearer token). Create a new key if it was revoked or expired
ambiguous_credentials Send either Authorization: Bearer or X-API-Key with X-API-Secret, never both
forbidden Add the scope named in details.requiredScope to the key
channel_disabled Ask the platform to grant the channel and a company admin to switch it on
validation_failed Fix every field in details.errors and resend
rate_limited Wait for Retry-After, then retry
idempotency_key_reused Use a new key for a new request
geo_*_not_found, geo_*_ambiguous Let the user choose from details.candidates, see Places by name
business_rule_violation Read message; the data breaks a rule that has no code of its own

The full catalogue is in the error reference.

Retry network errors, 429 (after Retry-After) and 5xx, with a growing delay and always with the same Idempotency-Key on creates. Do not retry other 4xx responses unchanged: the request itself has to change first.