Միացրեք ձեր խանութը Hosqi-ին

Ձեր խանութում պատրաստում եք փոքր, միայն կարդալու համար API։ Hosqi-ն այն կարդում է ժամանակացույցով, պահում է կատալոգը և հաճախորդներին պատասխանում է Instagram-ում, Messenger-ում, WhatsApp-ում ու Telegram-ում՝ ձեր իրական ապրանքներով, գներով և առկայությամբ։ Տվյալի միակ աղբյուրը մնում է ձեր խանութը։

Ով ինչ է անում

Խանութի բիզնես տրամաբանությունը մի փոխեք։ Դուք ուղարկում եք դրա արդյունքը, և Hosqi-ն ասում է հենց դա։

1. Տերը. Hosqi-ում՝ Միացումներ → Միացված հավելվածներ → Ավելացնել խանութ։ Գրում է անունը և API-ի ապագա հասցեն, սեղմում է Ստեղծել բանալի, պատճենում է բանալին և սեղմում Ավելացնել։ API-ն դեռ պարտադիր չէ պատրաստ լինի. այս քայլում Hosqi-ն նրան չի դիմում։
2. Տերը. Ծրագրավորողին տալիս է բանալին և Դոմենի կոդը, որը խանութի էջում է՝ Կարգավորումներ → Ծրագրավորողի համար։ Անվտանգ ճանապարհով, ոչ սովորական չատով։
3. Ծրագրավորողը. Պատրաստում է route-երը, բանալին և կոդը պահում է սերվերի կարգավորումներում, ոչ թե կոդում։ Արդյունքը ստուգում է ստուգիչով։
4. Ծրագրավորողը. Տեղադրում է production-ում, ստուգիչն աշխատեցնում է production հասցեով և կատարում է 12-րդ բաժնի ձեռքով ստուգումները։
5. Տերը. Սեղմում է Ստուգել կապը, հետո Ներմուծել և ինդեքսավորել։ 8,000 ապրանքով խանութի դեպքում դա տևեց մոտ հինգ րոպե։
6. Տերը. Սեղմում է Թույլատրել AI-ը, հետո Սկսել AI թեստը։ Այս խանութից վաճառող ընթացքը կարելի է հրապարակել թեստն անցնելուց հետո։

API՞, թե՞ ֆայլ։

Contract-ի տարբերակը 1.1 է։ 1.0-ի համեմատ այն ավելացնում է միայն այլ արժույթներով գները (բաժին 7), ուստի 1.0-ի համար գրված տվյալները մնում են վավեր։ Contract-ն ունի երեք մաս.

1. Սկսել հինգ րոպեում

Հրամաններն աշխատեցրեք այս փաթեթի թղթապանակից։ Աշխատեցրեք փորձնական խանութը, հետո ստուգիչը։ Պետք է Python 3.11 կամ նոր տարբերակ։

python sample-api/server.py

pip install "jsonschema>=4.26,<5"

python validator/commerce_contract.py --api http://127.0.0.1:8787 --allow-local --bearer sample-key --all

Փորձնական խանութը sample-api/server.py ֆայլն է։ Այն օգտագործում է միայն ստանդարտ գրադարանը, որպեսզի հեշտ կարդացվի որպես օրինակ։ Նրա 26 գրառումը sample-api/catalog.json-ում է։

Այն դիտավորյալ ցույց է տալիս locale_incomplete զգուշացումներ, որովհետև օրինակները կրճատ են, և մեծ մասը միայն անգլերեն տեքստ ունի։ CARPET-CUT-ը ցույց է տալիս endpoint_required, որովհետև փորձնական խանութը /quote չունի, և այդ ապրանքը փոխանցվում է մարդուն։

Հետո ստուգիչը ուղղեք ձեր API-ին.

python validator/commerce_contract.py --api https://shop.example/hosqi/v1 --bearer YOUR_KEY --all

Առանց --all-ի այն աշխատում է Hosqi-ի Ստուգել կապը կոճակի պես. կարդում է manifest-ը, խանութի գրառումները և ապրանքների երկու էջ, և կանգնում է առաջին ձախողված պատասխանի վրա։ --all-ով կարդում է ամբողջը, ինչպես համաժամեցումը, բաժին 10-ի սպասումներով ու կրկնություններով, ստուգում է նաև քանակները, հղումները և հաշվում է մակարդակը։ Երկուսն էլ պահում են max_rps-ը։ Ամբողջ հաշվետվության համար ավելացրեք --json, իսկ սեփականության ապացույցը ստուգելու համար՝ --token, Hosqi-ի ցույց տված կոդով։

Ստուգիչը մեկ ֆայլ և մեկ թղթապանակ է։ commerce_contract.py-ը պահեք commerce_schemas/-ի կողքին։

Փորձարկում ձեր համակարգչում։ --allow-local-⁠ը թույլ է տալիս ստուգիչին կարդալ http:// հասցե ձեր համակարգչում։ Hosqi-⁠ն ինքը երբեք դա չի անում. նրան պետք է HTTPS հրապարակային հասցեով։ Տեղական հասցեի դեպքում 9-⁠րդ բաժնի դոմենի ապացույցը չի կարող անցնել, այդ պատճառով --token-⁠ը ցույց է տալիս ownership_missing, և դա սպասելի է։ Ապրանքների հասցեները միևնույն է պետք է լինեն store.base_url-⁠ի դոմենում, ուստի փորձարկման ժամանակ տվյալներում օգտագործեք խանութի իրական դոմենը։

