API арқылы Kaspi шоттары

    4 мин оқу
    ·
    7 қаралым
    ·
    Жаңартылды: 2026-11-18

    Жүйеңізден жіберілетін Kaspi шоттары

    CRM жүйеңіз немесе сайтыңыз клиентке телефон нөмірі бойынша кез келген сомаға Kaspi шотын жібереді. Клиент шотты Kaspi қосымшасында алып, төлейді. Төлем өткенде вебхугыңызға kaspi_invoice_paid оқиғасы келеді: соның негізінде тапсырысты жабасыз және қажет болса, клиентке POST /v1/messages/send арқылы жазасыз.

    Бастамас бұрын не керек

    • Kaspi Pay кассирі кабинетте қосылған: Баптаулар → Интеграциялар → Kaspi Pay. «Кассир» рөлі бар жеке нөмір қажет.
    • Kaspi Pay тарифі әрекет етеді: «Старт» (бір кассаға айына 150 төлемге дейін) немесе «Шексіз». Тарифті кабинетте төлеуге болады: Коннекторлар → Kaspi Pay. Кассир алғаш қосылғаннан кейін 7 күндік сынақ кезеңі беріледі. WazzaBee CRM жүйесі әрекет етсе (сынақ немесе төленген), шоттар тегін.
    • API кілтіңіз үшін Kaspi шоттары қосылған. Оларды сіздің өтінішіңіз бойынша WazzaBee қолдау қызметі қосады, басқа кілттерде әдістер 403 қатесін қайтарады.
    • Кілттің вебхугы PATCH /v1/webhooks арқылы бапталған. Kaspi оқиғалары оған бөлек жазылусыз келеді.

    Артық шоттардан қорғаныс

    • Бір кілтке минутына 5 шоттан және тәулігіне 100 шоттан аспайды. Көбірек қажет болса, қолдау қызметіне жазыңыз.
    • Сол externalId бар қайталама сұраныс екінші шот жасамайды, бірінші шотты "duplicate": true белгісімен қайтарады.
    • Соңғы 30 минутта сол нөмірге сол сомаға төленбеген шот бар болса, жаңасы жасалмайды, жауапта бар шот келеді.
    • Бір кассирге тәулігіне барлық жолдар бойынша 300-ден аспайтын шот: API, мәзір-бот және CRM мәмілелері.
    • Егер тәулік ішінде клиенттер кілттің 10 немесе одан көп шотын қабылдамаса немесе төлемесе және бұл жабылған шоттардың жартысынан көп болса, кілт үшін Kaspi шоттары автоматты түрде тоқтатылады (kaspi_auto_stopped қатесі). Қайта қосу үшін қолдау қызметіне жазыңыз.

    POST /v1/kaspi/invoices

    Шот жіберу.

    POST https://api.wazzabee.com/api-gateway/v1/kaspi/invoices
    Authorization: Bearer API_КІЛТІҢІЗ
    Content-Type: application/json
    ПараметрТүріМіндеттіСипаттамасы
    phonestring✅Клиенттің Kaspi-дегі нөмірі, Қазақстан: +77011234567, 87011234567 немесе 7011234567
    amountnumber✅Теңгемен сома, 0-ден көп және 5 000 000-нан аспайды
    commentstringЖоқШотқа 200 таңбаға дейінгі түсініктеме, мысалы тапсырыс нөмірі мен тауар. Клиент оны Kaspi-де көреді
    externalIdstringЖоқЖүйеңіздегі тапсырыс нөмірі, 100 таңбаға дейін. Сұраныс қайталанғанда қос шоттан қорғайды
    curl -X POST "https://api.wazzabee.com/api-gateway/v1/kaspi/invoices" \
      -H "Authorization: Bearer API_КІЛТІҢІЗ" \
      -H "Content-Type: application/json" \
      -d '{"phone": "+77011234567", "amount": 15000, "comment": "Тапсырыс 1024, қап", "externalId": "1024"}'

    Жауап 201 (жаңа шот) немесе 200 (қайталау, "duplicate": true):

    {
      "success": true,
      "duplicate": false,
      "invoice": {
        "invoiceId": "uuid",
        "externalId": "1024",
        "phone": "+77011234567",
        "amount": 15000,
        "comment": "Тапсырыс 1024, қап",
        "status": "pending",
        "createdAt": "2026-11-17T14:00:00.000Z",
        "paidAt": null
      }
    }

    Шот мәртебелері: pending (төлемді күтуде), paid (төленді), expired (мерзімі өтті), cancelled (болдырылмады), unknown (Kaspi 3 күн ішінде жауап бермеді).

    GET /v1/kaspi/invoices/{invoiceId}

    invoiceId бойынша шот. Жауап: {"success": true, "invoice": {...}}. Мәртебе минутына бір рет жаңарады.

    GET /v1/kaspi/invoices

    Кілтіңіздің шоттары, жаңалары жоғарыда. Сұраныс жолының параметрлері: from және to (ISO 8601 күні), status (pending, paid, expired, cancelled, unknown), limit (1–200, әдепкі бойынша 50).

    GET https://api.wazzabee.com/api-gateway/v1/kaspi/invoices?from=2026-11-01T00:00:00Z&status=paid

    POST /v1/kaspi/invoices/{invoiceId}/cancel

    Төленбеген шотты болдырмау. Жауап: {"success": true, "invoice": {..., "status": "cancelled"}}. Өзіңіз болдырмаған шот үшін вебхук келмейді, нәтиже бірден жауапта болады.

    Вебхукке келетін оқиғалар

    ОқиғаҚашан
    kaspi_invoice_paidКлиент шотты төледі
    kaspi_invoice_expiredШотты төлеу мерзімі өтті
    kaspi_invoice_cancelledКлиент шоттан бас тартты немесе оны Kaspi-де болдырмады
    {
      "event": "kaspi_invoice_paid",
      "invoice": {
        "invoiceId": "uuid",
        "externalId": "1024",
        "phone": "+77011234567",
        "amount": 15000,
        "comment": "Тапсырыс 1024, қап",
        "status": "paid",
        "createdAt": "2026-11-17T14:00:00.000Z",
        "paidAt": "2026-11-17T14:03:10.000Z"
      },
      "timestamp": "2026-11-17T14:03:40.000Z"
    }

    Оқиға мәртебе өзгергеннен кейін бір минут ішінде келеді, WazzaBee-нің басқа вебхуктері сияқты қолтаңбамен және қайталаулармен. Мәртебені GET /v1/kaspi/invoices/{invoiceId} арқылы тексеруге болады.

    Ықтимал қателер

    КодerrorСебебі
    400bad_phone, bad_amount, bad_external_idНөмір, сома немесе externalId қате
    402no_tariffKaspi Pay тарифі әрекет етпейді, сынақ кезеңі аяқталды. Тарифті төлеңіз: Коннекторлар → Kaspi Pay
    402plan_limitОсы айда «Старт» тарифінің төлем лимиті таусылды
    403kaspi_not_enabledБұл кілт үшін Kaspi шоттары қосылмаған
    403kaspi_auto_stoppedЖаппай бас тартулар салдарынан кілттің шоттары автоматты түрде тоқтатылды, қолдау қызметі қосады
    404not_foundШот кілтіңіздің шоттары арасынан табылмады
    409not_connected, needs_reauthКассир қосылмаған немесе оны кабинетте қайта қосу керек
    409not_cancellableШот төленіп қойған немесе жабылған
    429rate_limit_minute, rate_limit_dayКілттің шот лимиті асып кетті
    429kassa_day_limitКассир бір тәулікте 300 шот шығарды, ертең қайталаңыз
    502kaspi_errorKaspi сұранысты қабылдамады, кейінірек қайталаңыз