SDK Ruby per Italia
Gem Ruby corp_merch — client idiomatico, Rails-aware e Sidekiq-friendly per Italia.
Architettura — Installazione e init per Italia
Aggiungi gem 'corp_merch' al Gemfile e bundle install. Init: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Italia'). Il flag country applica IVA 22% e instrada le fatture tramite SdI (hub Milano). Su Rails generator corp_merch:install. Ruby 3.1+. Thread-safe, nessuno stato globale.
Come integrarlo — Quickstart con Sidekiq
In un worker Sidekiq: cm.orders.create(idempotency_key: jid, buyer: {vat_id: 'EU…'}, lines: [{sku: 'TSH-001', qty: 200}], promised_date: 2.weeks.from_now). I retry Sidekiq sono safe perché idempotency_key è jid. Errori come eccezioni tipizzate: CorpMerch::ValidationError, CorpMerch::RateLimitError (rispetta Retry-After). HTTP via Net::HTTP — niente Faraday o HTTParty.
Operatività e casi limite — Verifica webhook (Rails)
In un controller: event = CorpMerch::Webhook.construct_event(request.raw_post, request.headers['X-Corp-Signature'], ENV['CM_WEBHOOK_SECRET']). Solleva SignatureVerificationError su firma errata; Rails risponde 400. File Sorbet RBI in sig/ per type-check completo con srb tc o tapioca. ID di notifica Sistema di Interscambio (SdI) esposti sugli oggetti evento fattura.
Domande frequenti
Rails 7 / 8 supportati?
Sì — testati Rails 7.1, 7.2 e 8.0. Versioni precedenti funzionano ma non sono in CI.
Type Sorbet?
File RBI sotto sig/. Testato con srb tc; tapioca genera gli RBI di terze parti per il tuo progetto.
Retry Sidekiq?
Idempotency-safe con jid; consigliamo retry: 5 per la maggior parte dei worker. RateLimitError rispetta Retry-After.
Account multipli?
Istanzia più client CorpMerch — wrapper sottile, thread-safe, niente stato globale.
IVA 22% e SdI?
Calcolati lato server dal param country ('Italia'). Gli eventi fattura espongono id SdI nei payload webhook.