Интеграция с 1С: приём платежей клуба

Платежи, принятые в клубе и проведённые в 1С (на стойке, по карте, за абонемент или бронь), попадают на кошелёк игрока в приложении AISOLUS Падел. 1С сама отправляет платежи в облако по расписанию — базу 1С не нужно публиковать наружу.

Как устроено

1. 1С по расписанию (или по кнопке) отправляет пачку новых платежей: POST /v1/integrations/1c/payments.
2. Облако ищет игрока по телефону из платежа. Найден — сумма зачисляется на его кошелёк, в истории кошелька появляется операция «Оплата в клубе · <назначение>».
3. Игрока с таким телефоном ещё нет — платёж сохраняется как несопоставленный и ждёт. Когда игрок зарегистрируется, 1С (или администратор) вызывает POST /v1/integrations/1c/payments/retry, и платёж зачисляется.
4. Для сверки 1С забирает список принятого облаком: GET /v1/integrations/1c/payments.

Доступ

Каждый запрос несёт заголовок X-1C-Token: <токен 1С>. Токен выдаёт администратор вашей платформы. Неверный токен или выключенная интеграция — 401 bad_1c_token.

Проверка связи и токена:

curl "https://адрес-вашего-сервера/api/v1/integrations/1c/ping" \
  -H "X-1C-Token: <токен 1С>"
# → {"ok": true, "payments": 128, "unmatched": 3}

Отправка платежей

За один запрос — от 1 до 500 платежей. Поля платежа:

curl -X POST "https://адрес-вашего-сервера/api/v1/integrations/1c/payments" \
  -H "X-1C-Token: <токен 1С>" \
  -H "Content-Type: application/json" \
  -d '{
  "payments": [
    {"ext_id": "00-000123", "phone": "+79000000001", "amount": 3500,
     "paid_at": "2026-10-02T10:15:00+03:00", "purpose": "Бронь корта", "kind": "booking"},
    {"ext_id": "00-000124", "phone": "8 (900) 000-00-02", "amount": 2000,
     "paid_at": "2026-10-02T10:20:00+03:00"}
  ]
}'

Ответ — итоги по пачке и результат по каждому платежу:

{
  "ok": true, "applied": 1, "unmatched": 1, "duplicate": 0, "rejected": 0,
  "items": [
    {"ext_id": "00-000123", "phone": "+79000000001", "amount": 3500, "kind": "booking",
     "purpose": "Бронь корта", "paid_at": "2026-10-02T10:15:00+03:00",
     "status": "applied", "error": "", "user_id": "3d6e9a10-…", "applied_at": "2026-10-02T07:15:04+00:00",
     "result": "applied"},
    {"ext_id": "00-000124", "phone": "+79000000002", "amount": 2000, "kind": "topup",
     "purpose": "", "paid_at": "2026-10-02T10:20:00+03:00",
     "status": "unmatched", "error": "no_user_with_phone", "user_id": null, "applied_at": null,
     "result": "unmatched"}
  ]
}

Статусы платежа

В ответе на отправку у каждого платежа есть ещё поле result: оно совпадает со статусом, а для уже принятого ранее ext_id равно duplicate — тогда в остальных полях возвращается сохранённая ранее запись.

Повторы и идемпотентность

• Платёж определяется полем ext_id. Повторная отправка того же ext_id ничего не зачисляет второй раз — результат duplicate.
• Поэтому при любой ошибке сети или таймауте пачку можно отправить заново целиком.
• Изменить уже принятый платёж повторной отправкой нельзя: облако вернёт сохранённую запись. Исправление — новым документом с новым ext_id.

Сопоставление по телефону

Телефон приводится к виду +7XXXXXXXXXX: из строки берутся цифры; 11 цифр, начинающихся с 7 или 8, и 10 цифр (без кода страны) понимаются как российский номер. Затем ищется игрок с ровно таким телефоном в профиле. Игрок регистрируется в приложении по тому же номеру — значит, телефон клиента в 1С должен совпадать с тем, с которым он входит в приложение.

Повторное сопоставление несопоставленных платежей:

curl -X POST "https://адрес-вашего-сервера/api/v1/integrations/1c/payments/retry" \
  -H "X-1C-Token: <токен 1С>"
# → {"ok": true, "checked": 3, "applied": 1}

Удобно вызывать его в том же расписании сразу после отправки новой пачки.

Сверка

Список принятых облаком платежей, новые первыми. Фильтры: status (applied, unmatched, rejected), since — время приёма облаком не раньше указанного, limit — от 1 до 1000 (по умолчанию 200).

curl "https://адрес-вашего-сервера/api/v1/integrations/1c/payments?status=unmatched&since=2026-10-01T00:00:00%2B03:00&limit=200" \
  -H "X-1C-Token: <токен 1С>"

Знак «+» в часовом поясе параметра since кодируйте как %2B, иначе он придёт пробелом.

На стороне 1С

Для проверки обмена у AISOLUS есть тестовая внешняя обработка 1С:Предприятие 8.3 (управляемые формы): она отправляет тестовый платёж, проверяет связь, повторно сопоставляет и показывает сверку. Модуль обработки предоставляет менеджер AISOLUS по запросу. Боевая выгрузка строится в конфигурации клуба по той же схеме: регламентное задание раз в несколько минут собирает документы оплаты, которые ещё не отправлены, и вызывает POST /v1/integrations/1c/payments через HTTPСоединение с защищённым соединением.

Порядок подключения:

1. Получить токен 1С у менеджера AISOLUS.
2. Проверить связь: GET /v1/integrations/1c/ping.
3. Отправить один тестовый платёж на телефон сотрудника, который вошёл в приложение, и убедиться, что сумма появилась в его кошельке.
4. Включить регулярную выгрузку и повторное сопоставление.