2. Ինչ պատրաստել

Խանութը Hosqi-ին տալիս է հիմնական հասցե, օրինակ՝ https://shop.example/hosqi/v1։

Կանոններ բոլոր route-երի համար.

• HTTPS, 443 պորտ, TLS 1.2 կամ նոր, հանրային հասցե։
• Ուղարկեք Content-Type: application/json։ Hosqi-ն ուղարկում է Accept-Encoding: gzip։
• Hosqi-ն redirect-ին չի հետևում։ Տվեք վերջնական հասցեն։
• Բոլոր route-երը միայն կարդում են, և դրանք կրկնելը անվտանգ է։
• Hosqi-ն կանչում է Hosqi-Catalog/1.0 անունով, մեկ հարցում միաժամանակ, max_rps-ի սահմանում (նախնական արժեքը 2)։ Firewall-ը կամ բոտերի ստուգումը պետք է այն թողնեն։ Մեկ էջի համար սպասում է մինչև 30 վայրկյան, և կարդալը կանգնում է 30 րոպեից հետո։

3. Նույնականացում

Hosqi-ն բանալին պահում է կնքված և այլևս ցույց չի տալիս։ Խանութը կարող է այն փոխել ցանկացած պահի։

4. GET /manifest

Hosqi-ն սա կարդում է առաջինը՝ ամեն անգամ։

{
  "hcf": "1.1",
  "kind": "catalog_api",
  "store_name": "Example Shop",
  "generated_at": "2026-11-05T09:00:00+04:00",
  "data_modified_at": "2026-11-05T08:40:00+04:00",
  "counts": {"store": 1, "location": 1, "delivery_profile": 1, "policy": 2, "product": 1240},
  "variant_count": 5310,
  "capabilities": {"page_size_max": 200, "delta": true, "tombstones": true, "offers": true, "max_rps": 5},
  "verification": "hq-verify-7f2a91c0"
}

Խորհուրդ է տրվում տալ ETag։ Հիմնեք այն տվյալի, ոչ պատասխանի վրա, որովհետև generated_at-ը ամեն կանչի հետ փոխվում է։ Hosqi-ն ուղարկում է If-None-Match, և 304-ը նշանակում է, որ ոչինչ չի փոխվել։

5. GET /records

GET /records?limit=200&cursor=c2tpcD0yMDA&types=product

{
  "hcf": "1.1",
  "generated_at": "2026-11-05T09:00:03+04:00",
  "mode": "full",
  "records": [
    {
      "type": "product", "id": "MUG-350-BLUE", "version": 31,
      "updated_at": "2026-11-05T08:40:00+04:00",
      "kind": "simple", "status": "active", "visibility": "public",
      "i18n": {"hy": {"title": "Կապույտ բաժակ, 350 մլ", "url": "https://shop.example/hy/p/mug-350-blue"}},
      "variants": [
        {
          "id": "MUG-350-BLUE", "sku": "MUG-350-BLUE",
          "pricing": {"mode": "fixed", "price": {"amount": "4500", "currency": "AMD"}},
          "availability": {"state": "in_stock"}
        }
      ]
    }
  ],
  "next_cursor": "c2tpcD0yMDA"
}

Էջերի կանոններ.

• Վերջին էջում next_cursor-ը null է։ Դատարկ էջը cursor-ով թույլատրելի է։
• Cursor-ի պարունակությունը Hosqi-ի համար նշանակություն չունի, բայց այն պետք է գործի առնվազն 60 րոպե։ Ժամկետանց cursor-ը վերադարձնում է 410, և Hosqi-ն մեկ անգամ նորից է սկսում։
• Հերթականությունը պետք է կայուն լինի, որպեսզի էջերը գրառում բաց չթողնեն և չկրկնեն. ամբողջական կարդալիս՝ ըստ id-ի, delta կարդալիս՝ ըստ updated_at-ի, հետո id-ի։ Կարելի է նախ դասավորել ըստ տեսակի։
• Գրառումների տեսակների հերթականությունը կարևոր չէ։ Hosqi-ն հղումները ստուգում է կարդալու վերջում։
• Էջը առավելագույնը 10 ՄԲ է՝ առանց սեղմման։ Գրառումը՝ 1 ՄԲ։ Ապրանքը՝ 2,500 variant տող։
• ID-ն կարող է երևալ երկու էջում, եթե կարդալու ընթացքում փոխվել է, և version-ը որոշում է։ Մեկ էջում երկու անգամ չի կարող լինել։

6. Փոփոխություններ և ջնջումներ

