Authentication
Partner requests are authenticated with an API key, not with a user token. The key is the whole credential: anyone holding it can act as you, so it belongs on your server and in your secret manager — never in a browser, a mobile app or a git repository.
The header
Send the key on every request in the X-Api-Key header. Keys are prefixed esk_live_ or esk_sandbox_ followed by 32 characters, so the environment is visible at a glance.
X-Api-Key: esk_live_a1b2c3d4e5f60718293a4b5c6d7e8f90Creating and storing keys
Create keys on the API keys page of this portal. The plaintext key is shown exactly once, at creation: we store only its SHA-256 hash and physically cannot show it again. If you lose it, rotate the key.
/keys · 10 max
Rotation
Rotating issues a new key immediately and keeps the old one working for 24 hours. Deploy the new key inside that window; after it, the old key is refused with ERR_API_KEY_REVOKED. Revoking, by contrast, takes effect at once.
grace = 24 h
Scopes
Each key carries a set of scopes. A request outside them is refused with ERR_API_KEY_SCOPE — a 403, not a 404, so you can tell a missing permission from a missing order.
| scope | Meaning |
|---|---|
orders:read | Read the orders assigned to you: items, totals, time window, zone and status timeline. |
orders:pii | Also read the customer's name, phone and delivery address. Grant only when you actually deliver. |
logistics:write | Report delivery events (PICKED_UP, EN_ROUTE, DELIVERED, FAILED) on your own orders. |
webhooks:manage | Create and edit webhook endpoints for this key. |
payments:read | Read payment intents and their status for reconciliation. |
Environments
Every key belongs to exactly one environment. The live API accepts only live keys and the sandbox only sandbox keys; the wrong one is refused with ERR_API_KEY_ENVIRONMENT even though the key itself is valid.
live https://api.turanyol.com
sandbox http://localhost:3050Rate limits
Each key has its own limit in requests per minute, enforced with a sliding window. Over the limit the API answers 429 with ERR_RATE_LIMITED and a Retry-After header in seconds — wait that long rather than retrying immediately.
HTTP/1.1 429 Too Many Requests
Retry-After: 12
{ "statusCode": 429, "code": "ERR_RATE_LIMITED", "message": "rate limit exceeded" }Usage counters
We count requests, 4xx and 5xx per key per day and keep 35 days. The numbers are on the API keys page, and GET /v1/partner/me returns your key's scopes, rate limit and last seven days of traffic.
A first request
curl -sS "https://api.turanyol.com/v1/partner/orders?status=EN_ROUTE&page=1" \
-H "X-Api-Key: $ESADARAK_API_KEY" \
-H "Accept: application/json"What can go wrong
Every failure is a JSON envelope with a stable code. The four you will meet first:
ERR_API_KEY_INVALIDThe X-Api-Key header is missing or does not match any key.
ERR_API_KEY_SCOPEThe key is valid but does not carry the scope this endpoint needs.
ERR_API_KEY_ENVIRONMENTA sandbox key was sent to the live API, or the other way round.
ERR_RATE_LIMITEDToo many requests for this key. Wait the number of seconds in Retry-After.