Управление картами поставщиков вторсырья¶

QIWI позволяет организациям, занимающимся приёмом вторсырья, заказать неименные пластиковые карты для выплат своим клиентам (физическим лицам-поставщикам). Партнёр управляет картами через сервис Recycling API — вручную с помощью интерфейса Личного кабинета или автоматически с помощью API.

Пластиковая карта — это реквизиты, напечатанные на физическом носителе, который доставляется партнёру по почте или курьером.

В этой статье описаны основные сценарии управления картами с помощью API.

Данные клиента¶

Для выдачи карты требуются следующие персональные данные клиента:

• фамилия;
• имя;
• отчество (если есть);
• дата рождения;
• место рождения;
• гражданство;
• паспортные данные (серия, номер, кем и когда выдан);
• номер мобильного телефона;
• адрес регистрации;
• адрес фактического проживания (если не совпадает с адресом регистрации);
• основание нахождения в России (для иностранных граждан, кроме Республики Беларусь и Республики Казахстан).

Первичная выдача карты¶

Сценарий «Первичная выдача карты» выполняется для клиента, который ещё не был зарегистрирован партнёром в сервисе Recycling.

Успешный сценарий «Первичная выдача карты» описан и изображён ниже.

1. QIWI через службу доставки передаёт конверты с неименными пластиковыми картами партнёру.
2. Партнёр отправляет в Recycling API запрос на создание заявки, где указывает:
   • персональные данные для регистрации и идентификации клиента;
   • параметр activationType=NEW.
3. Recycling API возвращает информацию о заявке и ее статус (status=PROCESSING_APPLICATION).
4. Партнёр периодически отправляет в Recycling API запрос статуса заявки.
5. Партнёр выдаёт карту клиенту и выполняет сценарий «Активация карты», если в ответе на запрос статуса заявки получен status=ACTIVATION_PENDING.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":14,
        "width":193,
        "actorMargin":81}}}%%
sequenceDiagram
    participant P as Партнёр
    participant Q as QIWI
    participant D as Служба доставки
    rect rgb(220, 230, 230)
    Q->>D: Передача конверта с картой
    D->>P: Доставка карты
    end
    P->>+Q: Запрос на создание заявки
    Note over P, Q: agentId, activationType=NEW, firstName, lastName, contacts, identifyingDocument, registrationAddress, livingAddress, secondaryDocument
    Q-->>-P: Ответ на запрос
    Note over P, Q: id, pointAddress, status:PROCESSING_APPLICATION
    loop Отслеживание статуса заявки
    P->>+Q: Запрос статуса заявки
    Note over P, Q: agentId, applicationId
    Q-->>-P: Ответ на запрос
    Note over P, Q: id, pointAddress, status:ACTIVATION_PENDING
    end
    rect rgb(255, 238, 223)
    P->>+Q: Сценарий «Активация карты»
    Q-->>-P: 
    end
    Note over Q,P: status:ACTIVATED

Элемент диаграммы QIWI — совокупность участников, обеспечивающих управление картой.

Запросы описаны в документации Recycling API. Сценарий «Активация карты» описан в разделе «Активация карты».

Повторная выдача карты¶

Сценарий «Повторная выдача карты» выполняется для клиента, который уже был зарегистрирован партнёром в сервисе Recycling, и оригинальная карта была утрачена или у неё истёк срок действия.

Успешный сценарий «Повторная выдача карты» аналогичен сценарию «Первичная выдача карты», за одним исключением: на шаге 2 в запросе на создание заявки партнёр передаёт параметр activationType=REISSUE, а не activationType=NEW.

Активация карты¶

Активация карты предполагает последовательное выполнение следующих шагов:

• создать заявку на выдачу карты;
• выдать карту клиенту;
• активировать карту.

Для активации партнёру необходим номер конверта с картой (известен партнёру) и идентификатор заявки, который возвращается в ответе на запрос создания заявки или на запрос списка заявок. Эти параметры нужно передать в запросе на активацию карты к Recycling API.

• В случае первичной выдачи карты активация выполняется синхронно. В ответе на запрос активации приходит status=ACTIVATED (финальный успешный статус).
• В случае повторной выдачи карты в ответе на запрос активации приходит status=ACTIVATION_IN_PROGRESS (нефинальный статус). Актуальный статус активации можно узнать с помощью запроса на получение информации по заявке — он возвращается в поле status.

После завершения активации карты клиенту на номер, указанный в заявке (contacts.mobilePhoneNumber), поступает SMS-оповещение об активации карты.

Жизненный цикл заявки на выдачу карты¶

В этом разделе описаны переходы заявки на выдачу карты из одного состояния в другое.

stateDiagram-v2

    state application_type <<choice>>
     [*] --> PROCESSING_APPLICATION: Данные ОК
     [*] --> REJECTED: Данные не ОК, заявка отклонена
        note left of [*]
            Полный набор данных
        end note
    PROCESSING_APPLICATION --> ACTIVATION_PENDING : Заявка обработана,<br>ожидание активации карты
    PROCESSING_APPLICATION --> REJECTED : В результате обработки заявки<br>карта не может быть выдана
    ACTIVATION_PENDING --> application_type: Активация карты
    application_type --> ACTIVATED : Первичная выдача карты
    application_type --> ACTIVATION_IN_PROGRESS: Повторная выдача карты
    ACTIVATED --> [*] : Карта активирована
    ACTIVATION_IN_PROGRESS --> ACTIVATED

Партнёр передаёт полный набор данных клиента. Если данные прошли проверки формата и могут быть сохранены, в сервисе создаётся заявка в одном из состояний:

• PROCESSING_APPLICATION — когда данные прошли валидацию, запускаются внутренние проверки и идентификация клиента;
• REJECTED — когда данные не прошли валидацию.

Если по заявке в состоянии PROCESSING_APPLICATION получен результат обработки заявки (есть результат внутренних проверок данных и идентификации клиента), она переходит в одно из двух возможных состояний:

• ACTIVATION_PENDING — если внутренние проверки и идентификация успешно пройдены;
• REJECTED — если внутренние проверки и идентификация не пройдены.

Далее статус заявки меняется в зависимости от того, карта выдана первично или повторно:

• Первичная выдача карты. После активации карты партнёром заявка переходит в статус ACTIVATED. Это означает, что карта активирована и готова к использованию.

• Повторная выдача карты. После активации карты партнёром заявка переходит в статус ACTIVATION_IN_PROGRESS. Последующий переход заявки в статус ACTIVATED означает, что карта активирована и готова к использованию.