Ամբողջական կարդալ։ Առանց updated_since-ի։ Hosqi-ն կարդում է մինչև վերջին էջը և ընդհանուր քանակը համեմատում է counts-ի հետ։ Տարբերությունը կարող է լինել մինչև 1% կամ 5 գրառում, որովհետև կատալոգը կարող է փոխվել կարդալու ընթացքում։ Ավարտված ամբողջական կարդալուց բացակայող ապրանքը հանվում է, բայց պաշտպանությամբ. եթե պետք է հանվեն ակտիվ ապրանքների 20%-ից ավելին, կամ արդյունքը դատարկ է, Hosqi-ն ոչինչ չի կիրառում և հարցնում է խանութին։

Delta կարդալ։ Hosqi-ն ուղարկում է updated_since՝ վերջին հաջող կարդալու generated_at-ից 10 րոպե առաջ։ Վերադարձրեք այդ պահից փոխված բոլոր գրառումները՝ mode: "delta"-ով։ Այս համընկնման պատճառով գրառումը կարող է երկու անգամ գալ, և version-ը դա անվնաս է դարձնում։

version-ը ամբողջ թիվ է, որը յուրաքանչյուր գրառման համար միայն աճում է։ Կարելի է օգտագործել updated_at-ի epoch-ը։ Hosqi-ն գրառումը կիրառում է միայն այն դեպքում, երբ version-ը պահվածից մեծ է։ Բարձրացրեք այն ամեն փոփոխության ժամանակ։ Եթե գինը փոխեք, իսկ version-ը թողնեք նույնը, Hosqi-ն գրառումը բաց կթողնի։ Սա վերաբերում է նաև tombstone-ին. նրա version-ը պետք է մեծ լինի ջնջվող գրառման վերջին version-ից, այլապես Hosqi-ն այն բաց կթողնի և կշարունակի վաճառել։

Ջնջված ID-ն վերադարձնելու համար ուղարկեք գրառումը ավելի բարձր version-ով և restore: true-ով։

Ջնջումներ.

{"type": "tombstone", "id": "MUG-350-BLUE", "target": "product", "version": 32,
 "updated_at": "2026-11-05T10:00:00+04:00", "deleted_at": "2026-11-05T10:00:00+04:00", "reason": "discontinued"}

Որքան հաճախ է Hosqi-ն կարդում.

Ping (ոչ պարտադիր)

Hosqi-⁠ն ձեր API-⁠ն կարդում է իր ժամանակացույցով։ Որպեսզի փոփոխությունը կարդացվի մոտ մեկ րոպեում, փոփոխության պահին կանչեք այս հասցեն.

curl -X POST "https://app.hosqi.io/api/platform/catalog/v1/sources/SOURCE_ID/ping" \
  -H "Authorization: Bearer YOUR_PING_KEY"

Հասցեն և բանալին Hosqi-⁠ի աղբյուրի էջում են՝ «Ծրագրավորողի համար» բաժնում։ Բանալին ցույց է տրվում մեկ անգամ։ Հարցման մարմինը չի կարդացվում, և ping-⁠ը տվյալ չի բերում. Hosqi-⁠ն փոփոխությունը միևնույն է կարդում է ձեր API-⁠ից՝ միայն փոխվածը, եթե updated_since-⁠ը աշխատում է, և ամբողջը, եթե չի աշխատում։

7. Գրառումներ

Ամեն գրառում ունի type, id, version, իսկ այս API-ում նաև updated_at։ Գրառումների schema-ներում updated_at-ը պարտադիր չէ, որովհետև դրանք օգտագործվում են նաև ֆայլերի համար, իսկ records-page-ը այն պահանջում է։ Դաշտերի ամբողջ ցանկը յուրաքանչյուր տեսակի schema-ն է։

Արժեքների կանոններ.

• Տեքստը UTF-8 է և պարզ։ Hosqi-ն HTML-ը հանում է։ Գրառումը առավելագույնը 32 մակարդակ խորություն ունի։
• Գումարը տասնորդական տող է և ISO 4217 կոդ, երբեք թիվ՝ {"amount": "4500", "currency": "AMD"}։ Տասնորդականը առավելագույնը 24 նիշ է։
• Ժամանակը RFC 3339 է՝ offset-ով։ Տեղական ժամերը HH:MM են և օգտագործում են նույն գրառման կամ խանութի IANA գոտին։
• Մի քանի լեզվով տեքստը i18n-ում է՝ BCP 47 կոդերով, օրինակ՝ hy, ru, en։
• ID-ները ձերն են, եզակի յուրաքանչյուր տեսակի մեջ, կայուն, և այլ ապրանքի համար չեն կրկնվում։ ID-ի մեջ գին կամ պաշար մի դրեք։
• Անհայտ դաշտերը անտեսվում են։ Ձեր սեփական տվյալը դրեք x_<vendor>-ի տակ, և AI-ը այն չի տեսնի։
• Դատարկ audience: {}-ը նշանակում է բոլորը։
• Մի ուղարկեք ինքնարժեք, մատակարարի տվյալ կամ հաճախորդի անձնական տվյալ։

store

