API loyihalash

GET    /api/v1/mahsulotlar                  ro'yxat
POST   /api/v1/mahsulotlar                  yaratish
GET    /api/v1/mahsulotlar/42               bitta
PUT    /api/v1/mahsulotlar/42               to'liq yangilash
PATCH  /api/v1/mahsulotlar/42               qisman yangilash
DELETE /api/v1/mahsulotlar/42               o'chirish

GET    /api/v1/mahsulotlar/42/sharhlar      ichki resurs
POST   /api/v1/mahsulotlar/42/sharhlar      sharh qo'shish

GET    /api/v1/buyurtmalar/17/elementlar

POST /api/v1/buyurtmalar/17/bekor-qilish
POST /api/v1/mahsulotlar/42/nashr-qilish
POST /api/v1/foydalanuvchilar/8/parolni-tiklash
POST /api/v1/sessiyalar                     (kirish)
DELETE /api/v1/sessiyalar/joriy             (chiqish)

POST /api/v1/buyurtmalar
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "elementlar": [
    {"mahsulot_id": 42, "soni": 2},
    {"mahsulot_id": 17, "soni": 1}
  ],
  "manzil_id": 5,
  "tolov_usuli": "karta",
  "izoh": "Kechqurun yetkazing"
}

HTTP/1.1 201 Created
Location: /api/v1/buyurtmalar/1042
Content-Type: application/json

{
  "malumot": {
    "id": 1042,
    "raqam": "B-20260815-0042",
    "holat": "yangi",
    "jami": {"qiymat": 750000, "valyuta": "UZS"},
    "yaratilgan": "2026-08-15T14:22:31+05:00",
    "elementlar": [
      {
        "mahsulot_id": 42,
        "nomi": "Klaviatura Logitech",
        "narx": {"qiymat": 250000, "valyuta": "UZS"},
        "soni": 2,
        "summa": {"qiymat": 500000, "valyuta": "UZS"}
      }
    ]
  }
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "xato": {
    "kod": "validatsiya_xatosi",
    "xabar": "So'rovda xatolar bor",
    "tafsilotlar": [
      {
        "maydon": "elementlar.0.soni",
        "kod": "min_qiymat",
        "xabar": "Soni kamida 1 bo'lishi kerak"
      },
      {
        "maydon": "manzil_id",
        "kod": "topilmadi",
        "xabar": "Bunday manzil mavjud emas"
      }
    ],
    "sorov_id": "req_8f3a1d0e4b7c"
  }
}

GET /api/v1/mahsulotlar?sahifa=3&chegara=20

{
  "malumot": [...],
  "meta": {
    "jami": 245,
    "sahifa": 3,
    "chegara": 20,
    "sahifalar": 13
  },
  "havolalar": {
    "ozi":      "/api/v1/mahsulotlar?sahifa=3&chegara=20",
    "birinchi": "/api/v1/mahsulotlar?sahifa=1&chegara=20",
    "oldingi":  "/api/v1/mahsulotlar?sahifa=2&chegara=20",
    "keyingi":  "/api/v1/mahsulotlar?sahifa=4&chegara=20",
    "oxirgi":   "/api/v1/mahsulotlar?sahifa=13&chegara=20"
  }
}

GET /api/v1/mahsulotlar
    ?kategoriya=5
    &narx_dan=100000
    &narx_gacha=500000
    &mavjud=true
    &qidiruv=klaviatura
    &saralash=-narx,nomi
    &maydonlar=id,nomi,narx

final class MahsulotFiltri
{
    public function __construct(
        public readonly ?int $kategoriyaId = null,
        public readonly ?int $narxDan = null,
        public readonly ?int $narxGacha = null,
        public readonly ?bool $mavjud = null,
        public readonly ?string $qidiruv = null,
        public readonly array $saralash = ['id' => 'asc'],
    ) {}

    public static function sorovdan(array $parametrlar): self
    {
        return new self(
            kategoriyaId: isset($parametrlar['kategoriya'])
                ? (int) $parametrlar['kategoriya'] : null,
            narxDan: isset($parametrlar['narx_dan'])
                ? (int) $parametrlar['narx_dan'] : null,
            qidiruv: $parametrlar['qidiruv'] ?? null,
            saralash: self::saralashniTahlilQiling($parametrlar['saralash'] ?? 'id'),
        );
    }

    private static function saralashniTahlilQiling(string $satr): array
    {
        $ruxsat = ['id', 'nomi', 'narx', 'yaratilgan'];
        $natija = [];

        foreach (explode(',', $satr) as $maydon) {
            $yonalish = str_starts_with($maydon, '-') ? 'desc' : 'asc';
            $maydon = ltrim($maydon, '-+');

            if (in_array($maydon, $ruxsat, true)) {
                $natija[$maydon] = $yonalish;
            }
        }

        return $natija ?: ['id' => 'asc'];
    }
}

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1755264000
Retry-After: 3600

{
  "xato": {
    "kod": "chegara_oshdi",
    "xabar": "Soatiga 1000 so'rov chegarasi oshdi. 1 soatdan keyin urinib ko'ring."
  }
}

POST /api/v1/buyurtmalar
Idempotency-Key: 8f3a1d0e-4b7c-4a5f-9d1e-3b6c8a0f2d4e

final class IdempotentlikOraliqQatlami
{
    public function ishlang(Sorov $sorov, callable $keyingi): Javob
    {
        $kalit = $sorov->sarlavha('Idempotency-Key');

        if ($kalit === null) {
            return $keyingi($sorov);
        }

        $saqlangan = $this->kesh->oling("idem:{$kalit}");
        if ($saqlangan !== null) {
            return $saqlangan;
        }

        $javob = $keyingi($sorov);

        if ($javob->kod() < 500) {
            $this->kesh->saqlang("idem:{$kalit}", $javob, 86400);
        }

        return $javob;
    }
}

openapi: 3.0.3
info:
  title: Onlayn do'kon API
  version: 1.0.0
  description: Mahsulotlar va buyurtmalar bilan ishlash

servers:
  - url: https://api.dokon.uz/v1
    description: Ishlab chiqarish
  - url: https://sinov-api.dokon.uz/v1
    description: Sinov muhiti

paths:
  /mahsulotlar:
    get:
      summary: Mahsulotlar ro'yxati
      parameters:
        - name: kategoriya
          in: query
          schema: { type: integer }
        - name: sahifa
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
      responses:
        '200':
          description: Muvaffaqiyatli
          content:
            application/json:
              schema:
                type: object
                properties:
                  malumot:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mahsulot'

    post:
      summary: Yangi mahsulot yaratish
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MahsulotSorovi'
      responses:
        '201':
          description: Yaratildi
        '422':
          description: Validatsiya xatosi

components:
  schemas:
    Mahsulot:
      type: object
      required: [id, nomi, narx]
      properties:
        id:   { type: integer, example: 42 }
        nomi: { type: string, example: "Klaviatura Logitech" }
        narx:
          type: object
          properties:
            qiymat:  { type: integer, example: 250000 }
            valyuta: { type: string, example: "UZS" }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

// Webhook yuborish
final class WebhookYuboruvchi
{
    public function yuboring(string $url, array $hodisa, string $sir): void
    {
        $tana = json_encode($hodisa, JSON_UNESCAPED_UNICODE);
        $imzo = hash_hmac('sha256', $tana, $sir);

        $this->http->post($url, [
            'sarlavhalar' => [
                'Content-Type'      => 'application/json',
                'X-Webhook-Imzo'    => $imzo,
                'X-Webhook-Hodisa'  => $hodisa['turi'],
            ],
            'tana' => $tana,
        ]);
    }
}