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


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

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

Запрос:

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?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?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 и т.д.) и просмотр истории, сообщений и прикрепленных файлов.


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

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

Условие отправки коллбэка:

Коллбэк формируется, если в апелляции появляется сообщение от арбитра.

Эндпоинт для настройки коллбэков:

Мерчант или агрегатор должен зарегистрировать URL для получения коллбэков через соответствующий API-метод (например, POST /merchant/Callbacks/Register — уточните у администратора API).

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

{  "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"
    }

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

Результат:

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

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

warning Примечания