После долгой паузы и анализа обратной связи, мы доработали некоторые части системы и рассказываем о предстоящих изменениях.

Классификатор кода ошибок

За все время существования наших сервисов одним из главных замечаний партнеров было то, что при интеграции нашего API им трудно обрабатывать ошибки, потому что большей частью они описаны произвольно, а в ‘выковыривании’ причин из текстового сообщения приятного мало.

В ближайшее время мы выпустим обновление, в котором в ответ с ошибкой будет дополнительно передаваться причина в виде цифрового кода ошибки по общему классификатору. Весь список можно посмотреть в документации API, но давайте рассмотрим пример ответа при создании выплаты, когда на кошельке нет баланса.

Раньше результат был примерно такой:

{
    "error": {
        "code": 400,
        "request": "b6dcb689-cd7d-91f8-a27c-4d35b2053274",
        "message":"Insufficient funds on the contract ID, cannot transfer `5000`, only `2000` available"
    }
}

Как видно из примера, единственный вариант понять, что причина именно в балансе - это проверять текст в сообщении. Однако текст является скорее общим описанием проблемы, чтобы клиент смог быстро понять причину. Так как в нашем случае клиенты - это системы наших партнеров, ошибки должны иметь структуру и быть машиночитаемы.

После выпуска обновлений системы сообщение об ошибке в случае недостаточности баланса будет выглядеть вот так:

{
    "error": {
        "code": 400,
        "reason": "200201",
        "request": "b6dcb689-cd7d-91f8-a27c-4d35b2053274",
        "message":"Insufficient balance",
        "details": {
            "amount": "10000",
            "balance": "1000"
        }
    }
}

Теперь у нас есть код ошибки в `reason`, а также дополнительно `details` с деталями ошибки.

Защита от дубликатов

Подробнее об этом можно прочитать в соответствующем разделе документации.

Рассмотрим случай, когда в системе срабатывала защита от дубликатов, но клиенту это доносилось в неудобном виде:

1. Клиент отправляет запрос на создание новой заявки к выплате

2. Заявка создается, но корректный ответ не доносится по причине технической ошибки с сетью, нашим сервером или сервером клиента. Это техника, такое бывает. Для таких случаев клиент передает внешний идентификатор в поле `external_ref_id`, чтобы в случае проблем отправить запрос повторно

3. Из-за проблемы с отправкой заявки клиент отправляет тот же запрос повторно. Но тут возникает проблема с обработкой запроса уже на нашей стороне

Если в системе уже была заявка с тем же внешним идентификатором, в ответ выдавался следующий ответ:

{
    "error": {
        "code": 400,
        "request": "e6ba3aad-7954-9534-a292-18f2e61d50b4",
        "message": "Invalid form request, see `data` for details",
        "data": {
            "external_ref_id": "Value should be unique."
        }
    }
}

На первый взгляд вроде бы все ясно, но интеграционный код клиента уже покрыт слоем сложности - факт дубликата выражен не самым тривиальным образом и фактически требует детального разбора всего ответа.

Мы вернулись сразу с двумя вариантами решения этой проблемы:

Вариант 1. Ничего не меняется, но код ошибки дубликата выглядит несколько иначе:

{
    "error": {
        "code": 400,
        "reason": "100100",
        "request": "e6ba3aad-7954-9534-a292-18f2e61d50b4",
        "message": "Duplicate request attempt",
        "details": {
            "id": 123,
            "external_ref_id": "376716985183021"
        }
    }
}

Теперь у нас есть не только явно переданный сигнал о дубликате в поле `reason`, но и вспомогательная информация в `details`. Больше не нужно пользоваться поиском и искать исходную заявку, она уже передана.

Вариант 2. Данный подход мы рекомендуем для всех новых интеграций.

Достаточно будет просто передать вместе с запросом заголовок `Idempotency-Replay: true`, и вместо ответа с ошибкой система вернет исходную заявку, как если бы никакого дубликата и не было. (при этом в ответе будет заголовок `Idempotency-Replayed: true`; то есть заявку вернули, но если кому-то важно, дали знать, что это был replay операции)

