Ruby SDK в Италии
Ruby gem corp_merch — идиоматичный клиент с поддержкой Rails и Sidekiq в Италии.
Архитектура — Установка и инициализация в Италии
Добавьте gem 'corp_merch' в Gemfile и выполните bundle install. Инициализация: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Италия'). Флаг country автоматически применяет IVA 22% и направляет счета через SdI (хаб в Милане). Для 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 подтверждений Sistema di Interscambio (SdI) доступны на объектах событий счёта.
Частые вопросы
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, потокобезопасно, без глобального состояния.
IVA 22% и SdI?
Считаются на сервере на основе параметра country ('Италия'). События счетов содержат id SdI в payload-ах webhook.