Каталогду синхрондоштуруу (API)

Эгер товарларыңыз, баалар жана калдыктар эсепке алуу тутумунда — 1С, CRM, кампа программасында же Google-таблицада — жашаса, аларды билим базасына кол менен киргизүүнүн кереги жок. Платформа каталогду API аркылуу кабыл алат: сиздин тутумуңуз маалыматты жөнөтөт, ал эми ИИ-кызматкер кардарларга дароо актуалдуу позициялар боюнча жооп берет — «бар», «2 даана калды», «баасы 95 000 сом», «бөлүп төлөө бар».

Бул качан керек

• Каталог чоң жана/же тез-тез өзгөрөт (баалар, калдыктар).
• Маалымат 1С же башка тутумда бар — жана сиз ал автоматтык түрдө жаңырышын каалайсыз.
• ИИ адашпашы керек: товар түгөнсө — бот чынын айтат «жок».

Каталогго эмне кирет, Бизнес-профилге эмне кирет

Каталог (ушул API) — бул ар бир позиция боюнча фактылар: кандай товар, кайда, канча, бар же жок, бөлүп төлөөгө/кредитке болобу.

Шарттар жана эрежелер — Бизнес-профилде: жеткирүү кантип иштейт, бөлүп төлөө жана кредит кандай шарттарда (банктар, мөөнөттөр), чекиттердин даректери жана иш убактысы, кайтарып берүү, кепилдик.

Эреже: каталог «бар / жок / канча / кайда / канча турат + белгилер» деген суроого жооп берет, профиль — «бул кантип иштейт» дегенге. Чекиттин дареги ар бир товарда кайталанбайт: товар чекиттин кодун (store_code) алып жүрөт, дарек болсо профилден коюлат.

1-кадам. API-ачкычты алыңыз

Кабинетте → Жөндөөлөр → API-токендер ачкыч түзүңүз. Ал бир жолу гана көрсөтүлөт — сактап коюңуз. biz_... түрүндөгү ачкыч сиздин уюмуңузга байланган: маалымат сиздин каталогуңузга гана жазылат, бөтөнү жеткиликсиз.

Ачкыч ар бир суроодо аталышта берилет:

Authorization: Bearer biz_сиздин_ачкыч

2-кадам. Товарларды жөнөтүңүз

POST https://ai.atlabyte.com/api/v1/sync/items

Суроонун денеси (JSON):

{
  "source": "1c",
  "mode": "upsert",
  "items": [
    {
      "external_id": "store7:P1",
      "title": "iPhone 15 128GB",
      "category": "Смартфондор",
      "price": 95000,
      "currency": "KGS",
      "available": true,
      "stock": 3,
      "store_code": "ГУМ",
      "installment": true,
      "credit": true,
      "attributes": { "түсү": "кара", "эси": "128GB" },
      "url": "https://shop.example/p1",
      "image_url": "https://shop.example/p1.jpg"
    }
  ]
}

curl мисалы:

curl -X POST https://ai.atlabyte.com/api/v1/sync/items \
  -H "Authorization: Bearer biz_сиздин_ачкыч" \
  -H "Content-Type: application/json" \
  -d @catalog.json

Товардын талаалары

Талаа	Милдет.	Сүрөттөмө
external_id	ооба	Сиздин тутумуңуздагы товардын туруктуу идентификатору. Жаңыртуу ушул боюнча жүрөт — бир эле позиция үчүн аны өзгөртпөңүз.
title	ооба	Товардын аталышы (өз тилиңизде — так ушул кардарга жетет).
category	-	Категория («Смартфондор», «Кир жуугуч машиналар»).
price	-	Баасы (сан).
currency	-	Валюта, мис. KGS, USD.
available	-	Бар-жогу, true/false. Жөнөтпөсөңүз — stock боюнча эсептейбиз.
stock	-	Калдык (сан). Ал сакталат жана сизге ар дайым көрүнөт. Кардарга так санды агент «Калдыктын так санын кардарга айтуу» белгиси күйгүзүлгөндө гана атайт (Билим базасы бөлүмүндө; демейде өчүк — агент «бар / жок» деп гана айтат).
store_code	-	Чекиттин/кампанын коду. Дарек Бизнес-профилден коюлат.
installment	-	Товарга бөлүп төлөө барбы (true/false). Шарттары — профилде.
credit	-	Товарга кредит барбы (true/false). Шарттары — профилде.
attributes	-	Каалаган «ачкыч-маани» мүнөздөмөлөрү: { "түсү": "кара", "эси": "128GB" }. Кайсы тармакка болбосун ылайыктуу.
url, image_url	-	Товарга жана сүрөткө шилтеме.