{
  "type": "store", "id": "store", "version": 8, "updated_at": "2026-11-05T08:00:00+04:00",
  "name": "Example Shop", "base_url": "https://shop.example", "status": "open", "timezone": "Asia/Yerevan",
  "default_locale": "hy", "locales": ["hy", "ru", "en"],
  "declared_complete": ["price_list", "promotion", "addons", "delivery_profile", "policy"],
  "markets": [
    {"id": "am", "countries": ["AM"], "currency": "AMD", "decimals": 0, "rounding": {"mode": "half_up"}, "tax": {"included": true}}
  ],
  "price_currencies": [{"currency": "USD"}, {"currency": "RUB", "decimals": 0}],
  "checkout": {"url_template": "https://shop.example/cart/add{?variant,qty}", "carries": ["variant", "qty"]}
}

• markets[].currency-ն այն արժույթն է, որով հաճախորդը վճարում է։ Hosqi-ն արժույթ չի փոխարկում։ Variant-ի գները base_market-ի արժույթով են, և այն պարտադիր է մի քանի շուկայի դեպքում։ Այլ շուկայի գինը գալիս է price_list-ից։
• price_currencies-ը (1.1-ից) այն այլ արժույթներն են, որոնցով ընդունում եք վճարում և որոնցով ինքներդ եք գին դնում։ Տես ստորև՝ Գներ այլ արժույթներով։
• declared_complete-ը նշում է, թե ձեր տվյալում ինչն է ամբողջական, այդ թվում՝ ինչ չունեք։ Եթե նշել եք promotion, բայց promotion գրառում չկա, նշանակում է՝ խանութը ակցիա չունի։
• Ապրանքի, policy-ի և checkout-ի հասցեները պետք է լինեն ձեր domain-ում կամ checkout.allowed_hosts-ում։ Նկարների հասցեները կարող են լինել ցանկացած հանրային HTTPS host-ում։
• store.endpoints-ը կենդանի հաշվարկի համար է (/quote, /availability), որը գալու է ավելի ուշ։ Առայժմ մի նշեք։ Այդ դեպքում live ապրանքը փոխանցվում է մարդուն՝ endpoint_required զգուշացմամբ։

product

5-⁠րդ բաժնի ապրանքը ամենափոքր վավեր օրինակն է. type, id, version, kind, status, visibility, i18n՝ title և url դաշտերով, և variants։ Ամեն ID կարող է լինել մինչև 255 նիշ տեքստ։

Ամեն ապրանք ունի առնվազն մեկ variant, նույնիսկ պարզ ապրանքը։ AI-ին հասնելու համար status-ը պետք է active լինի։ visibility=members-ի համար պետք է audience։

Ամեն լեզվի համար i18n-⁠ում ուղարկեք short_description և description։ Hosqi-⁠ն պահում է երկուսն էլ, և AI որոնումը կարդում է դրանք, ուստի հաճախորդը կարող է գտնել ապրանքը նաև նրանով, թե ինչի համար է, ոչ միայն անունով։ short_description-⁠ը մեկ-երկու նախադասություն է և առաջինն է կարդացվում, իսկ շատ երկար description-⁠ը կտրվում է վերջից։ Լավագույնը պարզ տեքստն է, HTML-⁠ը հանվում է։

availability.state-ը կարող է լինել in_stock, out_of_stock, preorder (պետք է available_from), backorder և made_to_order (պետք է lead_time), discontinued, unknown։ qty-ն պետք է լինի վաճառելի քանակը։ qty_disclosure-ը hidden է, եթե չնշեք exact կամ band։

pricing.mode.

Ընտրանքներ և variant-ներ

Մեկից ավելի variant ունեցող ապրանքին պետք են options և combinations։

{
  "type": "product", "id": "BOOK14", "version": 5, "updated_at": "2026-11-05T08:00:00+04:00",
  "kind": "variable", "status": "active", "visibility": "public",
  "i18n": {"en": {"title": "Book 14", "url": "https://shop.example/p/book14"}},
  "options": [
    {"id": "chip", "label": {"en": "Chip"}, "values": [{"id": "base", "label": {"en": "Base"}}, {"id": "pro", "label": {"en": "Pro"}}]},
    {"id": "ram", "label": {"en": "Memory"}, "values": [{"id": "16", "label": {"en": "16 GB"}}, {"id": "48", "label": {"en": "48 GB"}}]}
  ],
  "combinations": {
    "mode": "rules", "closed": true,
    "rules": [{"id": "r1", "when": {"chip": ["base"]}, "require": {"ram": ["16"]}, "why": {"en": "The base chip takes 16 GB only."}}]
  },
  "variants": [
    {"id": "BOOK14-BASE-16", "options": {"chip": "base", "ram": "16"}, "pricing": {"mode": "fixed", "price": {"amount": "759000", "currency": "AMD"}}, "availability": {"state": "in_stock"}},
    {"id": "BOOK14-PRO-16", "options": {"chip": "pro", "ram": "16"}, "pricing": {"mode": "fixed", "price": {"amount": "899000", "currency": "AMD"}}, "availability": {"state": "in_stock"}},
    {"id": "BOOK14-PRO-48", "options": {"chip": "pro", "ram": "48"}, "pricing": {"mode": "fixed", "price": {"amount": "1099000", "currency": "AMD"}}, "availability": {"state": "in_stock"}}
  ]
}

