Қысқаша
invoice_not_found (HTTP 404) — «счёт жоқ» деген сөз емес, «осы кілтке бұл счёт көрінбейді» деген сөз. Счёт әдетте орнында тұрады, бірақ сіз оны басқа кілтпен, басқа режимде немесе басқа ұйымнан сұрап отырсыз. Тексеру реті: идентификатор → режим (qp_test_ / qp_live_) → кілт байланған кассир → ұйым.
Симптом → себеп → шешім
| Симптом | Себебі | Шешімі |
|---|---|---|
| Жаңа ғана жасалған счёт табылмайды | Жауаптағы id емес, басқа өріс алынған | POST /invoices жауабындағы id өрісін пайдаланыңыз |
| Кабинетте счёт көрініп тұр, API таппайды | Счёт sandbox-та жасалған, сұрау live кілтпен | Кілтті сол режимге сәйкестендіріңіз |
| Кеше істеп тұрған код бүгін 404 береді | Кілт ауыстырылған, жаңа кілт басқа кассирге байланған | Кілттің байланысын кабинеттен қараңыз |
| Бір счёт бір қызметке көрінеді, екіншісіне жоқ | Екі қызметте екі бөлек кілт, біреуі байланған | Ортақ кілт беріңіз немесе байланысты алып тастаңыз |
externalOrderId бойынша іздегенде бос | Іздеу id бойынша жүргізілген | Тізім эндпоинтінен сүзіңіз |
Тексеру реті
1. Идентификатор дұрыс па
Счёт POST /api/v1/invoices жауабындағы id өрісімен сұралады. Жиі кездесетін шатасулар:
externalOrderIdменidшатастырылған.externalOrderId— сіздің өз тапсырыс нөміріңіз, ол webhook-та қайта келеді, бірақGET /invoices/{id}соны қабылдамайды.- Артық бос орын немесе жаңа жол. Кілтті де, идентификаторды да айнымалыға салғанда соңындағы
\nбайқалмай қалады. - Басқа ортадан көшірілген. Тесттен өндіріске көшіп кеткен идентификатор.
Тапсырыс нөмірі бойынша іздеу керек болса, GET /api/v1/invoices тізімін пайдаланыңыз. Толығы: Metadata және тапсырыс нөмірі.
2. Режимі сәйкес пе
Sandbox пен live — екі бөлек әлем. qp_test_… кілтпен жасалған счёт qp_live_… кілтке мүлде көрінбейді, керісінше де солай.
Ең жиі кездесетін жағдай: әзірлеуші sandbox-та сынап, сосын өндіріске көшеді, ал ескі тест идентификаторлары кодта немесе тестте қалып қояды. Нәтижесі — таза 404.
Тексеру: қолданылып жатқан кілттің префиксін қараңыз. qp_test_ — sandbox, qp_live_ — нақты режим. Айырмашылығы: Sandbox пен нақты режим.
3. Кілт кассирге байланған ба
Кілтті нақты бір кассирге байлауға болады. Байланған кілттің live счёттары тек сол кассир арқылы жүреді, ол басқа кассирдің счёттарын көрмейді — сұраған кезде 404 қайтарады.
Бұл қате емес, әдейі жасалған мінез: екі нүкте немесе екі бөлімше бір-бірінің счёттарын көрмеуі үшін.
Қашан кездеседі:
- Ұйымда бірнеше кассир бар, счёттар әртүрлі кілттермен жасалады
- Кілт кейін байланып қойылған, ал ескі счёттар басқа кассирдікі
- Есеп жинайтын қызмет байланған кілт пайдаланып, бәрін көремін деп ойлайды
Шешімі: есепке бәрін көретін, кассирге байланбаған бөлек кілт беріңіз, немесе әр қызметке өз кассирінің кілтін беріңіз. Толығы: API кілтті кассирге байлау.
4. Ұйым сол ма
Бір аккаунтта бірнеше ұйым болса, әр ұйымның өз кілттері бар. Басқа ұйымның счётын сұрасаңыз, 404 немесе forbidden келеді — счёт бар, бірақ сіздікі емес.
Тексеру: кабинетте кілт қай ұйымда жасалғанын қараңыз. Толығы: Бір аккаунтта бірнеше ұйым.
Бір минуттық диагностика
Дәл сол кілтпен тізімді сұраңыз:
GET /api/v1/invoices
X-API-Key: <дәл сол кілт>| Нәтиже | Қорытынды |
|---|---|
| Тізім бос | Режим қате немесе кілт мүлде басқа ұйымдікі |
| Тізімде счёттар бар, бірақ іздегеніңіз жоқ | Кілт байланған кассир басқа, немесе идентификатор қате |
| Іздегеніңіз тізімде бар | Идентификаторды дұрыс көшірмегенсіз |
| 401 келді | Кілт мәселесі, счёт емес: API 401 қайтарады |
Не істемеу керек
- Қайталап сұрай бермеңіз. 404 — уақытша ақау емес, қайталау көмектеспейді әрі
too_many_attemptsқатесіне әкелуі мүмкін. - Жаңа счёт жасай салмаңыз. Ескісі төленіп қалса, клиент екі рет төлейді. Алдымен кабинеттен іздеңіз.
- Кілтті жоя салмаңыз. Ол мәселені шешпейді, бірақ істеп тұрған интеграцияларды құлатады.
Жиі қойылатын сұрақтар
Счёт жойылған болуы мүмкін бе? Жоқ. Счёттар жойылмайды, олар күйін өзгертеді: cancelled, expired. Мұндай счёт GET арқылы бұрынғыдай ашылады.
Кабинетте счёт көрінеді, API таппайды. Қалай болады? Кабинетте сіз ұйымның бәрін көресіз, ал кілт байланған болса — тек өз кассирінің счёттарын. Ең жиі себебі осы.
Сандық идентификатор бере аламын ба? Жоқ, id — біздің жақтан берілетін идентификатор, оны өзгертуге болмайды. Өз нөміріңіз үшін externalOrderId бар.
Webhook-та келген id жарай ма? Иә, webhook-тағы invoice.id — дәл сол идентификатор. Егер ол 404 берсе, режим немесе кілт сәйкессіздігі деген сөз.
Sandbox счёттарын live-ға көшіруге бола ма? Жоқ. Sandbox деректері нақты режимге өтпейді, олар бөлек. Көшкен соң жаңа счёттар жасайсыз.