Ruby SDK в Польше
Ruby gem corp_merch — идиоматичный клиент с поддержкой Rails и Sidekiq в Польше.
Архитектура — Установка и инициализация в Польше
Добавьте gem 'corp_merch' в Gemfile и выполните bundle install. Инициализация: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Польша'). Флаг country автоматически применяет VAT 23% и направляет счета через KSeF (хаб в Варшаве). Для Rails — генератор corp_merch:install. Ruby 3.1+. Потокобезопасно, без глобального состояния.
Как подключить — Быстрый старт с Sidekiq
В Sidekiq-воркере: cm.orders.create(idempotency_key: jid, buyer: {vat_id: 'EU…'}, lines: [{sku: 'TSH-001', qty: 200}], promised_date: 2.weeks.from_now). Повторы Sidekiq безопасны: idempotency_key — это jid. Ошибки как типизированные исключения: CorpMerch::ValidationError, CorpMerch::RateLimitError (учитывает Retry-After). HTTP через Net::HTTP — без зависимостей Faraday и HTTParty.
Эксплуатация и пограничные случаи — Проверка webhook (Rails)
В контроллере: event = CorpMerch::Webhook.construct_event(request.raw_post, request.headers['X-Corp-Signature'], ENV['CM_WEBHOOK_SECRET']). Бросает SignatureVerificationError при неверной подписи; Rails возвращает 400. Файлы Sorbet RBI в sig/ для полной типизации через srb tc или tapioca. ID подтверждений Krajowy System e-Faktur (KSeF) доступны на объектах событий счёта.
Частые вопросы
Rails 7 / 8 поддерживается?
Да — тесты в CI для Rails 7.1, 7.2 и 8.0. Более ранние работают, но не входят в CI.
Типы Sorbet?
Файлы RBI в sig/. Проверено srb tc; tapioca генерирует RBI сторонних библиотек для вашего проекта.
Повторы Sidekiq?
Идемпотентно с jid; рекомендуем retry: 5 для большинства воркеров. RateLimitError учитывает Retry-After.
Несколько аккаунтов?
Создавайте несколько клиентов CorpMerch — тонкий wrapper, потокобезопасно, без глобального состояния.
VAT 23% и KSeF?
Считаются на сервере на основе параметра country ('Польша'). События счетов содержат id KSeF в payload-ах webhook.