closed-ը պարտադիր է։ true նշանակում է, որ այն, ինչ թույլատրված չէ, գոյություն չունի, և AI-ը կարող է մերժել։ false նշանակում է, որ տվյալը կարող է թերի լինել, և AI-ը կասի, որ պետք է ստուգի։

Կանոնն ունի when (ընտրանքներ և արժեքներ. ընտրանքների միջև՝ ԵՎ, ցանկի ներսում՝ ԿԱՄ), հետո require-ից և forbid-ից առնվազն մեկը, և ոչ պարտադիր why, որ AI-ը կարող է կրկնել։ Variant-ում * արժեքը համապատասխանում է այդ ընտրանքի ցանկացած արժեքի։

all և rules ռեժիմներում յուրաքանչյուր թույլատրելի համակցության պետք է գին. սեփական տող, * տող, կամ rules-ում՝ default_variant։ Այլապես ստուգիչը տալիս է combination_uncovered։

delivery_profile, policy, location

{
  "type": "delivery_profile", "id": "dp", "version": 3, "updated_at": "2026-11-05T08:00:00+04:00",
  "timezone": "Asia/Yerevan",
  "methods": [
    {"id": "city", "type": "delivery", "zones": [{"country": "AM", "region": "Yerevan"}],
     "price": {"amount": "1000", "currency": "AMD"},
     "free_over": {"amount": "30000", "currency": "AMD"}, "free_over_basis": "subtotal_before_discounts",
     "same_day": true, "cutoff": {"time": "16:00"}},
    {"id": "pickup", "type": "pickup", "location_ids": ["main"], "price": {"amount": "0", "currency": "AMD"}}
  ]
}

Յուրաքանչյուր եղանակ ունի zones կամ location_ids, և ճիշտ մեկը՝ price, price_bands, quote_required։

{
  "type": "policy", "id": "returns", "version": 2, "updated_at": "2026-11-05T08:00:00+04:00",
  "policy_type": "returns", "approved_at": "2026-11-01T10:00:00+04:00",
  "i18n": {"en": {"summary": "Unused items can be returned within 14 days."}},
  "returns": {"accepted": true, "window_days": 14, "who_pays": "customer"}
}

i18n.summary-ն այն տեքստն է, որ AI-ը կարող է կրկնել։ approved_at-ը ցույց է տալիս, երբ է խանութը այն հաստատել։

{
  "type": "location", "id": "main", "version": 1, "updated_at": "2026-11-05T08:00:00+04:00",
  "name": "Main shop", "address": "1 Example Street, Yerevan", "kinds": ["pickup", "shop"],
  "hours": [{"days": ["mon", "tue", "wed", "thu", "fri", "sat"], "from": "10:00", "to": "20:00"}]
}

availability-ն առանց location_id-ի ձեր պատասխանն է ամբողջ խանութի համար, որքան էլ վայր ունենաք։ Hosqi-ն այն չի գումարում և նորից չի հաշվում, ուստի ուղարկեք այն, ինչ ձեր կայքը կասեր հաճախորդին։

Branches, pickup and units

Պահեք ձեր բիզնես տրամաբանությունը։ Ուղարկեք դրա արդյունքը, և Hosqi-ն կասի հենց դա։

Պաշար ըստ branch-ի։ availability.state-ը մնում է ձեր ընդհանուր պատասխանը։ availability.locations-ը ցույց է տալիս, թե որտեղ է ապրանքը, ապրանքի գրառման և /offers-ի մեջ։ Այս ապրանքը ցույց է տալիս այս բաժնի բոլոր երեք բաները.

{
  "type": "product", "id": "PIPE-12", "version": 1762470000123, "updated_at": "2026-11-05T08:00:00+04:00",
  "kind": "simple", "status": "active", "visibility": "public", "delivery_profile_id": "pickup-only",
  "i18n": {"en": {"title": "Copper pipe", "url": "https://shop.example/p/pipe-12"}},
  "variants": [{
    "id": "PIPE-12", "pricing": {"mode": "fixed", "price": {"amount": "3200", "currency": "AMD"}},
    "sale_unit": {"unit": "ft", "display": "per ft", "step": "10", "min": "10"},
    "availability": {"state": "in_stock", "locations": [
      {"location_id": "main", "state": "in_stock"},
      {"location_id": "east", "state": "out_of_stock"}
    ]}
  }]
}

• Յուրաքանչյուր տողի պետք է location_id և state։ qty, qty_disclosure, lead_time, available_from և as_of դաշտերը պարտադիր չեն։
• locations-ով ուղարկված ապրանքը փոխարինում է Hosqi-ի պահած branch-երը, ուստի ուղարկեք բոլորը, նաև զրոյական պաշարով։
• inventory գրառումները location_id-ով մյուս ճանապարհն են։ Այդ դեպքում ամեն branch ունի իր version-ը, և ընդհանուր վիճակը փոխում է միայն ապրանքից նոր գրառումը։ Եթե ապրանքի version-ն արդեն հետևում է պաշարին, օգտագործեք locations-ը։

