Как партнёру провести клиента через анкету о бизнесе?

Почему анкету нельзя подать за клиента

В анкете есть подтверждение о неторговле запрещённым — азартные игры, крипта и форекс, оружие, взрослый контент и подобное. Это юридическое заверение, и давать его должен тот, у кого факты, — поэтому анкету заполняет и подтверждает сам клиент.

⛔ Не проектируйте у себя форму-прокси, которая собирает ответы клиента и отправляет их нашим API от его имени: принимающей ручки не существует. Ваша роль — довести клиента до формы, а не заполнить её.

Шаг 1. Прочитать состояние

curl "https://api.apipay.kz/api/partner/organizations/829/kyc" -H "X-Partner-Key: $KEY"

{ "success": true,
  "kyc": { "status": "needs_changes", "required_action": "fix_and_resubmit",
           "can_submit": true, "comment": "Скриншот витрины нечитаемый",
           "submitted_at": "2026-08-14T12:00:00+05:00", "submitted_via": "invite" } }

⚠️ Ветвитесь по required_action, а не по status. Это производное поле именно затем, чтобы маппинг наших статусов не оказался зашит в вашей CRM: ветвление по нему переживает пополнение набора статусов.

comment приходит только при fix_and_resubmit. Передавайте его клиенту дословно: это конкретное указание модератора, а пересказ превращает его в догадку.

Все клиенты сразу

Опрашивать каждую организацию по отдельности не нужно:

• GET /api/partner/health → organizations.kyc — сколько клиентов в каком состоянии;
• GET /api/partner/organizations?kyc_status=required,needs_changes — кто именно; это и есть «кому нужна анкета», одним запросом;
• карточка каждой организации несёт kyc_status.

Шаг 2. Выдать ссылку

curl -X POST "https://api.apipay.kz/api/partner/organizations/829/kyc/invite" \
  -H "X-Partner-Key: $KEY"

{ "success": true, "invite_url": "https://apipay.kz/invite/2f6c…",
  "expires_at": "2026-08-29T12:00:00+05:00" }

Что важно знать про ссылку:

• показывается один раз — у нас хранится только её хеш, повторно получить ту же не выйдет;
• передавайте её клиенту как есть — адрес ссылки может измениться, собирать его у себя из токена не нужно;
• новая выдача отзывает предыдущую — если клиент потерял ссылку, просто выдайте новую, но старая перестанет работать;
• открывать можно сколько угодно раз до истечения срока: если анкету вернут на доработку, клиент исправит её по той же ссылке;
• открывается без входа — передавайте её клиенту лично (личный чат, письмо), а не в общий канал: у того, кто получил ссылку, есть доступ к анкете этой организации до истечения срока;
• живёт 14 дней.

Отказы: 409 kyc_already_submitted (анкета уже у модератора, одобрена или по ней вынесен отказ), 409 test_organization (тестовая организация — на ней анкета не заводится).

Шаг 3. Что увидит клиент

Клиент открывает ссылку и заполняет три коротких шага — что продаёт и примерный средний чек, где продаёт (ссылка на витрину и 1–3 скриншота), подтверждение о неторговле запрещённым. Регистрация и вход не нужны, на странице видно только название его организации.

Скриншоты — jpg или png. Слишком большой файл отдаст 413, неподходящий формат — 422 invalid_file_type, а длинная склейка нескольких страниц в один узкий файл не принимается (422 image_rejected) — её нужно приложить частями.

Полное описание анкеты глазами клиента — «Анкета о бизнесе и лимит 1 платёж в день». Эту статью удобно переслать клиенту вместе со ссылкой.

Шаг 4. Поймать решение вебхуком

Решение модератора приходит на ваш webhook_url — поллить статус каждой организации не нужно:

{ "event": "kyc.status_changed", "scope": "partner", "partner_id": 7,
  "organization_id": 829, "external_id": "crm-client-42",
  "previous_status": "submitted", "kyc_status": "needs_changes",
  "comment": "Скриншот витрины нечитаемый",
  "source": "Partner Key", "is_sandbox": false, "timestamp": "2026-08-15T12:00:00+05:00" }

⚠️ Событие описывает переход, а не текущее состояние. Оба статуса зафиксированы в момент решения, поэтому повторная доставка не «догоняет» более позднее состояние: если модератор успел передумать, вы получите два события — про каждый переход своё. Опираться на текущее состояние всегда можно через GET .../kyc.

⚠️ Событие приходит только по организациям, которыми вы управляете. Клиент, пришедший по вашей реферальной ссылке, ведёт анкету сам и в своём кабинете.

Проверка подписи — та же, что у остальных наших событий: «Настройка вебхуков».

Пока анкета не одобрена

Организация клиента работает, но с ограничением: 1 реальный счёт в сутки (окно Asia/Almaty). При попытке создать второй API вернёт 429 kyc_daily_limit_reached, в теле meta{limit, reset_at, kyc_status}, в заголовке Retry-After — секунды до сброса.

В лимит идут все реальные счета организации: выставленные из кабинета, созданные по API-ключу, счета по QR и автосписания подписок. В песочнице лимита нет — отладку интеграции клиент (и вы) продолжаете там без ограничений.

После одобрения лимит снимается автоматически. Отказ (blocked) закрывает приём платежей: создание счёта возвращает 403 kyc_rejected, статус терминальный.

Частые ошибки

Частые вопросы