{
 "openapi": "3.0.3",
 "info": {
  "title": "NAKAT catalog API for AI agents",
  "version": "2026-10-06.2",
  "description": "Read-only catalog of nakatshop.ru (moto, bicycles, gear; WELS brand) and a link that puts items into the visitor's cart. Orders are placed by the buyer on the site. Shop: Saint Petersburg, pr. Engelsa 15, works by prior phone call 8-812-552-09-21. Delivery across Russia by SDEK and PEK. Limit: 60 requests per minute per IP."
 },
 "servers": [
  {
   "url": "https://nakatshop.ru/local/agent"
  }
 ],
 "paths": {
  "/api.php?action=sections": {
   "get": {
    "operationId": "listSections",
    "summary": "Catalog sections (id, name, level, url)",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api.php?action=search": {
   "get": {
    "operationId": "searchProducts",
    "summary": "Search products by name; returns price, availability and offers",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Text in product name"
     },
     {
      "name": "section",
      "in": "query",
      "schema": {
       "type": "integer"
      },
      "description": "Section id from listSections"
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 10,
       "maximum": 30
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 1
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/api.php?action=product": {
   "get": {
    "operationId": "getProduct",
    "summary": "Full product card: description, characteristics, photos, offers (colour/size) with offer_id, price, stock",
    "parameters": [
     {
      "name": "id",
      "in": "query",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/cart.php": {
   "get": {
    "operationId": "cartLink",
    "summary": "Browser link for the buyer: adds items to the visitor's cart and redirects to /basket/. Give this URL to the buyer; it must be opened in the buyer's browser, not by the agent's own HTTP client.",
    "parameters": [
     {
      "name": "items",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Comma list OFFER_ID:quantity, e.g. 150137:1,149640:2. Use offer_id (variant id) from the API; max 20 items, up to 10 pcs each."
     }
    ],
    "responses": {
     "302": {
      "description": "Redirect to /basket/"
     },
     "422": {
      "description": "Nothing added (reason in text)"
     }
    }
   }
  },
  "/api.php?action=delivery": {
   "get": {
    "operationId": "calculateDelivery",
    "summary": "Delivery methods and prices to a city for the given items (shop pickup, PEK road freight, SDEK courier / pickup point / postamat)",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "City name in Russian, e.g. Санкт-Петербург. If ambiguous, response lists candidates: repeat with location"
     },
     {
      "name": "location",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Location code from candidates"
     },
     {
      "name": "items",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "OFFER_ID:qty,OFFER_ID:qty"
     }
    ],
    "responses": {
     "200": {
      "description": "OK: methods[] with delivery_id, method, price, period, payment"
     },
     "300": {
      "description": "Ambiguous city, candidates[] with location codes"
     }
    }
   }
  },
  "/api.php?action=pickup_points": {
   "get": {
    "operationId": "listPickupPoints",
    "summary": "SDEK pickup points and postamats in a city (code, address, hours, coordinates, cash/card)",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "City name"
     },
     {
      "name": "location",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Location code"
     },
     {
      "name": "type",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "PVZ or POSTAMAT"
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "max 100, default 50"
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "page number"
     }
    ],
    "responses": {
     "200": {
      "description": "OK: points[] with code, type, address, work_time, cash, card"
     }
    }
   }
  },
  "/api.php?action=draft": {
   "get": {
    "operationId": "createOrderDraft",
    "summary": "Order draft link: items + city + delivery method (+ SDEK point). The buyer opens the link, goods land in their cart, delivery and point are preselected; the agent may pass the buyer's contacts (name, phone, email) itself, without the buyer typing them on the site, only if the buyer provided them or allowed their use (never invent or take them from other sources); they prefill the form; the buyer still gives consent, confirms the order and pays themselves",
    "parameters": [
     {
      "name": "items",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "OFFER_ID:qty,OFFER_ID:qty (offer_id from search/product)"
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "City name (or location code)"
     },
     {
      "name": "location",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Location code from action=delivery when city is ambiguous"
     },
     {
      "name": "delivery_id",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "2 shop pickup, 39 PEK, 108 SDEK courier, 109 SDEK pickup point, 110 SDEK postamat"
     },
     {
      "name": "point",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "SDEK point code from action=pickup_points (required for 109 and 110; type PVZ for 109, POSTAMAT for 110)"
     },
     {
      "name": "comment",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Note for the manager, up to 200 chars"
     },
     {
      "name": "name",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Buyer name (optional, prefills the order form)"
     },
     {
      "name": "phone",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Buyer phone, Russian number: 10 digits or 11 with 7/8 (optional, prefills the form)"
     },
     {
      "name": "email",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Buyer email (optional, prefills the form)"
     }
    ],
    "responses": {
     "200": {
      "description": "OK: draft_url (valid 24 h) to hand to the buyer"
     },
     "400": {
      "description": "bad_request / bad_point / bad_contact / unknown city"
     },
     "422": {
      "description": "item_unavailable"
     },
     "429": {
      "description": "rate_limit (30 per hour per IP)"
     }
    }
   }
  }
 }
}