SDK Ruby dla Polska
Gem Ruby corp_merch — idiomatyczny klient Rails-aware i Sidekiq-friendly dla Polska.
Architektura — Instalacja i init dla Polska
Dodaj gem 'corp_merch' do Gemfile i bundle install. Init: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Polska'). Flaga country aplikuje VAT 23% i kieruje faktury przez KSeF (hub Warszawa). Dla Rails generator corp_merch:install. Ruby 3.1+. Thread-safe, brak globalnego stanu.
Jak to zintegrować — Quickstart z Sidekiq
W workerze Sidekiq: cm.orders.create(idempotency_key: jid, buyer: {vat_id: 'EU…'}, lines: [{sku: 'TSH-001', qty: 200}], promised_date: 2.weeks.from_now). Retry Sidekiqa są bezpieczne, bo idempotency_key to jid. Błędy jako typowane wyjątki: CorpMerch::ValidationError, CorpMerch::RateLimitError (respektuje Retry-After). HTTP przez Net::HTTP — bez Faraday i HTTParty.
Eksploatacja i przypadki brzegowe — Weryfikacja webhooka (Rails)
W kontrolerze: event = CorpMerch::Webhook.construct_event(request.raw_post, request.headers['X-Corp-Signature'], ENV['CM_WEBHOOK_SECRET']). Rzuca SignatureVerificationError przy złym podpisie; Rails zamienia na 400. Pliki Sorbet RBI w sig/ do type-check przez srb tc lub tapioca. ID potwierdzeń Krajowy System e-Faktur (KSeF) eksponowane na obiektach zdarzeń faktur.
FAQ
Wsparcie Rails 7 / 8?
Tak — testy w CI dla Rails 7.1, 7.2 i 8.0. Starsze działają, ale nie są w CI.
Typy Sorbet?
Pliki RBI w sig/. Testowane z srb tc; tapioca generuje RBI bibliotek zewnętrznych dla twojego projektu.
Retry Sidekiq?
Idempotency-safe z jid; rekomendujemy retry: 5 dla większości workerów. RateLimitError respektuje Retry-After.
Wielokonto?
Tworzymy wiele klientów CorpMerch — cienki wrapper, thread-safe, bez globalnego stanu.
VAT 23% i KSeF?
Liczone po stronie serwera z parametru country ('Polska'). Zdarzenia faktur eksponują id KSeF w payloadach webhooków.