source — булак-тутумдун белгиси ("1c", "crm", "sheets"…). Бул топтоо үчүн жөнөкөй тег: API 1С менен байланган эмес, ушул форматта JSON жөнөткөн каалаган тутум ылайыктуу.

Режимдер (mode)

• upsert (демейки) — жаңы позицияларды кошуу жана бар болгондорун external_id боюнча жаңыртуу. Товар бул жөнөтүүдө болбогону үчүн гана эч нерсе өчүрүлбөйт — маалымат кокустан жоголбойт.
• delete — саналган позицияларды өчүрүү (алардын external_id гана керек).

Товар түгөндүбү? Эң жакшысы — аны available: false менен кайра жөнөтүү (позиция калат, бот «жок» деп айтып, альтернатива сунуштайт). delete — сатуудан биротоло алып салуу үчүн.

Түз 1С'тен жөнөтүү (орусча талаалар)

Эгер жүктөө түз 1С'тен жүрсө, талааларды англис схемасына которуунун кереги жок — 1С'тин өз форматында өзүнчө кабыл алуу бар:

POST https://ai.atlabyte.com/api/v1/sync/1c

Дене — стандарттуу 1С дампы {Точки, Товары, Остатки}:

{
  "Точки": [
    { "Код": 7, "Наименование": "МТ ЦЕНТР" }
  ],
  "Товары": [
    {
      "Код": "P1",
      "Наименование": "iPhone 15 128GB",
      "Цена": 95000,
      "ГруппаТоваров": "Смартфоны",
      "Рассрочка": true,
      "Кредит": true
    }
  ],
  "Остатки": [
    { "КодТочки": 7, "КодТовара": "P1", "Остаток": 3 }
  ]
}

• Товардын идентификатору КодТочки:КодТовара катары түзүлөт — ар башка чекиттеги товар өзүнчө эсепке алынат.
• Остаток → бар-жогу (> 0 = бар) жана саны.
• Наименование точки чекиттин коду катары колдонулат; дарек Бизнес-профилден коюлат.
• Рассрочка / Кредит — товарга жеткиликтүүлүк белгилери (шарттары — профилде).
• Авторизация жана режим ошол эле: Authorization: Bearer biz_… аталышы, external_id боюнча жаңыртуу, жоктору өчүрүлбөйт (түгөнгөн товарды Остаток: 0 менен жөнөтүңүз).

Платформанын ичинде эки формат тең бир схемага жана бир иштеткичке келет — интеграторлор үчүн англисче, жүктөөгө ыңгайлуу болсун деп 1С'тин орусча кабыл алуусу.

3-кадам. Каталогго эмне түшкөнүн текшериңиз

GET https://ai.atlabyte.com/api/v1/items

Сиздин позицияларыңызды чыпкалар жана беттөө менен кайтарат — синхрондоштуруу өткөнүнө ынануу же чекит/модель боюнча салыштыруу үчүн ыңгайлуу.

curl "https://ai.atlabyte.com/api/v1/items?store_code=ГУМ&available=true&q=iPhone&limit=50" \
  -H "Authorization: Bearer biz_сиздин_ачкыч"

Жеткиликтүү чыпкалар: source, store_code, category, available, installment, credit, q (аталыш боюнча издөө), price_min, price_max, limit (200гө чейин), cursor (кийинки бет үчүн).

Канчалык тез-тез жөнөтүү керек

Графиги боюнча жөнөтүңүз (мисалы, саатына бир жолу же 1С'те өзгөрүүлөрдөн кийин) же калдыктар жаңырган сайын. Кайра жөнөтүү коопсуз жана арзан: платформа эмне чын эле өзгөргөнүн өзү аныктайт жана өзгөргөн позицияларды гана кайра үйрөнөт — бүт каталогду саат сайын жөнөтсө да ашыкча жүк болбойт. Бир суроодо — 5000ге чейин позиция; чоң каталогду бөлүктөргө бөлүңүз.

Кардар эмне көрөт

Синхрондоштуруудан кийин ИИ-кызматкер так сиздин маалыматыңыз боюнча жооп берет: бар экенин ырастайт, баасын айтат, бөлүп төлөө/кредит жөнүндө айтат, чекиттер боюнча багыт берет. Каталогдо позиция жок болсо — ойлоп чыгарбайт, чынын айтып, альтернатива сунуштайт же операторго өткөрөт.