Միայն վերցվող ապրանքներ։ Ապրանքը, որի delivery_profile_id-ն ցույց է տալիս միայն pickup եղանակներով profile, երբեք չի առաջարկվում առաքմամբ։ Պատասխանը նշում է եղանակի location_ids-ի այն branch-երը, որտեղ ապրանքը կա, օրինակ՝ pickup only: East, Main։ pickup_place_missing զգուշացումը նշանակում է՝ ապրանքը առկա է, բայց այդ եղանակի ոչ մի branch-ում չկա։

Չափման միավոր։ Առանց լրացման գինը կարդացվում է որպես մեկ հատի գին։ Չափով վաճառվող ապրանքի variant-ին ավելացրեք sale_unit, ինչպես վերևում է, իսկ վերնագիրը թողեք այնպես, ինչպես ձեր կայքում է։

• unit-ը կոդ է։ ft, m, yd, kg, lb, l և m2 կոդերը պատասխաններում թարգմանվում են, իսկ piece, pc, pcs, each, ea, item և unit կոդերը չեն երևում։
• display-ը ձեր բառերն են՝ ձեր հիմնական լեզվի և մնացած կոդերի համար։
• step-ը և min-ը ցույց են տալիս, թե ինչ քանակ կարելի է պատվիրել։ qty-ն պետք է լինի գնի նույն միավորով, կամ մի՛ ուղարկեք այն։

Առանց հրապարակային գնի։ on_request, live կամ disclosure: "verified_only" դեպքում պատասխանն ասում է price on request, իսկ այդ գինը փնտրող հաճախորդը գնում է մարդու մոտ։

Գներ այլ արժույթներով

Որոշ խանութներ վաճառում են մեկ երկրում, բայց ընդունում են մի քանի արժույթ և ամեն արժույթով իրենք են գին դնում։ 1.1 տարբերակում այդ գները գալիս են հիմնական գնի կողքին.

{
  "type": "product", "id": "PHONE-6", "version": 4, "updated_at": "2026-11-09T08:00:00+04:00",
  "kind": "simple", "status": "active", "visibility": "public",
  "i18n": {"en": {"title": "Northline Phone 6, 128 GB", "url": "https://shop.example/p/phone-6"}},
  "variants": [{
    "id": "PHONE-6", "availability": {"state": "in_stock"},
    "pricing": {
      "mode": "fixed",
      "price": {"amount": "189000", "currency": "AMD"},
      "currency_prices": {
        "USD": {"price": {"amount": "489", "currency": "USD"}},
        "RUB": {"price": {"amount": "39900", "currency": "RUB"},
                "sale": {"price": {"amount": "37900", "currency": "RUB"}, "valid_to": "2026-11-30T20:00:00Z"}}
      }
    }
  }]
}

• Արժույթները մեկ անգամ նշեք store.price_currencies-ում՝ ձեր նախընտրած հերթականությամբ, ինչպես վերևի store-ում է։ Նշեք միայն այն արժույթները, որոնցով ընդունում եք վճարում, առավելագույնը 10, և երբեք՝ շուկայի արժույթը։
• currency_prices-ում ամեն նշված արժույթի համար տվեք price, իսկ ցանկության դեպքում նաև sale և compare_at, բոլորը՝ այդ նույն արժույթով։ Մի արժույթի զեղչը մյուսների վրա չի ազդում։
• Հիմնական price-ը մնում է շուկայի արժույթով և պարտադիր է։ Եթե ապրանքը որևէ արժույթով գին չունի, այդ արժույթը մի՛ նշեք։ Hosqi-ն չի փոխարկում, ուստի այդ ապրանքի համար այդ արժույթը ցույց չի տրվի։
• Սա variant-ի վերջնական գինն է և աշխատում է fixed և option_sum ռեժիմներով։ Մնացած ռեժիմներում այն անտեսվում է currency_prices_ignored զգուշացմամբ։
• Եթե decimals-ը չնշեք, վերցվում է ISO 4217-ով սահմանված տասնորդական նիշերի թիվը։ basis-ը fixed է (նախնական արժեքը), երբ գինը դուք եք դրել, և shop_rate, երբ այն հաշվել է ձեր խանութի համակարգը իր փոխարժեքով։
• Թե այս գներից որոնք ցույց տա AI-ը, միանգամից քանիսը և որն առաջինը, ընտրում է խանութի տերը Hosqi-ում։
• Եթե բանալին price_currencies-ում չկա, կամ ներսում գումար կա ուրիշ արժույթով, ստուգիչը տալիս է currency_not_in_market։ Եթե price_currencies-ում արժույթը կրկնվում է կամ շուկայի արժույթն է, տալիս է price_currency_invalid։

Գնացուցակներ, ակցիաներ, հավելումներ, հավաքածուներ

Չորսն էլ կան sample-api/catalog.json-ի օրինակներում, և schema-ները տալիս են բոլոր դաշտերը։

