SDK Ruby para España
Gem Ruby corp_merch — cliente idiomático, Rails-aware y Sidekiq-friendly para España.
Arquitectura — Instalación e init para España
Añade gem 'corp_merch' al Gemfile y bundle install. Init: cm = CorpMerch.new(api_key: ENV['CM_KEY'], country: 'España'). El flag country aplica IVA 21% y enruta facturas vía FACe/SII (hub Madrid). En Rails hay generador corp_merch:install. Ruby 3.1+. Thread-safe, sin estado global.
Cómo integrarlo — Quickstart con Sidekiq
En un worker de Sidekiq: cm.orders.create(idempotency_key: jid, buyer: {vat_id: 'EU…'}, lines: [{sku: 'TSH-001', qty: 200}], promised_date: 2.weeks.from_now). Los retries de Sidekiq son seguros porque idempotency_key es jid. Errores como excepciones tipadas: CorpMerch::ValidationError, CorpMerch::RateLimitError (respeta Retry-After). HTTP vía Net::HTTP — sin Faraday ni HTTParty.
Operación y casos límite — Verificación de webhook (Rails)
En un controller: event = CorpMerch::Webhook.construct_event(request.raw_post, request.headers['X-Corp-Signature'], ENV['CM_WEBHOOK_SECRET']). Lanza SignatureVerificationError ante firma inválida; Rails responde 400. Ficheros Sorbet RBI bajo sig/ para type-check completo con srb tc o tapioca. IDs de confirmación FACe / Suministro Inmediato de Información (SII) expuestos en objetos de evento de factura.
Preguntas frecuentes
¿Rails 7 / 8 soportados?
Sí — probados Rails 7.1, 7.2 y 8.0. Versiones anteriores funcionan pero no están en CI.
¿Tipos Sorbet?
Ficheros RBI bajo sig/. Probado con srb tc; tapioca genera RBIs de terceros para tu proyecto.
¿Reintentos de Sidekiq?
Idempotency-safe con jid; recomendamos retry: 5 para la mayoría de workers. RateLimitError respeta Retry-After.
¿Múltiples cuentas?
Instancia varios clientes CorpMerch — wrapper fino, thread-safe, sin estado global.
¿IVA 21% y FACe/SII?
Calculados en servidor desde el param country ('España'). Los eventos de factura exponen ids FACe/SII en payloads de webhook.