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 23% и направляет счета через AT (хаб в Лиссабоне). Для 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 подтверждений Portal das Finanças (AT) доступны на объектах событий счёта.
Частые вопросы
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 23% и AT?
Считаются на сервере на основе параметра country ('Португалия'). События счетов содержат id AT в payload-ах webhook.