Ruby SDK for Poland
corp_merch Ruby gem — idiomatic, Rails-aware, Sidekiq-friendly client for Poland.
Architecture — Install and initialise for Poland
Add gem 'corp_merch' to your Gemfile and bundle install. Initialise: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Poland'). The country flag auto-applies VAT 23% and routes invoices through KSeF (Warszawa hub). For Rails, an initializer template ships in the corp_merch:install generator. Ruby 3.1+. Threadsafe, no global state.
How to wire it up — Quickstart with Sidekiq
In a Sidekiq worker: cm.orders.create(idempotency_key: jid, buyer: {vat_id: 'EU…'}, lines: [{sku: 'TSH-001', qty: 200}], promised_date: 2.weeks.from_now). Sidekiq retries are safe because idempotency_key is the job id. Errors raise typed exceptions: CorpMerch::ValidationError, CorpMerch::RateLimitError (retries respect Retry-After). HTTP via Net::HTTP — no Faraday or HTTParty dependency.
Operations and edge cases — Webhook verification (Rails)
In a controller: event = CorpMerch::Webhook.construct_event(request.raw_post, request.headers['X-Corp-Signature'], ENV['CM_WEBHOOK_SECRET']). Raises SignatureVerificationError on bad signature; Rails turns it into 400. Sorbet RBI files shipped under sig/ for full type-checking with srb tc or tapioca. Krajowy System e-Faktur (KSeF) acknowledgement ids exposed on invoice event objects.
FAQ
Rails 7 / 8 supported?
Yes — tested against Rails 7.1, 7.2 and 8.0. Earlier versions of Rails work but are not in CI.
Sorbet types?
RBI files shipped under sig/. Tested with srb tc; tapioca generates third-party RBIs for your project.
Sidekiq retries?
Idempotency-safe with jid; we recommend Sidekiq retry: 5 for most workers. RateLimitError respects Retry-After.
Multiple accounts?
Instantiate multiple CorpMerch clients — each is a thin wrapper, thread-safe, no global state.
VAT 23% and KSeF?
Computed server-side based on the client's country param ('Poland'). Invoice events surface KSeF ids in webhook payloads.