Общие соглашения

Формат ответов

Все ответы имеют единую структуру-обёртку:

JSON API v3

Успешный ответ


{
  "success": true,
  "data": { ... }
}

Ответ с ошибкой


{
  "success": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with the specified ID was not found",
    "details": null
  }
}

Поля data и error взаимоисключающие — отсутствующее поле не сериализуется. В отдельных случаях details содержит структурированную информацию: например, details.invoice_id для INVOICE_ALREADY_EXISTS или details.contract_id для CONTRACT_ALREADY_EXISTS.

HTTP-коды ответов

HTTP-код	Значение
`200`	Успешная обработка
`201`	Ресурс создан (Invoice / Contract)
`202`	Запрос принят к обработке (Refund)
`400`	Невалидный запрос (ошибки валидации)
`401`	Ошибка аутентификации
`403`	Нет доступа к указанному проекту (IP не в whitelist, проект неактивен)
`404`	Ресурс не найден
`409`	Конфликт (напр. счёт уже существует)
`422`	Бизнес-логическая ошибка
`500`	Внутренняя ошибка платформы
`503`	Сервис временно недоступен

Типы данных

Тип	Формат JSON	Пример
`uuid`	string (UUID v4)	`"1624505c-0031-00cf-7d54-4cf1ce08cb30"`
`datetime`	string (ISO 8601, UTC)	`"2025-03-29T20:00:08Z"`
`money`	object — см. ниже	—
`currency`	string (ISO 4217)	`"RUB"`
`msisdn`	string (E.164 без `+`)	`"79600000000"`
`ip`	string (IPv4/IPv6)	`"10.20.30.40"`
`country`	string (ISO 3166-1 alpha-2)	`"RU"`

Денежные суммы

Все денежные значения представлены объектом money:


{
  "amount": "25.00",
  "currency": "RUB",
  "vat_included": true
}

amount — строка с фиксированной точкой (две цифры после точки). Передаётся строкой, чтобы избежать ошибок округления при работе с float.
currency — код валюты ISO 4217.
vat_included — флаг включения НДС в сумму.

Дополнительные параметры счёта

additional_parameters — произвольные пары «имя — значение» (строки), JSON-эквивалент блока <AdditionalParameters> из XML API. Через них передаются служебные флаги обработки, например NeedSendNotification, и собственные метки продавца.


{
  "additional_parameters": {
    "NeedSendNotification": "False"
  }
}

Блок принимают создание счёта — внутри order, — а также авторизация, отмена и возврат, где он лежит на верхнем уровне тела. Переданные значения дописываются к уже сохранённым у счёта, совпадающие по имени — перезаписываются.

Имена нечувствительны к регистру и должны быть уникальны: Flag и flag в одном объекте — ошибка запроса 400 BAD_REQUEST, а не два параметра.