• price_list-ի տողը քանակային գին է, երբ min_qty-ն 1-ից մեծ է։ Դրան պետք են tier_mode (all_units կամ graduated) և tier_scope (variant կամ product)։ disclosure: "verified_only"-ն թվերը հեռու է պահում չհաստատված կոնտակտներից։
• promotion-ը տալիս է այն տեքստը, որ AI-ը կարող է ասել։ Hosqi-ն զեղչ չի հաշվում։ Կուպոնին պետք է code_disclosure։
• addons-ը փոխում է պատվերը՝ առանց variant լինելու։ Յուրաքանչյուրն ունի price՝ kind-ով, իսկ carry-ն ասում է, թե ընտրությունը ինչպես է հասնում ձեր խանութին։ text, number, date և file հավելումներին պետք է validation, թեկուզ դատարկ։ carry: "link"-ին պետք է addons կամ personalisation՝ checkout.carries-ում։
• bundle ապրանքը թվարկում է components։ Հավաքածուն մեկ մակարդակ է։

8. GET /offers

Պարտադիր չէ։ Դրանով Hosqi-ն կարող է հաստատել գինը կամ պաշարը հենց պատասխանի պահին։ Առանց դրա Hosqi-ն հենվում է վերջին համաժամեցման և դրա տարիքի վրա։

GET /offers?variant_ids=MUG-350-BLUE,BOOK14-PRO-48&market=am

{
  "hcf": "1.1",
  "generated_at": "2026-11-05T12:00:00+04:00",
  "offers": [
    {"variant_id": "MUG-350-BLUE", "product_id": "MUG-350-BLUE", "status": "ok",
     "pricing": {"mode": "fixed", "price": {"amount": "4500", "currency": "AMD"}},
     "availability": {"state": "in_stock"}},
    {"variant_id": "BOOK14-PRO-48", "status": "not_found"}
  ]
}

• Մինչև 20 ID։ Ավելիին պատասխանեք 400։ market-⁠ը պարտադիր է, երբ խանութը մեկից ավելի շուկա ունի, իսկ մեկ շուկայի դեպքում Hosqi-⁠ն այն չի ուղարկում։
• ok-ի դեպքում պարտադիր են pricing և availability՝ նույն ձևով, ինչ կատալոգում։ option_sum գինը մնում է option_sum։
• pricing-ը ներառում է նաև currency_prices-ը, եթե variant-ը դրանք ունի, ուստի մեկ կանչով ստուգվում են բոլոր արժույթները։
• Պատասխանին պետք է Cache-Control: no-store։
• Պատասխանեք 2,500 մվ-ի ընթացքում։ Hosqi-ն հաճախորդի պատասխանը դրանից ավելի չի պահում։
• not_found-ը նշանակում է, որ Hosqi-ն դադարում է առաջարկել այդ variant-ը։

9. Domain-ի սեփականության ապացույց

Hosqi-ն խանութին ցույց է տալիս կոդ։ Ապացույց է ցանկացած մեկը.

• /manifest-ը կոդը վերադարձնում է verification-ում, և API-ի host-ը նույն domain-ում է, ինչ store.base_url-ը։
• DNS TXT գրառում խանութի domain-ում՝ hosqi-verification=<token> արժեքով։
• <meta name="hosqi-verification"> tag գլխավոր էջում։

Տերը կոդը գտնում է խանութի էջում՝ Կարգավորումներ → Ծրագրավորողի համար → Դոմենի կոդ։

10. Ինչպես է Hosqi-ն վարվում ձեր պատասխանների հետ

Կանգնած կարդալը երբեք չի փոխում հրապարակված կատալոգը։ Սխալը կարող եք նկարագրել application/problem+json-ով, և Hosqi-ն դրա title-ը ցույց կտա խանութին։

11. Ստուգում

Ստուգիչը նույն կոդն է, որ աշխատեցնում է Hosqi-ն։ Խստությունը որոշում է արդյունքը.

Ամեն խնդիր ունի code, severity, record_type, record_id, pointer, message և hint։ Ամենահաճախները.

Մակարդակ։ Hosqi-ն մակարդակը հաշվում է ինքը։ Այն չի հայտարարվում։

Ստուգիչի մակարդակը հաշվվում է միայն տվյալից։ Hosqi-ի կենդանի ստուգումները, օրինակ՝ հղումների և գների համեմատությունը ձեր կայքի հետ, կարող են այն իջեցնել։

Ինչ չի տեսնում ստուգիչը։ Այն փորձում է updated_since-ը հին և ընթացիկ ժամանակով, և չափում է /offers-ը, բայց չի կարող ջնջել ձեր տվյալը կամ փոխել գները։ Սրանք փորձեք ձեռքով. tombstone-ը երևում է delta կարդալիս, version-ը բարձրանում է ամեն փոփոխության ժամանակ, 304 է գալիս, երբ ոչինչ չի փոխվել, իսկ երկար կատալոգը էջ առ էջ կարդացվում է՝ առանց գրառում բաց թողնելու։

12. Միացնելուց առաջ

• /manifest-ը և /records-ը պատասխանում են HTTPS-ով, 443 պորտով, ձեր բանալիով։

• --all-ով ստուգիչը չի տալիս fatal և error։

• version-ը բարձրանում է ամեն փոփոխության ժամանակ, ամեն գրառման համար, իսկ tombstone-ինը մեծ է ջնջվող գրառումից։

