API Conventions

Shared rules for the partner Web API (/api/v1/). Follow these conventions so pagination, errors, and auth behave predictably.

Base URL & format

Production: https://yoursite.com/api/v1/
Local: http://localhost/fshop/api/v1/
Request / response body: JSON, UTF-8
For POST / PATCH / PUT send Content-Type: application/json
Prefer HTTPS in production

Success & error envelopes

Product endpoints typically return { success, data, message, meta }. Order lists use a Trendyol-like shape (totalElements, content[]). Errors usually look like { "success": false, "message": "..." }.

HTTP status codes

Code	Meaning
`200`	Success
`201`	Created (e.g. product / image)
`400`	Invalid request
`403`	API disabled, invalid key, or missing permission
`404`	Record not found
`405`	Method not allowed
`422`	Validation error
`429`	Rate limit exceeded
`503`	API key not configured

Rate limits

300 successful requests per IP per 15 minutes (HTTP 429 when exceeded)
Failed authentication lockout: about 30 failures per IP per 15 minutes

Pagination (critical):

Products: page is 1-based (default 1)
Orders, categories, brands: page is 0-based (default 0)

Mixing these is a common integration bug.

Method override

When the client can only send POST, you may pass _method=PUT, PATCH, or DELETE (query or body) to emulate those verbs.

Field aliases

Many fields accept both styles. For cargo on orders, use either cargoCompany / trackingNumber or snake_case aliases (cargo_company, tracking_number). Products likewise accept category / category_id, brand / brand_id, and similar pairs.

Permissions

Each API key has scopes such as orders.read, orders.write, products.read, products.create, products.update, products.delete, categories.read, brands.read. See Authentication.

No webhooks in Web API v1: there is no push notification for new orders. Poll List Orders on a schedule instead. Storefront / module callbacks are a separate surface — see Storefront AJAX API and Payment Module Development.

Success response (products)

{
  "success": true,
  "data": [],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 10,
    "pages": 1
  }
}

Error response

{
  "success": false,
  "message": "Geçersiz API anahtarı"
}