Основа для публикации backend-командой. Все адреса .invalid, карты, аптеки и ответы в примерах учебные. Публичный доступ к документации не даёт доступа к API; рабочий адрес и данные подключения выдаёт Олекстра.

Сооплата

Расчёт и подтверждение принимают JSON либо XML; отмена — только XML. Пространство имён XML: http://www.olekstra.ru/schema/cards. Для XML важны имена, порядок и кратность элементов; UTF-8 рекомендуется для новых интеграций.

Методы

Для пути без расширения формат выбирается по Content-Type; по умолчанию JSON. /invalidate.json и /check.ext.json текущим backend не объявлены. Не используйте их без отдельного подтверждённого контракта.

1. Расчёт

POST https://pos.example.invalid/check.json
Content-Type: application/json

{
  "drugstoreId": "999_DEMO_0001",
  "cardBarcode": "DEMO_CARD",
  "products": [
    {
      "clientPackId": "DEMO_SKU",
      "clientPackName": "Учебный товар",
      "barcode": "4600000000008",
      "quantity": 1,
      "price": "100.00"
    }
  ]
}

drugstoreId — полный код аптеки; префикс до второго символа «_» определяет бренд сети. products — массив строк; clientPackId и clientPackName обязательны, quantity — положительное целое число, price — неотрицательная цена. Для пересчёта передайте полученный voucherId. Штрихкод, известный Ekt и код товара сети — разные варианты опознания.

Структура успешного ответа (фрагмент)

{
  "voucherId": "00000000-0000-4000-8000-000000000001",
  "drugstoreId": "999_DEMO_0001",
  "confirmationToken": "00000000-0000-4000-8000-000000000002",
  "card": {
    "active": true,
    "comment": "",
    "checks": []
  },
  "sumToPay": "99.00",
  "rows": [],
  "complete": false
}

Это сокращённый учебный фрагмент. Ответ содержит сведения о карте, итогах и строках; деньги JSON в основных суммах передаются строками. Сохраните последний confirmationToken. Контрольных вопросов нет; JSON может содержать пустой checks: [].

2. Подтверждение

POST /confirm.json

{
  "drugstoreId": "999_DEMO_0001",
  "voucherId": "00000000-0000-4000-8000-000000000001",
  "confirmationToken": "00000000-0000-4000-8000-000000000002"
}

{
  "voucherId": "00000000-0000-4000-8000-000000000001",
  "authorizationCode": "123456"
}

Первое подтверждение — в течение 30 минут после последнего расчёта. Уже подтверждённый чек возвращает прежний код при повторе, даже после 30 минут. При смене карты внутри непробитого чека сервер выдаёт новый voucherId и токен, старые становятся недействительными; неподтверждённый расчёт по первой карте снимается. Это не установление личности владельца карт.

3. Возврат

POST /invalidate
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<invalidateRequest xmlns="http://www.olekstra.ru/schema/cards">
  <drugstoreId>999_DEMO_0001</drugstoreId>
  <voucherId>00000000-0000-4000-8000-000000000001</voucherId>
  <voucherDate>2026-10-16</voucherDate>
  <authorizationCode>123456</authorizationCode>
  <reason>Учебный возврат</reason>
</invalidateRequest>

Успех: invalidateResponse с атрибутом success="true". Окно возврата определяется программой. Ручное подтверждение просроченного чека и ввод задним числом в текущий профиль не входят.

Ошибки и неопределённый исход

Нельзя считать любой HTTP 200 успешным расчётом: бизнес-отказ check может быть текстом text/plain с HTTP 200. Проверяйте Content-Type и тело. Некорректный запрос — 400; неизвестный/закрытый чек, устаревший токен и позднее первое подтверждение — 409 на confirm. Истёкшее окно отмены — 403. Технический сбой или неизвестный исход фиксации — 503 с Retry-After: 1; повторяется та же операция с исходными идентификаторами, без создания новой продажи.

Exact и ограничения

Три exactSumToPay / exactRefundSum / exactNonRefundSum передаются вместе либо не передаются. Допускается плоская группа или exactFields, но не обе одновременно. Суммы ответа рассчитывает ядро. Поля Ext и отдельные методы не включаются по одному флажку в интерфейсе.

Адрес Сооплаты выдаётся для зарегистрированного имени подключения. Backend определяет вход по имени Host; настройки прокси и ограничения доступа согласуются с Олекстрой. Путь метода применяется к выданному адресу, имя из примера не является рабочим.