/** * Контракт Parallel API v2: типы запросов, ответов и Webhook. Заявки на вход (IN) и на выход (OUT), баланс, * ввод и вывод USDT. * * Пишется руками и не генерируется из кода сервиса. Таблицы полей на страницах документации строятся * из этих типов, поэтому описание поля живёт только здесь. * * Правила формы: * - поля — snake_case; * - значения из закрытого списка (статус, тип файла, код причины) — заглавными: `"PAID"`, `"SBP"`; * - коды банков — строчными: список банков пополняется, это справочник, а не закрытый список; * - суммы — строками: рубли в заявках, USDT в балансе; время — ISO 8601 по Москве; * - поле, которого в этом состоянии нет, отсутствует, а не равно `null`. `null` бывает только там, где * значение не удалось прочитать из файла (`Transfer`). */ // ─── Общее ────────────────────────────────────────────────────────────────── /** Сумма в рублях строкой, без копеек, если их нет: `"1000"`, `"999.5"`. */ export type Rub = string; /** Сумма в USDT строкой: `"500"`, `"12.5"`. */ export type Usdt = string; /** Время, ISO 8601, московское время: `"2026-11-09T12:00:00+03:00"`. */ export type Timestamp = string; /** Способ оплаты: СБП по номеру телефона или перевод на карту. */ export type Method = "SBP" | "TO_CARD"; /** Код банка из `GET /api/v2/banks`: `"sberbank"`, `"tbank"`. Список пополняется. */ export type BankCode = string; /** Банк: код из `GET /api/v2/banks` или название, как его пишет клиент: `"sberbank"`, `"Сбер"`, `"Тинькофф"`. */ export type BankName = string; /** * Как к нам попадёт чек: * - `BANK_EMAIL` — клиент отправляет чек из приложения Т-Банка на почту заявки (`receipt_email`). Платить можно только из Т-Банка; * - `UPLOAD` — вы загружаете файл через `POST /api/v2/invoices/{invoice_id}/attachments`. Клиент платит из любого банка. */ export type ReceiptDelivery = "BANK_EMAIL" | "UPLOAD"; /** Ответ с ошибкой: любой код, кроме 2xx. */ export interface ErrorResponse { error: { /** Код ошибки: по нему ветвится код интеграции */ code: ErrorCode; /** Что случилось, по-русски, для человека */ message: string; }; } export type ErrorCode = /** 400: тело или параметры запроса не прошли проверку */ | "VALIDATION_ERROR" /** 401: нет токена или токен неверный */ | "UNAUTHORIZED" /** 403: магазин ещё не активирован */ | "SHOP_NOT_ACTIVATED" /** 403: заявки этого направления (на вход или на выход) магазину не подключены */ | "DIRECTION_DISABLED" /** 403: этот способ получения чека не подключён магазину */ | "RECEIPT_DELIVERY_DISABLED" /** 403: выбор банка реквизитов (`bank`) вашему магазину не подключён */ | "BANK_CHOICE_DISABLED" /** 403: выбор способа оплаты (`method`) вашему магазину не подключён */ | "METHOD_CHOICE_DISABLED" /** 403: диспуты по заявкам на выход вашему магазину не подключены */ | "DISPUTE_DISABLED" /** 403: этот вид дополнительного доказательства оплаты не подключён магазину */ | "PROOF_OPTION_DISABLED" /** 404: заявки или адреса нет */ | "NOT_FOUND" /** 405: этот метод у адреса не поддерживается */ | "METHOD_NOT_ALLOWED" /** 404: подписки на события ещё нет */ | "WEBHOOK_NOT_SET" /** 409: действие недоступно в текущем статусе заявки */ | "INVALID_STATUS" /** 409: чек по этой заявке клиент присылает на почту, загрузка недоступна */ | "RECEIPT_DELIVERY_IS_BANK_EMAIL" /** 409: под финансовую ответственность по этой заявке уже взята другая сумма */ | "FINANCIAL_RESPONSIBILITY_ALREADY_TAKEN" /** 409: на балансе не хватает доступных USDT */ | "INSUFFICIENT_BALANCE" /** 409: диспут по этой заявке уже открывался */ | "DISPUTE_ALREADY_OPENED" /** 409: срок, в который можно открыть диспут, вышел: `dispute_days` в `GET /api/v2/sla` */ | "DISPUTE_WINDOW_CLOSED" /** 413: файл больше допустимого */ | "FILE_TOO_LARGE" /** 415: формат файла не поддерживается */ | "UNSUPPORTED_FILE" /** 503: сейчас нет реквизитов на эту сумму, повторите запрос позже с тем же `internal_id`. Бывает у магазина, заявки которого не ждут реквизиты: `requisites_wait_minutes: 0` в `GET /api/v2/sla` */ | "NO_REQUISITES" /** 503: временный сбой, повторите запрос позже */ | "UNAVAILABLE"; // ─── Создание заявки ──────────────────────────────────────────────────────── /** Тело `POST /api/v2/invoices` для заявки на вход. */ export interface CreateInvoiceRequest { /** Номер заявки в вашей системе. Защищает от случайного повторного создания: повтор с тем же `internal_id` вернёт уже созданную заявку */ internal_id: string; /** Направление: `IN` — заявка на вход: клиент переводит рубли на реквизиты Parallel */ direction: "IN"; /** Сумма в рублях: `"1000"` */ amount: Rub; currency: "RUB"; /** Способ оплаты: `SBP` — по СБП, `TO_CARD` — на карту. Без него подойдёт любой. Выбирать способ оплаты можно, только если это разрешено вашему магазину, иначе — `403 METHOD_CHOICE_DISABLED` */ method?: "SBP" | "TO_CARD"; /** Банк реквизитов. Без него подойдёт любой доступный. Выбирать банк можно, только если это разрешено вашему магазину, иначе — `403 BANK_CHOICE_DISABLED` */ bank?: BankCode; /** Как к нам попадёт чек: `BANK_EMAIL` — с почты Т-Банка, `UPLOAD` — вы загрузите сами. Без него — `default_receipt_delivery` из `GET /api/v2/sla` */ receipt_delivery?: ReceiptDelivery; } /** Тело `POST /api/v2/invoices` для заявки на выход. */ export interface CreateOutInvoiceRequest { /** Номер заявки в вашей системе. Защищает от случайного повторного создания: повтор с тем же `internal_id` вернёт уже созданную заявку */ internal_id: string; /** `OUT` — заявка на выход: Parallel переводит рубли вашему клиенту */ direction: "OUT"; /** Сумма в рублях, которую получит клиент: `"12000"` */ amount: Rub; currency: "RUB"; /** Куда перевести деньги */ requisites: RecipientRequisites; } /** Реквизиты получателя в заявке на выход: телефон для СБП или номер карты. */ export type RecipientRequisites = | { /** Перевод по СБП на номер `phone_number` */ method: "SBP"; /** Банк получателя: код или название, [как узнать код](/docs/banks) */ bank: BankName; /** Имя получателя, как в банке: `"Иван Иванович И."` */ full_name: string; /** Телефон получателя: `"+79001234567"` */ phone_number: `+${number}`; } | { /** Перевод на карту `card_number` */ method: "TO_CARD"; /** Банк получателя: код или название, [как узнать код](/docs/banks) */ bank?: BankName; /** Имя получателя, как в банке: `"Иван Иванович И."` */ full_name: string; /** Номер карты получателя: только цифры, `"2200700012345673"` */ card_number: `${number}`; }; // ─── Заявка ───────────────────────────────────────────────────────────────── /** * Любая заявка: на вход или на выход. Различаются полем `direction`. Это ответ `GET /api/v2/invoices/{invoice_id}`, * элемент списка заявок и `data.object` события. */ export type Invoice = InInvoice | OutInvoice; /** * Заявка на вход: ответ на создание, на `GET /api/v2/invoices/{invoice_id}`, на действия с заявкой и `data.object` события. * Заявка без реквизитов — `"requisites" in invoice === false` — ещё ждёт их (`NEW`) или отменена до их выдачи. * Заявка с чеком на почту отличается полем `receipt_email`: `"receipt_email" in invoice`. */ export type InInvoice = WaitingInvoice | EmailInvoice | UploadInvoice; /** Поля, которые есть у любой заявки на вход. */ export interface InvoiceBase { /** Номер заявки в вашей системе */ internal_id: string; /** Номер заявки в Parallel */ invoice_id: string; /** Направление: `IN` — заявка на вход: клиент переводит рубли на реквизиты Parallel */ direction: "IN"; created_at: Timestamp; /** Время последнего изменения. Webhook по одной заявке приходят по порядку; если сравниваете сами, сравнивайте по этому полю */ updated_at: Timestamp; /** Сумма заявки */ amount: Rub; currency: "RUB"; /** Файлы по заявке — чеки и видео оплаты — в порядке получения */ attachments: Attachment[]; } /** Заявка, которой выданы реквизиты. */ export interface IssuedInvoiceBase extends InvoiceBase { /** Курс USDT/RUB заявки: столько рублей стоит 1 USDT на вашем балансе */ deal_rate: string; /** Реквизиты, на которые платит клиент */ requisites: Requisites; } /** Заявка, реквизиты по которой ещё ищем (`NEW`) или так и не выдали (`CANCELED`). Реквизитов и почты для чека в ней нет. */ export type WaitingInvoice = InvoiceBase & { /** Курс USDT/RUB заявки, если он уже известен. Иначе появится вместе с реквизитами */ deal_rate?: string; } & (New | CanceledWithoutRequisites); /** Заявка с чеком на почту. Чек с почты присылает сам Т-Банк, поэтому дополнительного доказательства оплаты по ней не бывает. */ export type EmailInvoice = IssuedInvoiceBase & { /** Почта для чека, своя у каждой заявки. Есть, только если чек придёт на почту (`receipt_delivery: "BANK_EMAIL"`) */ receipt_email: string; /** Текст для клиента: платить только из приложения Т-Банка и отправить чек на `receipt_email`. Покажите его рядом с реквизитами */ payer_warning: string; } & Exclude; /** Заявка, чек по которой загружаете вы. */ export type UploadInvoice = IssuedInvoiceBase & { /** Есть, если вы взяли оплату под финансовую ответственность */ financial_responsibility?: FinancialResponsibility; } & InvoiceState; /** Статус показывает, от кого ожидается действие. У каждого такого статуса свой срок. */ export type InvoiceState = | InProgress | Review | ProofRequired | Paid | InDispute | Chargeback | Expired | Canceled; export interface New { /** Ищем реквизиты до `requisites_until`. Нашли — заявка переходит в `IN_PROGRESS` с `requisites` и `pay_until`, придёт Webhook */ status: "NEW"; /** До этого времени ищем реквизиты, иначе заявка отменится с `NO_REQUISITES` */ requisites_until: Timestamp; } export interface InProgress { /** Ждём оплату от клиента до `pay_until` */ status: "IN_PROGRESS"; /** До этого времени клиент должен заплатить, а вы загрузить чек. Считается от выдачи реквизитов */ pay_until: Timestamp; /** Есть, если чеки подтвердили часть суммы заявки. Клиент может доплатить до `pay_until`; не доплатил — заявка переходит в `PAID` на эту сумму */ paid_amount?: Rub; } export interface Review { /** Проверяем файл до `review_until`, результат придёт на Webhook */ status: "REVIEW"; /** До этого времени мы проверим файл: `review_minutes` из `GET /api/v2/sla` с последнего полученного */ review_until: Timestamp; } export interface ProofRequired { /** Чек не подтвердил оплату. До `proof_until` пришлите видео оплаты или возьмите заявку под финансовую ответственность */ status: "PROOF_REQUIRED"; /** До этого времени загрузите видео оплаты или возьмите заявку под финансовую ответственность, иначе заявка истечёт */ proof_until: Timestamp; } export interface Paid { /** Оплачена: зачтено `paid_amount` рублей, USDT на вашем балансе */ status: "PAID"; /** Сколько рублей зачтено. Меньше `amount`, если к `pay_until` клиент заплатил меньше или вы взяли под финансовую ответственность меньшую сумму */ paid_amount: Rub; paid_at: Timestamp; /** Есть, если по заявке был диспут */ dispute?: ClosedDispute; } export interface InDispute { /** Открыт диспут: на реквизиты пришло меньше, чем зачтено. Зачтённое заморожено до решения */ status: "DISPUTE"; paid_amount: Rub; paid_at: Timestamp; dispute: Dispute; } export interface Chargeback { /** Диспут решён: денег не пришло, зачтённое списано с баланса */ status: "CHARGEBACK"; chargeback_at: Timestamp; dispute: ClosedDispute; } export interface Expired { /** Срок вышел, а оплата так и не подтвердилась. Окончательный статус */ status: "EXPIRED"; expired_at: Timestamp; } export interface Canceled { /** Отменена. Окончательный статус */ status: "CANCELED"; canceled_at: Timestamp; cancellation: Cancellation; } /** Отменена до выдачи реквизитов. Окончательный статус */ export interface CanceledWithoutRequisites { status: "CANCELED"; canceled_at: Timestamp; cancellation: { /** * - `CANCELED_BY_MERCHANT` — вы отменили заявку; * - `NO_REQUISITES` — реквизиты не нашлись к `requisites_until` */ code: "CANCELED_BY_MERCHANT" | "NO_REQUISITES"; message: string; }; } /** Почему заявка отменена. */ export interface Cancellation { /** * - `CANCELED_BY_MERCHANT` — вы отменили заявку; * - `REQUISITES_NOT_WORKING` — реквизиты не принимают перевод; * - `OTHER` — другое, подробности в `message` */ code: "CANCELED_BY_MERCHANT" | "REQUISITES_NOT_WORKING" | "OTHER"; message: string; /** Скриншот, если мы его приложили */ file_name?: string; /** Ссылка на скриншот, действует 7 дней */ file_url?: string; } /** Реквизиты для оплаты: по СБП или на карту. */ export type Requisites = SbpRequisites | CardRequisites; /** Реквизиты для перевода по СБП. */ export interface SbpRequisites { /** Перевод по СБП на номер `phone_number` */ method: "SBP"; /** Код банка */ bank: BankCode; /** Название банка для клиента */ bank_name: string; /** Имя получателя латиницей */ full_name: string; /** Телефон получателя: `+` и цифры, `"+79001234567"` */ phone_number: `+${number}`; } /** Реквизиты для перевода на карту. */ export interface CardRequisites { /** Перевод на карту `card_number` */ method: "TO_CARD"; /** Код банка. В заявке на выход без банка в запросе — определённый по номеру карты, а если не определили — `"unknown"` */ bank: BankCode | "unknown"; /** Название банка для клиента; при `bank: "unknown"` — `"Неизвестный банк"` */ bank_name: string; /** Имя получателя латиницей */ full_name: string; /** Номер карты получателя: только цифры, `"2200700012345673"` */ card_number: `${number}`; } /** Вы взяли оплату под финансовую ответственность. */ export interface FinancialResponsibility { /** Сколько рублей вы зачли на свою ответственность */ amount: Rub; taken_at: Timestamp; } /** Диспут открываем мы, когда денег на реквизиты пришло меньше, чем зачтено. */ export interface Dispute { /** Сколько на самом деле пришло на реквизиты заявки; `"0"` — ничего */ received_amount: Rub; /** Что случилось */ message: string; /** Наша выписка по реквизитам */ file_name: string; /** Ссылка на выписку, действует 7 дней */ file_url: string; opened_at: Timestamp; } /** Решённый диспут. Исход — в статусе заявки: `PAID` с `paid_amount` или `CHARGEBACK`. */ export interface ClosedDispute extends Dispute { closed_at: Timestamp; } // ─── Заявка на выход ──────────────────────────────────────────────────────── /** * Заявка на выход: Parallel переводит рубли вашему клиенту и прикладывает чеки. USDT на вашем балансе заморожены * с создания заявки и списываются, когда она оплачена. */ export type OutInvoice = OutInvoiceBase & (OutInProgress | OutPaid | OutInDispute | OutExpired | OutCanceled); /** Поля, которые есть у любой заявки на выход. */ export interface OutInvoiceBase { /** Номер заявки в вашей системе */ internal_id: string; /** Номер заявки в Parallel */ invoice_id: string; /** `OUT` — заявка на выход */ direction: "OUT"; created_at: Timestamp; /** Время последнего изменения. Webhook по одной заявке приходят по порядку; если сравниваете сами, сравнивайте по этому полю */ updated_at: Timestamp; /** Сумма заявки */ amount: Rub; currency: "RUB"; /** Курс USDT/RUB заявки: столько рублей стоит 1 USDT на вашем балансе */ deal_rate: string; /** Реквизиты получателя */ requisites: Requisites; /** Сколько рублей получатель получил по этой заявке. Растёт с каждым чеком; после диспута может быть уменьшена */ paid_amount: Rub; /** Максимальное число переводов по заявке */ max_receipts: number; /** Чеки наших переводов в порядке оплаты. Сумму можем перевести частями, тогда чеков несколько */ receipts: Receipt[]; } /** Чек нашего перевода получателю. */ export interface Receipt { /** Номер чека в Parallel */ receipt_id: string; /** Сумма этого перевода */ amount: Rub; file_name: string; /** Ссылка на чек, действует 7 дней */ file_url: string; /** Время перевода */ paid_at: Timestamp; } export interface OutInProgress { /** Переводим деньги получателю до `pay_until`. На каждый новый чек приходит `invoice.out.receipt_added` */ status: "IN_PROGRESS"; /** До этого времени мы переведём деньги: `pay_minutes` из `GET /api/v2/sla` с создания заявки или с решения диспута */ pay_until: Timestamp; /** Есть, если диспут принят с `REPAY`: переводим недостающее, `paid_amount` — сколько получатель получил */ dispute?: ClosedOutDispute; } export interface OutPaid { /** Оплачена: получателю переведено `paid_amount` рублей, USDT за эту сумму списаны с баланса. Если переведена только часть, `paid_amount` меньше `amount`, причина указана в `partial`, а USDT за остаток возвращены на баланс */ status: "PAID"; paid_at: Timestamp; /** Есть, если мы перевели меньше суммы заявки */ partial?: OutStop; /** Есть, если по заявке был диспут */ dispute?: ClosedOutDispute; } export interface OutInDispute { /** Вы открыли диспут: получателю пришло меньше, чем в чеках. Чей ход и до какого срока — в `dispute.status` */ status: "DISPUTE"; paid_at: Timestamp; dispute: OpenOutDispute; } export interface OutExpired { /** К `pay_until` не переведено ничего, USDT возвращены на баланс. Окончательный статус */ status: "EXPIRED"; expired_at: Timestamp; } export interface OutCanceled { /** Мы не смогли перевести ничего: реквизиты получателя не принимают перевод. USDT возвращены на баланс. Окончательный статус. Отменить заявку на выход сами вы не можете */ status: "CANCELED"; canceled_at: Timestamp; cancellation: OutStop; } /** Почему мы остановили переводы по заявке на выход. */ export interface OutStop { /** * - `REQUISITES_NOT_WORKING` — банк получателя отклонил перевод; * - `PAY_UNTIL_PASSED` — вышел срок `pay_until`; * - `OTHER` — другое, подробности в `message` */ code: "REQUISITES_NOT_WORKING" | "PAY_UNTIL_PASSED" | "OTHER"; message: string; /** Скриншот ошибки банка, если мы его приложили */ file_name?: string; /** Ссылка на скриншот, действует 7 дней */ file_url?: string; } /** * Что сделать с заявкой, если недостача подтвердится: * - `REPAY` — Parallel переведёт получателю недостающее; * - `RECALCULATE` — заявка пересчитается на сумму, которая пришла: USDT за разницу вернутся на баланс. */ export type DisputeResolution = "REPAY" | "RECALCULATE"; /** Выписка получателя из банка, приложенная к диспуту. */ export interface Statement { file_name: string; /** Ссылка на выписку, действует 7 дней */ file_url: string; /** Ваш комментарий к выписке */ message?: string; received_at: Timestamp; } /** Поля, которые есть у любого диспута по заявке на выход. */ export interface OutDisputeBase { /** Сколько, по словам клиента, пришло получателю; `"0"` — ничего */ received_amount: Rub; /** Что вы просите сделать с заявкой */ resolution: DisputeResolution; /** Ваш комментарий */ message?: string; /** Выписки, которые вы приложили, в порядке загрузки */ statements: Statement[]; opened_at: Timestamp; } export interface DisputeReview { /** Parallel проверяет выписку */ status: "REVIEW"; /** До этого времени Parallel решит диспут или попросит другую выписку. Если не успеет, диспут примется и заявка пересчитается на `received_amount` */ review_until: Timestamp; } export interface DisputeStatementRequired { /** Parallel просит другую выписку: что нужно, написано в `request` */ status: "STATEMENT_REQUIRED"; /** Какая выписка нужна и почему не подошла прежняя */ request: string; /** До этого времени загрузите выписку. Если её не будет, диспут отклонится */ statement_until: Timestamp; } export interface DisputeAccepted { /** Недостача подтвердилась: заявка перевыплачивается или пересчитана, как вы выбрали в `resolution` */ status: "ACCEPTED"; /** Решение Parallel текстом */ decision: string; closed_at: Timestamp; } export interface DisputeRejected { /** Выписка не подтвердила недостачу, заявка не изменилась */ status: "REJECTED"; /** Решение Parallel текстом */ decision: string; closed_at: Timestamp; } /** Открытый диспут по заявке на выход: заявка в статусе `DISPUTE`. */ export type OpenOutDispute = OutDisputeBase & (DisputeReview | DisputeStatementRequired); /** Решённый диспут по заявке на выход: заявка `PAID`, а при принятом `REPAY` — `IN_PROGRESS`. */ export type ClosedOutDispute = OutDisputeBase & (DisputeAccepted | DisputeRejected); /** Диспут по заявке на выход. Открываете вы, когда получателю пришло меньше, чем `paid_amount`. */ export type OutDispute = OpenOutDispute | ClosedOutDispute; /** * Тело `POST /api/v2/invoices/{invoice_id}/dispute`: `multipart/form-data`. Только для заявки на выход в статусе * `PAID`, один раз, не позже `dispute_days` из `GET /api/v2/sla` после `paid_at`. Открыть диспут можно, только если это * разрешено вашему магазину, иначе — `403 DISPUTE_DISABLED`. Ответ — `OutInvoice` в статусе `DISPUTE`. */ export interface OpenDisputeRequest { /** Сколько, по словам клиента, пришло получателю; `"0"` — ничего */ received_amount: Rub; /** Что сделать с заявкой: `REPAY` — перевести получателю недостающее, `RECALCULATE` — пересчитать заявку */ resolution: DisputeResolution; /** Выписка получателя из банка за день перевода: PDF или изображение, до 10 МБ */ file: Blob; /** Комментарий, если нужен */ message?: string; } /** * Тело `POST /api/v2/invoices/{invoice_id}/dispute/statements`: `multipart/form-data`. Новая выписка, когда диспут в * статусе `STATEMENT_REQUIRED`. Ответ — `OutInvoice`, диспут снова в статусе `REVIEW`. */ export interface UploadStatementRequest { /** Выписка получателя из банка: PDF или изображение, до 10 МБ */ file: Blob; /** Комментарий, если нужен */ message?: string; } // ─── Список заявок ────────────────────────────────────────────────────────── /** Параметры `GET /api/v2/invoices`. Все необязательные. Заявки идут от новых к старым. */ export interface ListInvoicesQuery { /** Только заявки на вход или только на выход */ direction?: "IN" | "OUT"; /** Только заявки в этом статусе: `"PAID"` */ status?: Invoice["status"]; /** Созданные не раньше этого времени */ created_from?: Timestamp; /** Созданные раньше этого времени */ created_to?: Timestamp; /** Сколько заявок вернуть: от 1 до 100, по умолчанию 50 */ limit?: number; /** Значение `next_cursor` из прошлого ответа, чтобы получить следующую страницу */ cursor?: string; } /** Ответ `GET /api/v2/invoices`. */ export interface InvoiceList { items: Invoice[]; /** Есть, если заявки ещё остались: передайте его в `cursor` */ next_cursor?: string; } // ─── Баланс, ввод и вывод USDT ────────────────────────────────────────────── /** Ответ `GET /api/v2/balance`: баланс магазина в USDT. */ export interface Balance { currency: "USDT"; /** Доступный баланс: им оплачиваются заявки на выход, его можно вывести */ available: Usdt; /** Заморожено: выводы в обработке, незавершённые заявки на выход и зачисления по открытым диспутам */ frozen: Usdt; /** Адрес для пополнения баланса в сети TRC-20 */ deposit_address?: string; } /** Тело `POST /api/v2/withdrawals`. Ответ `201` — `Withdrawal`. */ export interface CreateWithdrawalRequest { /** Сколько USDT списать с баланса: не больше `available` */ amount: Usdt; /** Адрес вашего кошелька USDT в сети TRC-20 */ address: string; } /** Операция с USDT на балансе: пополнение или вывод. Элемент ответа `GET /api/v2/balance/operations`. */ export type BalanceOperation = Deposit | Withdrawal; /** Пополнение баланса: USDT пришли на `deposit_address`. */ export interface Deposit { /** Номер операции в Parallel */ operation_id: string; /** `DEPOSIT` — пополнение */ type: "DEPOSIT"; /** Сколько USDT зачислено */ amount: Usdt; network: "TRC20"; /** Адрес, на который пришли USDT */ address: string; /** Когда перевод появился в сети */ created_at: Timestamp; /** Зачислено на баланс */ status: "COMPLETED"; /** Номер транзакции в сети */ tx_hash: string; /** Когда сумма зачислена на баланс */ completed_at: Timestamp; } /** Вывод USDT с баланса на ваш кошелёк. */ export type Withdrawal = WithdrawalBase & (WithdrawalPending | WithdrawalCompleted | WithdrawalCanceled); export interface WithdrawalBase { /** Номер операции в Parallel */ operation_id: string; /** `WITHDRAWAL` — вывод */ type: "WITHDRAWAL"; /** Сколько USDT списано с баланса */ amount: Usdt; /** Комиссия сети, её платите вы: на кошелёк придёт `amount` минус `fee` */ fee: Usdt; network: "TRC20"; /** Адрес вашего кошелька */ address: string; created_at: Timestamp; } export interface WithdrawalPending { /** Вывод в обработке, сумма заморожена */ status: "PENDING"; } export interface WithdrawalCompleted { /** USDT отправлены на ваш кошелёк */ status: "COMPLETED"; /** Номер транзакции в сети */ tx_hash: string; completed_at: Timestamp; } export interface WithdrawalCanceled { /** Вывод отменён, сумма вернулась в `available` */ status: "CANCELED"; /** Почему отменён */ message: string; canceled_at: Timestamp; } /** Параметры `GET /api/v2/balance/operations`. Все необязательные. Операции идут от новых к старым. */ export interface ListBalanceOperationsQuery { /** Только пополнения или только выводы */ type?: "DEPOSIT" | "WITHDRAWAL"; /** Сколько операций вернуть: от 1 до 100, по умолчанию 50 */ limit?: number; /** Значение `next_cursor` из прошлого ответа, чтобы получить следующую страницу */ cursor?: string; } /** Ответ `GET /api/v2/balance/operations`. */ export interface BalanceOperationList { items: BalanceOperation[]; /** Есть, если операции ещё остались: передайте его в `cursor` */ next_cursor?: string; } // ─── Файлы: чеки и видео оплаты ───────────────────────────────────────────────────── /** Файл по заявке: чек или видео оплаты. Ответ на загрузку и элемент `attachments` заявки. */ export type Attachment = AttachmentBase & (Checking | Passed | Failed); export interface AttachmentBase { /** Номер файла в Parallel */ attachment_id: string; /** PDF — чек из банка, IMAGE — скриншот, VIDEO — видео оплаты */ type: "PDF" | "IMAGE" | "VIDEO"; file_name: string; /** Ссылка на файл, действует 7 дней */ file_url: string; received_at: Timestamp; } export interface Checking { /** Файл на проверке, результат придёт на Webhook */ status: "CHECKING"; } export interface Passed { /** Файл подтверждает оплату */ status: "PASSED"; checked_at: Timestamp; /** Что прочитано из файла. Есть, если файл удалось прочитать */ transfer?: Transfer; } export interface Failed { /** Файл не подтверждает оплату, почему — в `failure_reason` */ status: "FAILED"; checked_at: Timestamp; failure_reason: AttachmentFailureReason; transfer?: Transfer; } export interface AttachmentFailureReason { /** * - `FAKE` — файл похож на подделку; * - `UNREADABLE` — не удалось распознать банк или формат; * - `NOT_COMPLETED` — перевод не завершён: например, «В обработке»; банк может его отменить; * - `WRONG_RECIPIENT` — перевод на другие реквизиты; * - `DUPLICATE` — этим чеком уже закрыта другая заявка */ code: | "FAKE" | "UNREADABLE" | "NOT_COMPLETED" | "WRONG_RECIPIENT" | "DUPLICATE"; message: string; } /** Перевод, как он прочитан из файла. Что не прочиталось — `null`. */ export interface Transfer { /** Сумма перевода */ amount: Rub | null; /** Время перевода */ at: Timestamp | null; /** Статус перевода в чеке как есть, словами банка: `"Успешно"`, `"В обработке"` */ bank_status: string | null; /** Номер операции в банке */ operation_id: string | null; /** Отправитель: банк и имя */ from: { bank: BankCode | null; name: string | null }; /** Получатель: куда ушёл перевод */ to: { method: Method | null; bank: BankCode | null; name: string | null; phone_number: string | null; card_number: string | null; }; } // ─── Действия с заявкой ───────────────────────────────────────────────────── /** * Тело `POST /api/v2/invoices/{invoice_id}/attachments`: `multipart/form-data` с одним полем `file`. * PDF и изображения (JPG, PNG) — до 10 МБ, видео (MP4, MOV, WebM) — до 50 МБ. Ответ `201` — `Invoice`: заявка целиком, * загруженный файл — последний в `attachments`. PDF и скриншот проверяем сразу: в ответе файл уже `PASSED` (его сумма * добавлена в `paid_amount`; подтверждена вся сумма заявки — заявка `PAID`, часть — `IN_PROGRESS`) или `FAILED` с `failure_reason`. Видео оплаты проверяем до `review_until`: файл `CHECKING`, заявка `REVIEW`, * результат придёт на Webhook. */ export interface UploadAttachmentRequest { file: Blob; } /** * Тело `POST /api/v2/invoices/{invoice_id}/take_financial_responsibility`. Ответ — `Invoice` в статусе `PAID`. * Повтор с той же суммой возвращает ту же заявку; с другой — `409 FINANCIAL_RESPONSIBILITY_ALREADY_TAKEN`. */ export interface TakeFinancialResponsibilityRequest { /** На сколько рублей зачитывается вся заявка: больше уже подтверждённого чеками `paid_amount` и не больше суммы заявки */ amount: Rub; } // ─── Условия магазина ─────────────────────────────────────────────────────── /** Ответ `GET /api/v2/sla`: условия вашего магазина. Их задаёт Parallel. */ export interface Sla { /** Номер вашего магазина в Parallel */ shop_id: string; /** Название вашего магазина */ shop_name: string; /** `true` — запрос с тестовым токеном: деньги не настоящие */ testnet: boolean; /** Заявки на выход (OUT) */ out?: { /** Курс USDT/RUB, по которому сейчас создастся заявка */ rate: string; /** За сколько минут мы переводим деньги получателю: `pay_until` */ pay_minutes: number; /** Сколько дней после `paid_at` можно открыть диспут. Есть, только если диспуты разрешены вашему магазину */ dispute_days?: number; /** За сколько минут Parallel проверяет выписку (`review_until`); столько же у вас на другую выписку (`statement_until`). Есть, только если диспуты разрешены вашему магазину */ dispute_minutes?: number; }; /** Заявки на вход (IN) */ in: { /** Курс USDT/RUB, по которому сейчас создастся заявка */ rate: string; /** Как к нам попадёт чек, если не указать `receipt_delivery` при создании заявки */ default_receipt_delivery: ReceiptDelivery; /** Сколько минут заявка ждёт реквизиты в статусе `NEW`: `requisites_until`. `0` — не ждёт: если реквизитов сразу нет, ответ `503 NO_REQUISITES` */ requisites_wait_minutes: number; /** Сколько минут у клиента на оплату: `pay_until` */ pay_minutes: number; /** Сколько минут мы проверяем видео оплаты: `review_until` */ review_minutes: number; /** Сколько минут у клиента на дополнительное доказательство оплаты: `proof_until` */ proof_minutes: number; /** * Способы подтвердить оплату, подключённые вашему магазину, от самого надёжного к менее надёжному: * - `FINANCIAL_RESPONSIBILITY` — взять оплату под финансовую ответственность; * - `BANK_EMAIL` — чек на почту заявки (`receipt_delivery: "BANK_EMAIL"`); * - `VIDEO` — видео оплаты; * - `PDF` — чек PDF из банка. */ proof_options: ( | "FINANCIAL_RESPONSIBILITY" | "BANK_EMAIL" | "VIDEO" | "PDF" )[]; }; } /** Элемент ответа `GET /api/v2/banks`. */ export interface Bank { code: BankCode; /** Название банка для клиента */ name: string; } // ─── Webhook ──────────────────────────────────────────────────────────────── /** Событие по заявке на вход. */ export type InEventType = /** Реквизиты выданы заявке, которая их ждала: заявка `IN_PROGRESS` с `requisites` */ | "invoice.in.requisites_issued" /** Пришёл файл, который проверяется не сразу: видео или чек с почты. Заявка `REVIEW` */ | "invoice.in.attachment_received" /** Чек не подтвердил оплату, а дополнительное доказательство по заявке не запрашивается (чек на почту или магазину оно не подключено). Заявка снова `IN_PROGRESS`, ждём другой чек */ | "invoice.in.attachment_rejected" /** Чек не подтвердил оплату: нужно видео или финансовая ответственность. Заявка `PROOF_REQUIRED` */ | "invoice.in.proof_required" /** Чек подтвердил часть суммы: заявка `IN_PROGRESS` с `paid_amount`, клиент может доплатить до `pay_until` */ | "invoice.in.partially_paid" /** Оплачена: заявка `PAID` */ | "invoice.in.paid" /** Срок вышел без оплаты: заявка `EXPIRED` */ | "invoice.in.expired" /** Отменена: заявка `CANCELED` */ | "invoice.in.canceled" /** Parallel открыл диспут: заявка `DISPUTE` */ | "invoice.in.dispute.opened" /** Диспут решён: заявка `PAID` или `CHARGEBACK` */ | "invoice.in.dispute.closed"; /** Событие по заявке на выход. */ export type OutEventType = /** Новый чек перевода: в `receipts` добавился чек, `paid_amount` вырос */ | "invoice.out.receipt_added" /** Переводы закончены: заявка `PAID`. Чек последнего перевода приходит в этом же событии */ | "invoice.out.paid" /** К `pay_until` не переведено ничего: заявка `EXPIRED` */ | "invoice.out.expired" /** Реквизиты получателя не принимают перевод: заявка `CANCELED` */ | "invoice.out.canceled" /** Вы открыли диспут: заявка `DISPUTE` */ | "invoice.out.dispute.opened" /** Parallel просит другую выписку: `dispute.status` — `STATEMENT_REQUIRED`, что нужно — в `dispute.request` */ | "invoice.out.dispute.statement_required" /** Вы загрузили выписку, которую попросили: `dispute.status` снова `REVIEW` */ | "invoice.out.dispute.statement_received" /** Диспут решён: `dispute.status` — `ACCEPTED` или `REJECTED` */ | "invoice.out.dispute.closed"; export type EventType = InEventType | OutEventType; /** * На что подписаться: тип события или его начало до точки — все события группы. `invoice` — все события, * `invoice.in` — по приёму, `invoice.out` — по выплатам, `invoice.in.dispute` и `invoice.out.dispute` — по диспутам. */ export type EventFilter = | EventType | "invoice" | "invoice.in" | "invoice.out" | "invoice.in.dispute" | "invoice.out.dispute"; /** * Событие: что произошло с заявкой. Приходит `POST {url}` с заголовками `X-Webhook-Signature` (HMAC-SHA256 тела * ключом `secret`, hex) и `X-Webhook-Delivery-Id` (равен `event_id`). Успех — любой ответ `2xx`; иначе повторяем * то же событие через 1, 5, 30 минут, 2, 6 и 12 часов. События по одной заявке приходят по порядку. */ export interface WebhookEvent { /** Номер события */ event_id: string; type: EventType; /** Когда произошло событие */ created_at: Timestamp; data: { /** Заявка на момент события */ object: Invoice; /** * Прежние значения полей, которые изменились в заявке. */ previous?: Record; }; } /** Подписка магазина: ответ `GET`, `PUT /api/v2/webhook_subscription` и `POST /api/v2/webhook_subscription/secret`. */ export interface WebhookSubscription { /** HTTPS-адрес, на который приходят события */ url: string; /** На какие события подписаны. Пустой список — на все */ events: EventFilter[]; /** Ключ подписи. Создаётся при первой настройке */ secret: string; } /** Тело `PUT /api/v2/webhook_subscription`. */ export interface SetWebhookSubscriptionRequest { url: string; /** Типы событий или группы: `["invoice.in"]` — все события приёма. Без поля или пустой список — все события */ events?: EventFilter[]; } // ─── Методы ───────────────────────────────────────────────────────────────── /** Параметр пути `{bank}`. */ export interface BankPath { /** Код или название банка */ bank: BankName; } /** Параметр пути `{invoice_id}`. */ export interface InvoicePath { /** Номер заявки в Parallel: `invoice_id` из ответа на создание */ invoice_id: string; } /** * Методы API v2: ключ — HTTP-метод и путь, значение — что метод принимает и возвращает. Из них собирается * спецификация OpenAPI: `/openapi.json`. * * Первая строка JSDoc метода — его название, остальное — описание. Поля значения: * - `path` — параметры пути, `query` — параметры запроса; * - `body` — тело запроса: `multipart/form-data`, если в нём есть файл, иначе JSON; * - `responses` — успешные ответы по HTTP-коду; * - `errors` — коды ошибок метода. `UNAUTHORIZED`, `SHOP_NOT_ACTIVATED` и `UNAVAILABLE` может вернуть любой метод, * здесь их нет. */ export interface Api { /** * Создать заявку * * Создаёт заявку на вход или на выход: их различает поле `direction`. Повторный запрос с тем же `internal_id` не * создаёт новую заявку, а возвращает уже созданную. */ "POST /api/v2/invoices": { body: CreateInvoiceRequest | CreateOutInvoiceRequest; responses: { /** Заявка создана */ 201: Invoice; /** Заявка с этим `internal_id` уже есть: в ответе она */ 200: Invoice; }; errors: | "VALIDATION_ERROR" | "DIRECTION_DISABLED" | "RECEIPT_DELIVERY_DISABLED" | "BANK_CHOICE_DISABLED" | "METHOD_CHOICE_DISABLED" | "NO_REQUISITES" | "INSUFFICIENT_BALANCE"; }; /** * Список заявок * * Возвращает заявки магазина, на вход и на выход, от новых к старым. */ "GET /api/v2/invoices": { query: ListInvoicesQuery; responses: { 200: InvoiceList; }; }; /** * Получить заявку * * Возвращает заявку на вход или на выход. */ "GET /api/v2/invoices/{invoice_id}": { path: InvoicePath; responses: { 200: Invoice; }; errors: "NOT_FOUND"; }; /** * Загрузить чек или видео оплаты * * Загружает файл по заявке на вход: чек или видео оплаты. * * | Файл | Форматы | Размер | Проверка | * | - | - | - | - | * | Чек | PDF | до 10 МБ | Сразу. В ответе заявка уже `PAID` или `PROOF_REQUIRED` | * | Скриншот | JPG, PNG | до 10 МБ | Оплату не подтверждает. Заявка переходит в `PROOF_REQUIRED` | * | Видео оплаты | MP4, MOV, WebM | до 50 МБ | До `review_until`. В ответе заявка `REVIEW`, результат приходит на Webhook | */ "POST /api/v2/invoices/{invoice_id}/attachments": { path: InvoicePath; body: UploadAttachmentRequest; responses: { /** Заявка на вход: загруженный файл стоит последним в `attachments` */ 201: InInvoice; }; errors: | "NOT_FOUND" | "INVALID_STATUS" | "RECEIPT_DELIVERY_IS_BANK_EMAIL" | "PROOF_OPTION_DISABLED" | "FILE_TOO_LARGE" | "UNSUPPORTED_FILE"; }; /** * Взять заявку под финансовую ответственность * * Зачитывает заявку на вход под вашу финансовую ответственность. Доступно, пока заявка не закрыта: в статусах * `IN_PROGRESS`, `REVIEW` и `PROOF_REQUIRED`. Взять заявку под финансовую ответственность можно один раз: повтор с той * же суммой возвращает ту же заявку. */ "POST /api/v2/invoices/{invoice_id}/take_financial_responsibility": { path: InvoicePath; body: TakeFinancialResponsibilityRequest; responses: { /** Заявка на вход в статусе `PAID` */ 200: InInvoice; }; errors: | "VALIDATION_ERROR" | "NOT_FOUND" | "INVALID_STATUS" | "FINANCIAL_RESPONSIBILITY_ALREADY_TAKEN" | "RECEIPT_DELIVERY_IS_BANK_EMAIL" | "PROOF_OPTION_DISABLED"; }; /** * Отменить заявку * * Отменяет заявку на вход. Отменить можно в статусе `NEW` или `IN_PROGRESS`, пока по заявке не загружено ни одного * файла. Тела у запроса нет. Заявку на выход отменить нельзя. */ "POST /api/v2/invoices/{invoice_id}/cancel": { path: InvoicePath; responses: { /** Заявка на вход в статусе `CANCELED` */ 200: InInvoice; }; errors: "NOT_FOUND" | "INVALID_STATUS"; }; /** * Открыть диспут * * Открывает диспут по заявке на выход в статусе `PAID`: получателю пришло меньше, чем в `paid_amount`. Открыть диспут * можно, только если это разрешено вашему магазину. */ "POST /api/v2/invoices/{invoice_id}/dispute": { path: InvoicePath; body: OpenDisputeRequest; responses: { /** Заявка на выход в статусе `DISPUTE` */ 200: OutInvoice; }; errors: | "VALIDATION_ERROR" | "NOT_FOUND" | "INVALID_STATUS" | "DISPUTE_DISABLED" | "DISPUTE_ALREADY_OPENED" | "DISPUTE_WINDOW_CLOSED" | "FILE_TOO_LARGE" | "UNSUPPORTED_FILE"; }; /** * Загрузить выписку по диспуту * * Добавляет выписку к диспуту, когда Parallel попросил другую: диспут в статусе `STATEMENT_REQUIRED`. */ "POST /api/v2/invoices/{invoice_id}/dispute/statements": { path: InvoicePath; body: UploadStatementRequest; responses: { /** Заявка на выход в статусе `DISPUTE`, диспут в статусе `REVIEW` */ 200: OutInvoice; }; errors: | "VALIDATION_ERROR" | "NOT_FOUND" | "INVALID_STATUS" | "FILE_TOO_LARGE" | "UNSUPPORTED_FILE"; }; /** * Баланс * * Возвращает баланс магазина. */ "GET /api/v2/balance": { responses: { 200: Balance; }; }; /** * Вывести USDT * * Создаёт вывод USDT на ваш кошелёк. */ "POST /api/v2/withdrawals": { body: CreateWithdrawalRequest; responses: { 201: Withdrawal; }; errors: "VALIDATION_ERROR" | "INSUFFICIENT_BALANCE"; }; /** * История пополнений и выводов * * Возвращает пополнения и выводы USDT, от новых к старым. */ "GET /api/v2/balance/operations": { query: ListBalanceOperationsQuery; responses: { 200: BalanceOperationList; }; }; /** * Условия магазина и курс * * Возвращает условия вашего магазина и текущий курс. */ "GET /api/v2/sla": { responses: { 200: Sla; }; }; /** * Список банков * * Возвращает все банки, которые знает Parallel, с кодами для поля `bank`. */ "GET /api/v2/banks": { responses: { 200: Bank[]; }; }; /** * Найти банк * * Возвращает банк по коду или названию, как его поймёт Parallel в поле `bank`: `GET /api/v2/banks/Сбер`. */ "GET /api/v2/banks/{bank}": { path: BankPath; responses: { 200: Bank; }; errors: "NOT_FOUND"; }; /** * Подписаться на события * * Задаёт адрес и события, которые на него приходят. Без `events` подписка идёт на все события. */ "PUT /api/v2/webhook_subscription": { body: SetWebhookSubscriptionRequest; responses: { 200: WebhookSubscription; }; errors: "VALIDATION_ERROR"; }; /** * Текущая подписка * * Возвращает адрес, события и ключ подписи. */ "GET /api/v2/webhook_subscription": { responses: { 200: WebhookSubscription; }; errors: "WEBHOOK_NOT_SET"; }; /** * Сменить ключ подписи * * Выпускает новый ключ подписи. Все следующие события подписаны им. Тела у запроса нет. */ "POST /api/v2/webhook_subscription/secret": { responses: { /** Подписка с новым `secret` */ 200: WebhookSubscription; }; errors: "WEBHOOK_NOT_SET"; }; }