SDK Ruby para Portugal
Gem Ruby corp_merch — cliente idiomático, Rails-aware e Sidekiq-friendly para Portugal.
Arquitectura — Instalação e init para Portugal
Adiciona gem 'corp_merch' ao Gemfile e bundle install. Init: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'Portugal'). A flag country aplica IVA 23% e encaminha facturas via AT (hub Lisboa). Em Rails há gerador corp_merch:install. Ruby 3.1+. Thread-safe, sem estado global.
Como integrar — Quickstart com Sidekiq
Num worker Sidekiq: cm.orders.create(idempotency_key: jid, buyer: {vat_id: 'EU…'}, lines: [{sku: 'TSH-001', qty: 200}], promised_date: 2.weeks.from_now). Retries do Sidekiq são seguros porque idempotency_key é jid. Erros como excepções tipadas: CorpMerch::ValidationError, CorpMerch::RateLimitError (respeita Retry-After). HTTP via Net::HTTP — sem Faraday nem HTTParty.
Operação e casos extremos — Verificação de webhook (Rails)
Num controlador: event = CorpMerch::Webhook.construct_event(request.raw_post, request.headers['X-Corp-Signature'], ENV['CM_WEBHOOK_SECRET']). Lança SignatureVerificationError em assinatura inválida; o Rails responde 400. Ficheiros Sorbet RBI em sig/ para type-check completo com srb tc ou tapioca. IDs de notificação Portal das Finanças (AT) expostos nos objectos de evento de factura.
Perguntas frequentes
Rails 7 / 8 suportados?
Sim — testados Rails 7.1, 7.2 e 8.0. Versões anteriores funcionam mas não estão em CI.
Tipos Sorbet?
Ficheiros RBI em sig/. Testado com srb tc; tapioca gera RBIs de terceiros para o teu projecto.
Retries Sidekiq?
Idempotency-safe com jid; recomendamos retry: 5 para a maioria dos workers. RateLimitError respeita Retry-After.
Múltiplas contas?
Instancia vários clientes CorpMerch — wrapper fino, thread-safe, sem estado global.
IVA 23% e AT?
Calculados no servidor a partir do param country ('Portugal'). Os eventos de factura expõem ids AT nos payloads de webhook.