• Գինը փոխելուց և ապրանքը ջնջելուց հետո delta կարդալը վերադարձնում է երկուսն էլ։

• Firewall-ը կամ բոտերի ստուգումը թողնում է Hosqi-Catalog/1.0-ը։

• Գիտեք, թե խանութը ինչպես է ապացուցելու domain-ը (բաժին 9)։

• Մեկ branch-ի պաշարի փոփոխությունը delta կարդալիս գալիս է ավելի բարձր version-ով։

• Կարգավորումներից եկող արժեքը, օրինակ՝ free_over-ը, փոխվելիս բարձրացնում է իր գրառման version-ը։

• Բանալին և դոմենի կոդը սերվերի կարգավորումներում են, ոչ թե կոդում։

Հետո հայտնեք տիրոջը։ Նա սեղմում է Ստուգել կապը, հետո Ներմուծել և ինդեքսավորել։ Եթե ինչ-որ բան մերժվի, Hosqi-ն ցույց կտա կոդը և ուղղման ցուցումը։

13. Ֆայլ՝ API-ի փոխարեն

Եթե փոքր API-ն էլ շատ է, խանութը մեկ ֆայլ է դնում հղումով, և Hosqi-ն այն կարդում է ժամանակացույցով։ Hosqi-ում ընտրեք Feed ֆայլ՝ հղումով։

• JSON Lines. UTF-8, մեկ գրառում՝ մեկ տողում, .jsonl կամ .jsonl.gz, HTTPS-ով։
• Առաջին տողը feed գրառումն է։ source_id-ն Աղբյուրի ID-ն է՝ Ծրագրավորողի համար բաժնում։
• Հաջորդ տողերը 7-րդ բաժնի գրառումներն են, նույնը, ինչ տալիս է /records-ը։
• Ամեն նոր ֆայլի հետ բարձրացրեք sequence-ը, իսկ counts-ում գրեք, թե յուրաքանչյուր տեսակից քանի գրառում է հաջորդում։
• Ուղարկեք ETag։ Hosqi-ն ուղարկում է If-None-Match, իսկ 304-ը նշանակում է, որ ոչինչ չի փոխվել։
• Դոմենն ապացուցեք DNS-ով կամ 9-րդ բաժնի meta tag-ով։

{"type": "feed", "id": "feed", "version": 1762470000123, "hcf": "1.1", "source_id": "YOUR_SOURCE_ID", "mode": "full", "generated_at": "2026-11-05T08:00:00+04:00", "sequence": 1, "counts": {"store": 1, "product": 2500}}

Ստուգեք ֆայլը նախքան հրապարակելը.

python validator/commerce_contract.py --file feed.jsonl

14. Սխալներ, որ արդեն տեսել ենք

• version-ը հետևում է միայն ապրանքների աղյուսակին։ Գնի կամ պաշարի փոփոխությունը Hosqi-ին չի հասնում։ Վերցրեք գրառումը կազմող բոլոր աղյուսակների վերջին փոփոխությունը։
• version-ը հետևում է job-ին, որը ամեն անգամ վերագրում է տողերը։ Ամեն ընթերցման ժամանակ բոլոր ապրանքները փոխված են երևում։ Հետևեք իրական փոփոխությանը, ոչ թե job-ի ժամին։
• Կարգավորումներից եկող արժեքը փոխվում է, օրինակ՝ free_over-ը, իսկ version-ը մնում է։ Hosqi-ն կիրառում է միայն ավելի բարձր version, նաև լրիվ ընթերցման ժամանակ, և պատասխանները մնում են հին կանոնով։ Բարձրացրեք այդ delivery_profile-ի, store-ի կամ location-ի version-ը։
• Ուղարկվում է միայն գլխավոր branch-ը։ Մյուս branch-երի ապրանքները երևում են որպես առկա չէ։ Ուղարկեք ընդհանուր state-ը և բոլոր branch-երը locations-ում։
• location.name-ը կրկնում է խանութի անունը։ Պատասխանը երկարում է, և branch-երը կրճատվում են երեքի և +1-ի։ Գրեք կարճ անուն, օրինակ՝ Sun Valley։
• Միավորը վերնագրում է, կամ qty-ն կտորով է, իսկ գինը՝ ֆուտով։ Պատասխանը սխալ է կարդացվում։ Վերնագիրը թողեք կայքի պես, ավելացրեք sale_unit, իսկ qty-ն ուղարկեք գնի միավորով կամ մի ուղարկեք։
• Հանրությունից թաքնված գինը ուղարկվում է fixed-ով։ Հաճախորդը տեսնում է գին, որը կայքը թաքցնում է։ Օգտագործեք on_request։
• Ապրանքի url-ը ժամանակավոր է, օրինակ՝ /product/pending-123։ Հաճախորդը ստանում է անօգուտ էջ։ Ուղարկեք ապրանքի իրական էջը։
• Login-ը, firewall-ը կամ բոտերի ստուգումը պատասխանում է Hosqi-ին։ html_received, կամ ընթերցումը կանգնում է։ Թողեք Hosqi-Catalog/1.0-ը և տվեք վերջնական հասցեն, որովհետև Hosqi-ն redirect-ին չի հետևում։