Ruby SDK for Spain
corp_merch Ruby gem — idiomatic, Rails-aware, Sidekiq-friendly client for Spain.
Architecture — Install and initialise for Spain
Add gem 'corp_merch' to your Gemfile and bundle install. Initialise: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Spain'). The country flag auto-applies IVA 21% and routes invoices through FACe/SII (Madrid 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. FACe / Suministro Inmediato de Información (SII) 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.
IVA 21% and FACe/SII?
Computed server-side based on the client's country param ('Spain'). Invoice events surface FACe/SII ids in webhook payloads.