Оба варианта подразумевают, что клиент получает запрос от своего пользователя в браузере или приложении, создает заявку в своей системе, а затем пытается передать ее нам с внешним идентификатором уже асинхронно через очередь задач.

Все изменения пока отлаживаются в тестовой среде и будут выпущены в течение недели. Напишите нам, если у вас есть какие-то замечания или предложения.

Две недели назад мы анонсировали, что планируем изменения в работе статусов заявок. С тех пор мы отрабатывали с партнерами все нюансы и отлаживали необходимый функционал.

Спешим сообщить, что мы наконец выпустили эти изменения, а также несколько других улучшений.

1. Из-за изменений работы платежных шлюзов, в последние месяцы начали появляться заявки на выплату, которые долго висели в статусе FAILED. Таких заявок было немного, но когда человек не мог получить свои деньги потому, что платеж где-то завис - это приносило излишний негатив в сторону наших партнеров и следовательно нас самих. Мы учли эти недочеты, и теперь все неуспешные платежи будут переходить в финальный статус в течение 30-60 секунд вместо нескольких часов.

2. Мы начали работу над улучшением детализации причин отмены платежей. Например, теперь клиенты смогут понять, что их банк отказал им в зачислении на карту потому, что у них на карте отключена возможность проведения интернет платежей; что карта истекла, заблокирована или даже украдена. А не потому, что ‘отказано‘.

3. Иногда случаются ситуации, когда клиенты не видят выплаты на своих картах. Причин может быть много, но чтобы исключить технические, нам по запросу приходится запрашивать так называемые коды ARN/RRN от МПС, чтобы клиент мог обратиться в свой банк и разобраться. Этот процесс сейчас довольно долгий, но мы начали работу над его совершенствованием. В течение последующих 2-3 недель партнеры смогут наблюдать, что у них появляются новые детали платежей: в частности, ARN/RRN референс зачисления платежа.

В настоящий момент заявка на выплату может пребывать в одном из следующих статусов:

• PENDING - Заявка принята нашей системой, но еще не обработана

• FAILED - Система попыталась обработать заявку, но шлюз не смог ее принять

• PROCESSED - Заявка отработана, платеж исполнен

• CANCELLED - Платеж был отклонен, поэтому заявка отменена и деньги возвращены.

Тут все просто и понятно, первые два статуса не финальные, а последние два - финальные. Но такой подход не учитывает момент, когда платежные шлюзы в свою очередь зависят от МПС или банков, выпустивших карту, и каждый этап в цепочке может иметь свои не финальные статусы. Поэтому мы решили внедрить еще одно состояние:

SENT - когда система обработала заявку и отправила ее в шлюз, но по какой-то причине не получила однозначный результат. Это не финальный статус заявки и по большому счету для конечного пользователя не сильно отличается от PENDING или FAILED, ибо ему все так же придется периодически опрашивать систему. Однако этот статус ясно дает понять, что поведение штатное.

Ввиду серьезности последствий в случае неопределенного поведения интеграций при получении неизвестного им статуса, мы будем вводить изменения не сразу, а через примерно 1 неделю, чтобы все успели доработать свои системы.

Наша система активно развивается, количество партнеров и клиентов растет, а сотрудничество становится глубже. Все это помогает нам лучше понимать потребности рынка и дорабатывать свои сервисы.

В этом блоге(?) мы будем активно рассказывать о продуктах, которые планируем запускать, или же собирать обратную связь по уже имеющимся.

Чтобы не возникало ситуаций, при которых партнеры были поставлены перед фактом и не успели доработать интеграции со своими системами, мы также будем заранее сообщать о планируемых изменениях. Под каждой заметкой можно будет написать свои замечания или предложения, даже анонимно. Но все же лучше оставляйте свои контакты.