digiwin_dsp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfd6bd54cc74a0a92198baf85f66c940882a9ef23e9f8c957fcf1ce10e137725
+  data.tar.gz: 07f3727ce554845d88f989a89206ec814ce83e8ddbf3c3f9587f4ca60c3b6131
+SHA512:
+  metadata.gz: 21846a4c401f66c10df4f2fee23af8291c8c9819b64393285333762ddee19541fecc799dcc446f7e7d6b30d7529046ddbe221979dc043e3455aef141878d539e
+  data.tar.gz: dcd9694dd636c648a5e973980542a99eb476f421bb18d082934370749ca7d61a2473146183a54eda64d3d37d2e587f7f4147371eeccecb39e839c0125ddc6543

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `digiwin_dsp` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Release workflow (`.github/workflows/release.yml`): tag push (`v*`) triggers RubyGems publish via OIDC Trusted Publishing, runs the full spec suite as a guard, and updates the GitHub Release with the built `.gem` artifact.
+
+## [0.1.0] - 2026-05-21
+
+Initial release. Covers the four 自有官網模組 endpoints under `/v1/SalesOrder/*`.
+
+### Added
+
+- `DigiwinDsp.configure` block + per-setting ENV fallback (`DIGIWIN_DSP_API_KEY`, `DIGIWIN_DSP_API_SECRET`, `DIGIWIN_DSP_PLATFORM_ID`, `DIGIWIN_DSP_ENV`, `DIGIWIN_DSP_BASE_URL`)
+- `DigiwinDsp::Configuration` — UAT/production base URL resolver, timeout knobs, injectable logger, `#validate!` guard
+- `DigiwinDsp::Authenticator` — static `DSP-api-key` header
+- `DigiwinDsp::Client` — Faraday 2 connection with:
+  - `faraday-retry` for HTTP 429 / 5xx (3 attempts, exponential backoff)
+  - Path-prefix-safe URL joining (`/DSP_UAT/api/DSP` + `/v1/SalesOrder/add` → correct full URL)
+  - JSON serialization / parsing
+  - Status-code → exception mapping
+  - **Body-envelope `Status`/`Message` inspection** — DSP returns HTTP 200 even on failure, so the gem classifies `Duplicated:`, `Processing:`, `WrongStatus:`, `系統異常:` patterns into typed exceptions
+- Resources, all exposing `#create(records, idempotency_key:, digi_header:)`:
+  - `Resources::Order` → `POST /v1/SalesOrder/add`
+  - `Resources::Cancellation` → `POST /v1/SalesOrder/cancel`
+  - `Resources::Invoice` → `POST /v1/SalesOrder/invoice`
+  - `Resources::Return` → `POST /v1/SalesOrder/return`
+- Serializers with per-endpoint `REQUIRED_FIELDS` (22 / 8 / 11 / 19) sharing a `Serializers::Base` module that wraps records into the `digi_body.std_data.parameter.request.request_detail[]` envelope
+- Exception hierarchy: `Error`, `ConfigurationError`, `AuthenticationError`, `ValidationError`, `RateLimitError`, `ServerError`, `NetworkError`, `DuplicateRequestError` — each carrying `#code`, `#dsp_message`, `#http_status`, `#request_id`, `#response_body`
+- `docs/dsp-api-spec.md` summary + `docs/dsp-specs/DSPOOFFICIAL00{1,2,4,5}.yaml` (Digiwin's OpenAPI 3.1 source)
+- 134 RSpec examples, WebMock-driven, 100% line + 100% branch coverage, RuboCop clean
+
+### Tooling
+
+- SimpleCov + simplecov-lcov coverage reporting (line + branch); minimum thresholds 80% line / 70% branch
+- GitHub Actions CI workflow (`.github/workflows/ci.yml`): Ruby 3.2 / 3.3 / 3.4 matrix, runs RuboCop + RSpec, uploads `coverage/lcov.info` to Codecov on the 3.3 row
+- CI status + Codecov coverage badges in README
+
+### Design notes
+
+- `digi_header` is **omitted by default**; only passed through when caller provides a custom hash. Standard DSP traffic doesn't need it.
+- The gem is **synchronous on purpose**. Callers wrap requests in their own background job runner (e.g. ActiveJob) when needed.
+- Idempotency: clients can send `X-Idempotency-Key` via the `idempotency_key:` kwarg. DSP also dedupes server-side by `form_no + platform_id`.
+
+[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/7a6163/digiwin_dsp/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Zac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,216 @@
+# digiwin_dsp
+
+[![CI](https://github.com/7a6163/digiwin_dsp/actions/workflows/ci.yml/badge.svg)](https://github.com/7a6163/digiwin_dsp/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/7a6163/digiwin_dsp/branch/main/graph/badge.svg)](https://codecov.io/gh/7a6163/digiwin_dsp)
+[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.2-CC342D)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE.txt)
+
+Ruby client for the Digiwin DSP **自有官網模組** (Official Website Module) API. Lets a Rails 自有官網 push orders, cancellations, invoice updates, and returns into the Digiwin ERP through the DSP gateway.
+
+| Operation | Resource | Endpoint |
+|---|---|---|
+| 新增訂單 | `DigiwinDsp::Resources::Order` | `POST /v1/SalesOrder/add` |
+| 取消訂單 | `DigiwinDsp::Resources::Cancellation` | `POST /v1/SalesOrder/cancel` |
+| 發票更新 | `DigiwinDsp::Resources::Invoice` | `POST /v1/SalesOrder/invoice` |
+| 退貨 | `DigiwinDsp::Resources::Return` | `POST /v1/SalesOrder/return` |
+
+See [`docs/dsp-api-spec.md`](./docs/dsp-api-spec.md) (plus `docs/dsp-specs/*.yaml`) for the wire spec.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "digiwin_dsp"
+```
+
+```bash
+bundle install
+```
+
+Ruby ≥ 3.2 required.
+
+## Configuration
+
+Configure once at boot (e.g. `config/initializers/digiwin_dsp.rb` in Rails):
+
+```ruby
+DigiwinDsp.configure do |c|
+  c.api_key      = ENV.fetch("DIGIWIN_DSP_API_KEY")
+  c.platform_id  = ENV.fetch("DIGIWIN_DSP_PLATFORM_ID")
+  c.environment  = :sandbox          # :sandbox (UAT) | :production
+  c.logger       = Rails.logger      # any Logger-like object
+  c.timeout      = 10                # request timeout (seconds)
+  c.open_timeout = 5
+end
+```
+
+Every setting also falls back to an ENV var:
+
+| Setting | ENV var | Default |
+|---|---|---|
+| `api_key` | `DIGIWIN_DSP_API_KEY` | _(required)_ |
+| `api_secret` | `DIGIWIN_DSP_API_SECRET` | `nil` |
+| `platform_id` | `DIGIWIN_DSP_PLATFORM_ID` | `nil` |
+| `environment` | `DIGIWIN_DSP_ENV` | `:sandbox` |
+| `base_url` | `DIGIWIN_DSP_BASE_URL` | resolved from `environment` |
+| `timeout` | — | `10` |
+| `open_timeout` | — | `5` |
+| `logger` | — | `Logger.new(IO::NULL)` |
+
+Base URLs (resolved from `environment`):
+
+- `:sandbox` → `https://digiwindsp.digiwin.com/DSP_UAT/api/DSP`
+- `:production` → `https://digiwindsp.digiwin.com/DSP/api/DSP`
+
+See [`.env.local.example`](./.env.local.example) for a starter env file.
+
+## Usage
+
+Each resource exposes a single `#create(records, idempotency_key:, digi_header:)` method that returns the parsed `response_detail` array on success or raises a typed exception on failure.
+
+### Create an order
+
+```ruby
+record = {
+  "platform_id"     => "acme_storefront_test",
+  "create_datetime" => Time.now.strftime("%Y-%m-%d %H:%M:%S"),
+  "site_no"         => "acme_storefront_test",
+  "form_no"         => "WEB202605200001",     # 官網訂單編號
+  "order_date"      => "20260520",
+  "buyer_name"      => "王小明",
+  "receiver_name"   => "王小明",
+  "pay_type"        => "9104",
+  "shipping_type"   => "9102",
+  "tax_type"        => "1",
+  "sno"             => "1",                   # line index
+  "form_subno"      => "1",
+  "product_no"      => "P-001",
+  "product_name"    => "測試商品",
+  "unit"            => "EA",
+  "qty"             => "1",
+  "free_qty"        => "0",
+  "price"           => "100",
+  "subtotal"        => "100",
+  "payment"         => "100",
+  "order_status"    => "3",                   # 3 = 新增
+  "last_record"     => "Y"                    # "Y" on the final line
+}
+
+response_detail = DigiwinDsp::Resources::Order.create(record)
+# => [{ "form_no" => "WEB202605200001", ... }]
+```
+
+Multi-line orders: pass an array. Each element must carry the order-level fields plus its own line fields. Set `"last_record" => "Y"` on the final element and `"N"` on the rest:
+
+```ruby
+records = [
+  base_fields.merge("sno" => "1", "product_no" => "P-001", "qty" => "1", "last_record" => "N"),
+  base_fields.merge("sno" => "2", "product_no" => "P-002", "qty" => "3", "last_record" => "Y")
+]
+
+DigiwinDsp::Resources::Order.create(records)
+```
+
+### Cancel, invoice update, return
+
+```ruby
+DigiwinDsp::Resources::Cancellation.create(cancel_record)
+DigiwinDsp::Resources::Invoice.create(invoice_record)
+DigiwinDsp::Resources::Return.create(return_record)
+```
+
+Each has its own required-field set (8 / 11 / 19 fields respectively). Inspect `REQUIRED_FIELDS` for the exact list, e.g.:
+
+```ruby
+DigiwinDsp::Serializers::CancellationSerializer::REQUIRED_FIELDS
+```
+
+### Idempotency
+
+Pass `idempotency_key:` to attach an `X-Idempotency-Key` request header. DSP also dedupes server-side by `form_no + platform_id` and returns `Duplicated:訂單不可重複` on a re-send (mapped to `DuplicateRequestError`).
+
+```ruby
+DigiwinDsp::Resources::Order.create(record, idempotency_key: "order-#{record['form_no']}")
+```
+
+### Background jobs
+
+The gem is synchronous on purpose. Wrap calls in your own job runner:
+
+```ruby
+class SyncOrderToDigiwinJob < ApplicationJob
+  retry_on DigiwinDsp::RateLimitError, wait: :polynomially_longer, attempts: 5
+  discard_on DigiwinDsp::DuplicateRequestError
+
+  def perform(order_id)
+    order = Order.find(order_id)
+    DigiwinDsp::Resources::Order.create(order.to_dsp_payload, idempotency_key: "order-#{order.id}")
+  end
+end
+```
+
+## Error handling
+
+All exceptions inherit from `DigiwinDsp::Error` and carry rich attributes (`#code`, `#dsp_message`, `#http_status`, `#request_id`, `#response_body`).
+
+| Exception | Raised when |
+|---|---|
+| `DigiwinDsp::ConfigurationError` | `api_key` missing at request time |
+| `DigiwinDsp::ValidationError` | Required field missing locally, or DSP returns `WrongStatus:` / `Processing:取消訂單處理中` / HTTP 400 |
+| `DigiwinDsp::AuthenticationError` | HTTP 401 / 403 |
+| `DigiwinDsp::DuplicateRequestError` | DSP returns `Duplicated:` or HTTP 409 |
+| `DigiwinDsp::RateLimitError` | DSP returns `Processing:資料處理中` (retryable) or persistent HTTP 429 |
+| `DigiwinDsp::ServerError` | DSP returns `系統異常:` or HTTP 5xx that exhausts retries |
+| `DigiwinDsp::NetworkError` | TCP connect failure or timeout |
+| `DigiwinDsp::Error` | Catch-all (unmapped failure message or unexpected status) |
+
+> ⚠️ Digiwin DSP returns **HTTP 200** even on application-level failure. The gem parses the response body's `Status` / `Message` fields and raises the appropriate typed exception so callers can rescue normally.
+
+```ruby
+begin
+  DigiwinDsp::Resources::Order.create(record)
+rescue DigiwinDsp::DuplicateRequestError
+  Rails.logger.info("Order already pushed, skipping")
+rescue DigiwinDsp::ValidationError => e
+  Rails.logger.error("Payload rejected: #{e.dsp_message}")
+  raise
+rescue DigiwinDsp::RateLimitError, DigiwinDsp::ServerError
+  raise   # let the job retry
+end
+```
+
+## Custom `digi_header`
+
+By default the gem **omits `digi_header`** from the request body (it's only required for certain custom Digiwin integrations). If your DSP setup expects one, pass it through:
+
+```ruby
+DigiwinDsp::Resources::Order.create(
+  record,
+  digi_header: {
+    "digi_host"    => { "prod" => "EC-SHOP", "ip" => "10.0.0.42", "timestamp" => "20260520123456789" },
+    "digi_service" => { "prod" => "ECP", "name" => "salesorder.add" }
+  }
+)
+```
+
+## Development
+
+```bash
+bin/setup              # bundle install
+bundle exec rspec      # run the full test suite (134 examples, 100% coverage)
+bundle exec rubocop    # lint
+bin/console            # IRB with the gem loaded
+```
+
+The full DSP OpenAPI 3.1 specs live under `docs/dsp-specs/`. If Digiwin updates them, replace the YAML files and re-run the test suite — the `REQUIRED_FIELDS` constants in each serializer pin the contract.
+
+## Contributing
+
+1. Fork & branch
+2. `bin/setup`
+3. Write tests first (TDD); ensure `bundle exec rspec` and `bundle exec rubocop` are green
+4. Open a PR
+
+## License
+
+MIT. See [`LICENSE.txt`](./LICENSE.txt).

data/lib/digiwin_dsp/authenticator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  class Authenticator
+    HEADER_NAME = "DSP-api-key"
+
+    def initialize(configuration = DigiwinDsp.configuration)
+      @configuration = configuration
+    end
+
+    def auth_headers
+      @configuration.validate!
+      { HEADER_NAME => @configuration.api_key }
+    end
+  end
+end

data/lib/digiwin_dsp/client.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module DigiwinDsp
+  class Client
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+    USER_AGENT = "digiwin_dsp/#{VERSION} (Faraday/#{Faraday::VERSION})".freeze
+
+    STATUS_ERROR_MAP = {
+      400 => ValidationError,
+      401 => AuthenticationError,
+      403 => AuthenticationError,
+      409 => DuplicateRequestError,
+      429 => RateLimitError
+    }.freeze
+
+    # Order matters — more-specific patterns first.
+    ENVELOPE_FAILURE_MAP = [
+      [/\ADuplicated:/, DuplicateRequestError],
+      [/\AProcessing:資料處理中/, RateLimitError],
+      [/\AProcessing:取消訂單處理中/, ValidationError],
+      [/\AWrongStatus:/, ValidationError],
+      [/\A系統異常:/, ServerError]
+    ].freeze
+
+    def initialize(configuration: DigiwinDsp.configuration, authenticator: nil)
+      @configuration = configuration
+      @authenticator = authenticator || Authenticator.new(configuration)
+    end
+
+    def post(path, body, idempotency_key: nil, headers: {})
+      @configuration.validate!
+      response = connection.post(normalize_path(path)) do |req|
+        req.headers["X-Idempotency-Key"] = idempotency_key if idempotency_key
+        headers.each { |k, v| req.headers[k] = v }
+        req.body = body
+      end
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise NetworkError, e.message
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: connection_base_url, headers: default_headers) do |f|
+        f.request :json
+        f.request :retry,
+                  max: 3,
+                  interval: 0.0,
+                  backoff_factor: 1,
+                  retry_statuses: RETRY_STATUSES,
+                  methods: %i[get post put patch delete]
+        f.response :json, content_type: /\bjson\z/
+        f.response :logger, @configuration.logger, headers: false, bodies: false, log_level: :debug
+        f.adapter Faraday.default_adapter
+        f.options.timeout = @configuration.timeout
+        f.options.open_timeout = @configuration.open_timeout
+      end
+    end
+
+    def connection_base_url
+      base = @configuration.base_url
+      base.end_with?("/") ? base : "#{base}/"
+    end
+
+    def normalize_path(path)
+      path.sub(%r{\A/+}, "")
+    end
+
+    def default_headers
+      {
+        "User-Agent" => USER_AGENT,
+        "Accept" => "application/json"
+      }.merge(@authenticator.auth_headers)
+    end
+
+    def handle_response(response)
+      status = response.status
+      body = response.body
+      return inspect_envelope(body) if status.between?(200, 299)
+
+      raise classify_http_error(status, body)
+    end
+
+    def classify_http_error(status, body)
+      klass = STATUS_ERROR_MAP[status] || (status.between?(500, 599) ? ServerError : Error)
+      message = klass == Error ? "unexpected HTTP status #{status}" : http_message(status, body)
+      klass.new(message, **error_attrs(status, body))
+    end
+
+    def inspect_envelope(body)
+      return body unless body.is_a?(Hash) && body["Status"].to_s.casecmp("failure").zero?
+
+      message = body["Message"].to_s
+      klass = ENVELOPE_FAILURE_MAP.find { |regex, _| regex.match?(message) }&.last || Error
+      raise klass.new(message, **envelope_error_attrs(body))
+    end
+
+    def http_message(status, body)
+      dsp_msg = body.is_a?(Hash) ? body["error_message"] || body["message"] : nil
+      dsp_msg ? "HTTP #{status}: #{dsp_msg}" : "HTTP #{status}"
+    end
+
+    def error_attrs(status, body)
+      hash = body.is_a?(Hash) ? body : {}
+      {
+        code: hash["error_code"] || hash["code"],
+        dsp_message: hash["error_message"] || hash["message"],
+        request_id: hash["request_id"],
+        http_status: status,
+        response_body: body
+      }
+    end
+
+    def envelope_error_attrs(body)
+      {
+        code: body["Status"],
+        dsp_message: body["Message"],
+        request_id: body["request_id"],
+        http_status: 200,
+        response_body: body
+      }
+    end
+  end
+end

data/lib/digiwin_dsp/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module DigiwinDsp
+  class Configuration
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_OPEN_TIMEOUT = 5
+
+    BASE_URLS = {
+      sandbox: "https://digiwindsp.digiwin.com/DSP_UAT/api/DSP",
+      production: "https://digiwindsp.digiwin.com/DSP/api/DSP"
+    }.freeze
+
+    attr_accessor :api_key, :api_secret, :platform_id, :environment, :logger, :timeout, :open_timeout
+    attr_writer :base_url
+
+    def initialize
+      @api_key      = ENV.fetch("DIGIWIN_DSP_API_KEY", nil)
+      @api_secret   = ENV.fetch("DIGIWIN_DSP_API_SECRET", nil)
+      @platform_id  = ENV.fetch("DIGIWIN_DSP_PLATFORM_ID", nil)
+      @environment  = ENV.fetch("DIGIWIN_DSP_ENV", "sandbox").to_sym
+      @base_url     = ENV.fetch("DIGIWIN_DSP_BASE_URL", nil)
+      @timeout      = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @logger       = Logger.new(IO::NULL)
+    end
+
+    def base_url
+      return @base_url if @base_url
+
+      BASE_URLS.fetch(environment) do
+        raise ConfigurationError,
+              "unknown environment #{environment.inspect}; expected one of #{BASE_URLS.keys.inspect}"
+      end
+    end
+
+    def validate!
+      return unless api_key.nil? || api_key.to_s.empty?
+
+      raise ConfigurationError,
+            "api_key is required (set via DigiwinDsp.configure or DIGIWIN_DSP_API_KEY)"
+    end
+  end
+end

data/lib/digiwin_dsp/resources/cancellation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Resources
+    class Cancellation
+      PATH = "/v1/SalesOrder/cancel"
+
+      def self.create(records, **)
+        new.create(records, **)
+      end
+
+      def initialize(client = Client.new)
+        @client = client
+      end
+
+      def create(records, idempotency_key: nil, digi_header: nil)
+        body = Serializers::CancellationSerializer.serialize(records, digi_header: digi_header)
+        response = @client.post(PATH, body, idempotency_key: idempotency_key)
+        response["response_detail"]
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/resources/invoice.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Resources
+    class Invoice
+      PATH = "/v1/SalesOrder/invoice"
+
+      def self.create(records, **)
+        new.create(records, **)
+      end
+
+      def initialize(client = Client.new)
+        @client = client
+      end
+
+      def create(records, idempotency_key: nil, digi_header: nil)
+        body = Serializers::InvoiceSerializer.serialize(records, digi_header: digi_header)
+        response = @client.post(PATH, body, idempotency_key: idempotency_key)
+        response["response_detail"]
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/resources/order.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Resources
+    class Order
+      PATH = "/v1/SalesOrder/add"
+
+      def self.create(records, **)
+        new.create(records, **)
+      end
+
+      def initialize(client = Client.new)
+        @client = client
+      end
+
+      def create(records, idempotency_key: nil, digi_header: nil)
+        body = Serializers::SalesOrderSerializer.serialize(records, digi_header: digi_header)
+        response = @client.post(PATH, body, idempotency_key: idempotency_key)
+        response["response_detail"]
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/resources/return.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Resources
+    class Return
+      PATH = "/v1/SalesOrder/return"
+
+      def self.create(records, **)
+        new.create(records, **)
+      end
+
+      def initialize(client = Client.new)
+        @client = client
+      end
+
+      def create(records, idempotency_key: nil, digi_header: nil)
+        body = Serializers::ReturnSerializer.serialize(records, digi_header: digi_header)
+        response = @client.post(PATH, body, idempotency_key: idempotency_key)
+        response["response_detail"]
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/serializers/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Serializers
+    # Mix into a serializer module via `extend Base`. The hosting module must
+    # define a REQUIRED_FIELDS constant (array of string field names).
+    module Base
+      def serialize(records, digi_header: nil)
+        normalized = normalize(records)
+        validate!(normalized)
+        wrap(normalized, digi_header)
+      end
+
+      private
+
+      def normalize(records)
+        list = records.is_a?(Array) ? records : [records]
+        list.map { |r| r.transform_keys(&:to_s) }
+      end
+
+      def validate!(records)
+        problems = records.each_with_index.flat_map { |record, index| missing_fields(record, index, records.size) }
+        return if problems.empty?
+
+        raise ValidationError, "missing or empty required fields: #{problems.join(", ")}"
+      end
+
+      def missing_fields(record, index, total)
+        missing = self::REQUIRED_FIELDS.reject { |f| present?(record[f]) }
+        return [] if missing.empty?
+
+        prefix = total > 1 ? "[#{index}]." : ""
+        missing.map { |f| "#{prefix}#{f}" }
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+
+      def wrap(records, digi_header)
+        body = {
+          "digi_body" => {
+            "std_data" => {
+              "parameter" => {
+                "request" => {
+                  "request_detail" => records
+                }
+              }
+            }
+          }
+        }
+        digi_header ? { "digi_header" => digi_header }.merge(body) : body
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/serializers/cancellation_serializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Serializers
+    module CancellationSerializer
+      extend Base
+
+      REQUIRED_FIELDS = %w[
+        platform_id create_datetime site_no form_no order_date
+        sno product_no order_status
+      ].freeze
+    end
+  end
+end

data/lib/digiwin_dsp/serializers/invoice_serializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Serializers
+    module InvoiceSerializer
+      extend Base
+
+      REQUIRED_FIELDS = %w[
+        platform_id create_datetime site_no form_no
+        invoice_no invoice_date invoice_time invoice_status invoice_type random_code
+        order_status
+      ].freeze
+    end
+  end
+end

data/lib/digiwin_dsp/serializers/return_serializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Serializers
+    module ReturnSerializer
+      extend Base
+
+      REQUIRED_FIELDS = %w[
+        platform_id create_datetime site_no form_no form_subno
+        original_form_no tax_type sno product_no
+        qty free_qty price subtotal payment order_status
+        returner_name returner_address returner_phone returner_zip_code
+      ].freeze
+    end
+  end
+end

data/lib/digiwin_dsp/serializers/sales_order_serializer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Serializers
+    module SalesOrderSerializer
+      extend Base
+
+      REQUIRED_FIELDS = %w[
+        platform_id create_datetime site_no form_no order_date
+        buyer_name receiver_name pay_type shipping_type tax_type
+        sno form_subno product_no product_name unit
+        qty free_qty price subtotal payment
+        order_status last_record
+      ].freeze
+    end
+  end
+end

data/lib/digiwin_dsp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  VERSION = "0.1.0"
+end

data/lib/digiwin_dsp.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+module DigiwinDsp
+  class Error < StandardError
+    attr_reader :code, :dsp_message, :request_id, :http_status, :response_body
+
+    def initialize(message = nil, code: nil, dsp_message: nil, request_id: nil, http_status: nil, response_body: nil)
+      super(message)
+      @code          = code
+      @dsp_message   = dsp_message
+      @request_id    = request_id
+      @http_status   = http_status
+      @response_body = response_body
+    end
+  end
+
+  class ConfigurationError    < Error; end
+  class AuthenticationError   < Error; end
+  class ValidationError       < Error; end
+  class RateLimitError        < Error; end
+  class ServerError           < Error; end
+  class NetworkError          < Error; end
+  class DuplicateRequestError < Error; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: digiwin_dsp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zac
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Synchronous Ruby gem wrapping the Digiwin DSP 自有官網模組 endpoints (create
+  order, cancel order, invoice update, return) for use from a Rails site.
+email:
+- 579103+7a6163@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/digiwin_dsp.rb
+- lib/digiwin_dsp/authenticator.rb
+- lib/digiwin_dsp/client.rb
+- lib/digiwin_dsp/configuration.rb
+- lib/digiwin_dsp/resources/cancellation.rb
+- lib/digiwin_dsp/resources/invoice.rb
+- lib/digiwin_dsp/resources/order.rb
+- lib/digiwin_dsp/resources/return.rb
+- lib/digiwin_dsp/serializers/base.rb
+- lib/digiwin_dsp/serializers/cancellation_serializer.rb
+- lib/digiwin_dsp/serializers/invoice_serializer.rb
+- lib/digiwin_dsp/serializers/return_serializer.rb
+- lib/digiwin_dsp/serializers/sales_order_serializer.rb
+- lib/digiwin_dsp/version.rb
+homepage: https://github.com/7a6163/digiwin_dsp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/7a6163/digiwin_dsp
+  source_code_uri: https://github.com/7a6163/digiwin_dsp
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the Digiwin DSP 自有官網模組 API.
+test_files: []