ИИ-агентке арналған нұсқаулық (қысқаша)

Толық, нақты нұсқасы ағылшын тілінде: AI agent integration guide. Машинада оқылатын контракт: /openapi.json; индекс: /llms.txt.

Пилоттық режим

Нақты төлем қабылдау әлі жоқ; барлығы офлайн, имитациямен тексеріледі. Жария API мекенжайы анықталмаған — ол тек баптау мәні (ELEVENPAY_BASE_URL).

Қатаң шектеулер

1. Сайттың бар тірі төлем интеграциясын иесінің нақты рұқсатынсыз өзгертпеңіз; жаңа жолды әдепкіде өшірулі жалаумен қосыңыз.
2. Құпияларды (.env, кілттер, парольдер) оқымаңыз, басып шығармаңыз, коммит жасамаңыз.
3. Әзірлеу кезінде тірі төлем API-ін шақырмаңыз; тек офлайн жинақтар мен имитацияларды қолданыңыз.
4. Репозиторий жолдарын, мекенжайларды, тенант/заңды тұлға сәйкестігін болжамаңыз: белгісізді UNKNOWN деп белгілеңіз.
5. Деректер қорының миграциясы — бөлек рұқсатсыз жоқ.

Қадамдар

1. Тексеру (тек оқу): фреймворк, деректер қоры/ORM, тапсырыс өмірлік циклі, бар төлем коды, беру (fulfilment), фондық тапсырмалар, ортаның айнымалылары, тесттер.
2. Сәйкестік: тапсырыс ID → merchant_order_id; сома деректер қорынан, бүтін теңге; Idempotency-Key — тапсырыспен бірге тұрақты.
3. Баптау: ELEVENPAY_ENABLED (өшірулі), ELEVENPAY_BASE_URL, ELEVENPAY_API_KEY, ELEVENPAY_WEBHOOK_SECRET — тек серверде.
4. Шот: POST /v1/cashier/invoices; нәтиже белгісіз болса — сол кілтпен кейінірек қайталаңыз.
5. Вебхук: бірінші төлемнен бұрын тіркеңіз; қолтаңбаны шикі байттармен тексеріңіз.
6. Растау: «төленді» тек расталған есеп айырысудан кейін; бір транзакцияда оқиға ID + шартты жаңарту + беру кезегі.
7. Қайталау: шот та, беру де қайталанбайды. unknown — екінші шот жоқ.
8. Мерзім/кеш төлем: мерзім сіздікі; кеш расталған төлем — қолмен қарау.
9. Тест: кит тесттері, offline_demo, lifecycle-vectors.json; өз lint/typecheck/тесттеріңіз.