Developers

Ордера и идемпотентность

Создание ордера фиксирует курс и назначает адрес депозита. Это единственное место, где ошибка интеграции перемещает деньги: идемпотентность там не удобство.

Опубликованный контракт, еще не открытый

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

POST/api/v1/ordersPublished contract, not open

Создать заказ

Фиксирует курс и возвращает выделенный адрес депозита. Заказ несет разбивку как зафиксированную: он воспроизводим, что позволяет восстановить точную примененную цену даже месяцы спустя. Заголовок Idempotency-Key обязателен.

Аутентификация: Authorization: Bearer … См. аутентификацию

Параметры

Параметры
Поле	Тип	Описание
`quoteId`обязательный	string	Идентификатор принятой котировки.
`beneficiary`обязательный	object	Поля, налагаемые схемой канала. Имя должно совпадать с проверенной личностью: выплаты третьим лицам запрещены.
`networkId`обязательный	string	Сеть, по которой будет отправлен депозит. Она определяет возвращаемый адрес и, в некоторых сетях, обязательный мемо.

Запросbash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

Ответ — опубликованный контрактjson

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

Мемо равно null в большинстве сетей и обязательно в XRP, Stellar и TON. Его пропуск там приводит к потере средств: относитесь к полю как к обязательному, как только оно не null.

Возможные ошибки: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Полный каталог

GET/api/v1/orders/{reference}Published contract, not open

Читать заказ

Текущее состояние и история переходов с метками времени. История — источник истины: она только добавляется, никогда не переписывается, и именно она отвечает на вопрос «почему мой заказ перешел в это состояние в это время».

Аутентификация: Authorization: Bearer … См. аутентификацию

Запросbash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Ответ — опубликованный контрактjson

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Возможные ошибки: unauthorized, not_found. Полный каталог

Идемпотентность

Запрос на создание, который истек по таймауту в сети, не сообщает вам, был ли создан ордер. Без ключа идемпотентности у вас есть только два плохих варианта: повторить и рисковать двумя ордерами, или не повторять и рисковать ни одним.

Заголовокhttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Один ключ на одно намерение

Ключ идентифицирует намерение «создать этот ордер», а не HTTP-запрос. Уникальный идентификатор на вашей стороне: идентификатор корзины, UUID, сгенерированный до вызова, никогда не счетчик.

Повтор возвращает исходный ответ

Повтор того же ключа с тем же телом возвращает ответ первого запроса с тем же HTTP-статусом. Это делает повтор безопасным, в том числе после таймаута.

Тот же ключ, другое тело: конфликт

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

Хранение в течение 24 часов

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

Мемо, в сетях, где оно требуется

В XRP, Stellar и TON адреса депозита недостаточно: дополнительный идентификатор обозначает конечного получателя. Это самая дорогостоящая причина инцидентов в интеграции вывода средств.

Депозит без мемо — потерянный депозит

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

Состояния ордера

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

Состояния ордера
Состояние	Что оно означает
`QUOTE_LOCKED`	Курс зафиксирован. Ордер ожидает данных бенефициара или проверки личности.
`AWAITING_DEPOSIT`	Адрес депозита назначен, и окно депозита открыто. Это единственный момент для отправки средств.
`DEPOSIT_DETECTED`	Входящая транзакция видна в сети, но еще не подтверждена. Успокойте пользователя, ничего не доставляйте.
`CONFIRMING`	Подтверждения накапливаются. Требуемое количество зависит от сети, а не от суммы.
`DEPOSIT_CONFIRMED`	Депозит защищен. Правила соответствия и перекотировки оцениваются отсюда.
`UNDERPAID`	Полученная сумма ниже ожидаемой сверх допустимого. Три исхода: пополнить, продолжить с полученной суммой или получить возврат.
`OVERPAID`	Полученная сумма превышает ожидаемую. Первоначальная сумма остается по зафиксированному курсу, излишек обрабатывается отдельно.
`PAYOUT_QUEUED`	Перевод поставлен в очередь. Очередь гарантирует, что выплата будет отправлена один раз, даже если несколько воркеров сработают параллельно.
`PAYOUT_SENT`	Перевод отправлен по каналу. Отправлено не означает получено: конечная задержка зависит от банка получателя.
`COMPLETED`	Расчет подтвержден каналом. Конечное состояние.
`PAYOUT_FAILED`	Канал отклонил или вернул перевод. Автоматического повтора нет: причина почти всегда в деталях.
`REFUNDED`	Средства возвращены на исходный адрес за вычетом комиссий сети. Конечное состояние.