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

Шаг 1: Создание апелляции

Создание апелляции для счета или выплаты для начала процесса.

Эндпоинты: 

  • POST /merchant/Appeals/CreateInvoiceAppeal (для счетов)
  • POST /merchant/Appeals/CreateWithdrawalAppeal (для выплат)

Запрос:

POST /merchant/Appeals/CreateInvoiceAppeal HTTP/1.1
Host: api.example.com
ECDSA: {signature}:{id}
Content-Type: application/json
Accept: application/json
{
  "invoiceId": 12345
}

Ответ:

{
  "id": "H7OOOH-Q206B-ULЗY4V"
}

Результат: Получение ID апелляции (H7OOOH-Q206B-ULЗY4V) для дальнейших действий.

---

Шаг 2: Прикрепление файлов

Загрузка файла (PDF, JPEG или PNG, до 10 МБ) для предоставления подтверждающих документов.

Эндпоинт: POST /merchant/Appeals/UploadFile

Запрос:

POST /merchant/Appeals/UploadFile?appealId=H7OOOH-Q206B-ULЗY4V&externalId=upload_123 HTTP/1.1
Host: api.example.com
ECDSA: {signature}:{id}
Content-Type: multipart/form-data
Accept: application/json

Content-Disposition: form-data; name="file"; filename="receipt.pdf"
Content-Type: application/pdf

Ответ:

{
  "fileIds": ["file_456"]
}

Результат: Получение ID загруженного файла (file_456) для ссылки.

---

Шаг 3: Проверка статуса апелляции

Периодический запрос данных апелляции для отслеживания статуса и обновлений.

Эндпоинт: GET /merchant/Appeals/GetById

Запрос:

GET /merchant/Appeals/GetById?id=H7OOOH-Q206B-ULЗY4V HTTP/1.1
Host: api.example.com
ECDSA: {signature}:{id}
Accept: application/json

Ответ:

{
  "id": "H7OOOH-Q206B-ULЗY4V",
  "creationTime": "2025-05-21T09:00:00Z",
  "status": "Created",
  "operationType": "Invoice",
  "operationId": 12345,
  "expiresAt": "2025-05-28T09:00:00Z",
  "expireSecondsRemaining": 604800,
  "historyEntries": [
    {
      "id": "history_001",
      "creationTime": "2025-05-21T09:00:00Z",
      "status": "Created",
      "comment": "Апелляция создана",
      "author": "Мерчант"
    }
  ],
  "messages": [],
  "chatFiles": [],
  "files": [
    {
      "id": "file_456",
      "createdAt": "2025-05-21T09:05:00Z",
      "name": "receipt.pdf",
      "authorName": "Мерчант",
      "fileLink": "https://api.example.com/files/file_456"
    }
  ],
  "reason": "Оспаривание счета"
}

Результат: Получение текущего статуса (Created, Rejected, Accepted и т.д.) и просмотр истории, сообщений и прикрепленных файлов.

---

Дополнительно: Получение коллбэка о сообщении Арбитра

Коллбэки отправляются на зарегистрированный URL-адрес мерчанта или агрегатора при появлении сообщения от арбитра в апелляции. Это позволяет оперативно получать уведомления об обновлениях без необходимости периодического опроса статуса через GET /merchant/Appeals/GetById.

Структура коллбэка:

{  "entityType": "Appeal",
  "appealId": "H7OOOH-Q206B-ULЗY4V",
  "invoiceId": "2222",
  "invoiceExternalId": "1234",
  "message": "Сообщение от арбитра",
  "files": [
    {
      "id": "H6Q7FX-MQ2CJ-OIYPHP",
      "link": "https://rt-appeals.s3.yandexcloud.net/H6Q7FX...",
      "name": "763167df-5646-494e-b315-e554596218da.pdf"
    }

Особенности структуры:

  • Поле entityType всегда имеет значение "Appeal".
  • Поле appealId указывает ID апелляции.
  • Для апелляций по счетам используются поля invoiceId и invoiceExternalId.
  • Для апелляций по выплатам вместо invoiceId и invoiceExternalId используются поля withdrawalId и withdrawalExternalId.
  • Поле message содержит текст сообщения от арбитра.
  • Поле files содержит массив прикрепленных файлов (если есть), с их ID, ссылкой для скачивания и именем файла.

    Получение коллбэка позволяет мерчанту или агрегатору оперативно реагировать на сообщения арбитра, загружать прикрепленные файлы (через GET /merchant/Appeals/DownloadFile) или отправлять ответные сообщения (через POST /merchant/Appeals/SendChatMessage).

Дополнительные действия

  • Отправка сообщений в чат: Используйте POST /merchant/Appeals/SendChatMessage для общения в чате апелляции.
  • Пометка как прочитано: Используйте POST /merchant/Appeals/MarkAsRead для отметки апелляции как прочитанной.
  • Скачивание файлов: Используйте GET /merchant/Appeals/DownloadFile для получения прикрепленных файлов.
  • Удаление файлов: Используйте POST /merchant/Appeals/RemoveFileAppointment для удаления загруженных файлов.

warning Примечания

  • Все запросы должны содержать подпись ECDSA в заголовке: ECDSA: {signature}:{id}.
  • Для отслеживания обновлений требуется периодический опрос статуса (GET /merchant/Appeals/GetById), но это можно улучшить с помощью коллбэков (см. ниже).
  • Поддерживаемые статусы: Created, Rejected, Accepted, Completed, Canceled, NeedClarification.
  • Поддерживаемые форматы файлов: PDF, JPEG, PNG (максимум 10 МБ).
  • Нет меток