fiscalrail 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d9fcbcf8bfd05d48cce8ca79c50e6053d989ef54c0a2b67b5c386764f71b8a0
-  data.tar.gz: e1026a8001318bfb1914add9feb13409818b1f8d54937fc7569c4776474763a9
+  metadata.gz: 686707319e3f84edc7570df96ecde4325051ced614c1d7afb0706fb490730fbe
+  data.tar.gz: 9b72d4865f113b5d9e1d18668a390ec8d6900b1ab05d06ca9ef12cf933a47c90
 SHA512:
-  metadata.gz: 85026a467a16b3bc54a33306720743d41aba4ea63b7e3072e30240f2b4d67bb6d54cf38293d92098b9ad0b05da755e671c39e6e559bd0675c942a5fe78c05995
-  data.tar.gz: ef408ec27b12fe12d907de2abaa8d15a9be13485437f1c5985f442d94fde4615dc519975805221c266acbfdb1834aaaa0c8ee8f39918db98c743bf3d9371f43a
+  metadata.gz: 7b72ea35beff00c975ccb4dcb1f4953b56805cd64b330dee8cd4d39086158043574a4f10e51d28eac3639bea26cde7dbd0bfdcf068cbf66a8bd4d1838e5b4836
+  data.tar.gz: aae2526ccbe70ba3872c6859861cb972f743e72b1fc653fd28006d8236b49275583f48651e034fae59f6dbd109e36e841fec16d842efb0d8770dfd88dc9e0d04

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.6.0
+
+- Add ES-scoped issuer certificate file uploads, representation verification,
+  submission-verification retries and pending-change cancellation.
+- Expose active submission readiness and pending verification results from the
+  deployed API contract (47 operations).
+- Keep certificate uploads as native multipart requests without automatic retries.
+
+
 ## 0.5.0 — 2026-09-28
 
 - Match the deployed current-account API routes and split invoicing settings into a dedicated resource.

data/README.md

@@ -5,7 +5,7 @@ A Ruby client for issuing immutable invoices through FiscalRail. Ruby 3.3 or lat
 Install with Bundler:
 
 ```ruby
-gem "fiscalrail", "~> 0.5.0"
+gem "fiscalrail", "~> 0.6.0"
 ```
 
 ## Issue an invoice
@@ -230,3 +230,32 @@ FISCALRAIL_APP_ROOT="$PWD" bundle exec ruby /absolute/path/to/ruby/test/rails_in
 It creates a Test account inside a test transaction and checks customer creation, null clearing, payment defaults, issuance/replay, pagination, PDF download and amendment. Set `FISCALRAIL_SDK_PDF=/tmp/sdk-invoice.pdf` to retain the rendered PDF for inspection. This test is optional and is not part of the standalone gem CI.
 
 See [RELEASING.md](RELEASING.md) for the release checklist.
+
+
+## Spanish AEAT submission
+
+Use a Live Spanish account key. Upload a `.p12`/`.pfx` file (up to 128 KiB),
+including its private key, using native multipart upload. Omit the password for
+an unprotected bundle. The certificate's issuer NIF must match the account.
+
+```ruby
+File.open("issuer.p12", "rb") do |certificate|
+  setup = client.account_tax_regimes.es.upload_certificate(
+    certificate_file: certificate,
+    certificate_password: ENV.fetch("CERTIFICATE_PASSWORD")
+  )
+end
+setup = client.account_tax_regimes.retrieve
+# Inspect setup.es.pending_submission.status / error_code and setup.es.submission.ready.
+client.account_tax_regimes.es.verify_submission # retry the pending or active check
+client.account_tax_regimes.es.cancel_submission_change
+client.account_tax_regimes.es.verify_representation # after granting AEAT authority
+```
+
+Each mutation above is a separate operation; choose the one needed. Upload and
+verification return the account setup while AEAT checks run asynchronously.
+Poll the generic account tax-regime resource for pending verification status,
+error code and the active setup's readiness. A working setup remains active until
+a replacement verifies; failed checks retain the pending certificate for retry.
+Cancelling removes only the pending change. Uploads are not automatically retried.
+The ES mutations use `/account/tax-regime/es/...`; reads use `/account/tax-regime`.

data/lib/fiscalrail/generated/contract.rb

@@ -2365,6 +2365,49 @@ module FiscalRail
       ],
       "type": "object"
     },
+    "SpanishAccountSubmission": {
+      "model": "SpanishAccountSubmission",
+      "properties": {
+        "certificate_expires_at": {
+          "format": "date-time",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error_code": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "kind": {
+          "type": "string"
+        },
+        "last_checked_at": {
+          "format": "date-time",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "ready": {
+          "type": "boolean"
+        },
+        "status": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "ready",
+        "certificate_expires_at",
+        "status",
+        "error_code",
+        "last_checked_at"
+      ],
+      "type": "object"
+    },
     "SpanishAccountTaxRegime": {
       "model": "SpanishAccountTaxRegime",
       "properties": {
@@ -2394,6 +2437,16 @@ module FiscalRail
     "SpanishAccountTaxRegimeDetails": {
       "model": "SpanishAccountTaxRegimeDetails",
       "properties": {
+        "pending_submission": {
+          "oneOf": [
+            {
+              "$ref": "#/components/schemas/SpanishPendingSubmission"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "representation": {
           "oneOf": [
             {
@@ -2403,10 +2456,22 @@ module FiscalRail
               "type": "null"
             }
           ]
+        },
+        "submission": {
+          "oneOf": [
+            {
+              "$ref": "#/components/schemas/SpanishAccountSubmission"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "required": [
-        "representation"
+        "representation",
+        "submission",
+        "pending_submission"
       ],
       "type": "object"
     },
@@ -2460,6 +2525,89 @@ module FiscalRail
       ],
       "type": "object"
     },
+    "SpanishPendingSubmission": {
+      "model": "SpanishPendingSubmission",
+      "properties": {
+        "certificate_expires_at": {
+          "format": "date-time",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error_code": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "kind": {
+          "type": "string"
+        },
+        "last_checked_at": {
+          "format": "date-time",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "status": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "status",
+        "error_code",
+        "last_checked_at",
+        "certificate_expires_at"
+      ],
+      "type": "object"
+    },
+    "SubmissionConfigurationErrorResponse": {
+      "model": "SubmissionConfigurationErrorResponse",
+      "properties": {
+        "error": {
+          "model": "SubmissionConfigurationError",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "details": {
+              "items": {
+                "model": "SubmissionConfigurationValidationDetail",
+                "properties": {
+                  "field": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "field",
+                  "message"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "error"
+      ],
+      "type": "object"
+    },
     "TaxId": {
       "model": "TaxId",
       "properties": {
@@ -2914,6 +3062,16 @@ module FiscalRail
         }
       }
     },
+    "cancelAccountSubmissionChange": {
+      "method": "DELETE",
+      "path": "/account/tax-regime/es/submission/pending",
+      "parameters": [],
+      "responses": {
+        "200": {
+          "$ref": "#/components/schemas/AccountTaxRegime"
+        }
+      }
+    },
     "createApiKey": {
       "method": "POST",
       "path": "/api-keys",
@@ -3587,6 +3745,36 @@ module FiscalRail
           "$ref": "#/components/schemas/PaymentInstruction"
         }
       }
+    },
+    "uploadAccountCertificate": {
+      "method": "POST",
+      "path": "/account/tax-regime/es/certificate",
+      "parameters": [],
+      "responses": {
+        "202": {
+          "$ref": "#/components/schemas/AccountTaxRegime"
+        }
+      }
+    },
+    "verifyAccountRepresentation": {
+      "method": "POST",
+      "path": "/account/tax-regime/es/representation/verify",
+      "parameters": [],
+      "responses": {
+        "202": {
+          "$ref": "#/components/schemas/AccountTaxRegime"
+        }
+      }
+    },
+    "verifyAccountSubmission": {
+      "method": "POST",
+      "path": "/account/tax-regime/es/submission/verify",
+      "parameters": [],
+      "responses": {
+        "202": {
+          "$ref": "#/components/schemas/AccountTaxRegime"
+        }
+      }
     }
   }
 }

data/lib/fiscalrail/generated/models.rb

@@ -593,6 +593,15 @@ module FiscalRail
       def verified_at = self["verified_at"]
     end
 
+    class SpanishAccountSubmission < Model
+      def certificate_expires_at = self["certificate_expires_at"]
+      def error_code = self["error_code"]
+      def kind = self["kind"]
+      def last_checked_at = self["last_checked_at"]
+      def ready = self["ready"]
+      def status = self["status"]
+    end
+
     class SpanishAccountTaxRegime < Model
       def account = self["account"]
       def es = self["es"]
@@ -601,7 +610,9 @@ module FiscalRail
     end
 
     class SpanishAccountTaxRegimeDetails < Model
+      def pending_submission = self["pending_submission"]
       def representation = self["representation"]
+      def submission = self["submission"]
     end
 
     class SpanishInvoiceQr < Model
@@ -619,6 +630,29 @@ module FiscalRail
       def verifactu = self["verifactu"]
     end
 
+    class SpanishPendingSubmission < Model
+      def certificate_expires_at = self["certificate_expires_at"]
+      def error_code = self["error_code"]
+      def kind = self["kind"]
+      def last_checked_at = self["last_checked_at"]
+      def status = self["status"]
+    end
+
+    class SubmissionConfigurationError < Model
+      def code = self["code"]
+      def details = self["details"]
+      def message = self["message"]
+    end
+
+    class SubmissionConfigurationErrorResponse < Model
+      def error = self["error"]
+    end
+
+    class SubmissionConfigurationValidationDetail < Model
+      def field = self["field"]
+      def message = self["message"]
+    end
+
     class TaxId < Model
       def country = self["country"]
       def id = self["id"]

data/lib/fiscalrail/resource.rb

@@ -10,7 +10,7 @@ module FiscalRail
 
     private
 
-    def request(operation_id, path: {}, params: {}, body: nil, retry_safe: false, idempotency_key: nil, headers: {}, binary: false)
+    def request(operation_id, path: {}, params: {}, body: nil, multipart: nil, retry_safe: false, idempotency_key: nil, headers: {}, binary: false)
       operation = Generated::OPERATIONS.fetch(operation_id)
       route = operation.fetch("path").gsub(/\{([^}]+)\}/) do
         value = path.fetch(Regexp.last_match(1).to_sym)
@@ -20,7 +20,7 @@ module FiscalRail
       end
       headers = headers.merge("Accept" => "application/pdf") if binary
       response = @transport.request(method: operation.fetch("method"), path: route, params: params,
-        body: body, retry_safe: retry_safe, idempotency_key: idempotency_key, headers: headers)
+        body: body, multipart: multipart, retry_safe: retry_safe, idempotency_key: idempotency_key, headers: headers)
       metadata = { request_id: response.headers["request-id"], idempotent_replayed: response.headers["idempotent-replayed"], idempotency_key: idempotency_key }
       unless operation.fetch("responses").key?(response.status.to_s)
         raise ResponseParseError.new("unexpected HTTP #{response.status}", model: operation_id, field: "$", **metadata.slice(:request_id, :idempotency_key))

data/lib/fiscalrail/resources/accounts.rb

@@ -29,9 +29,33 @@ module FiscalRail
     end
 
     class AccountTaxRegimes < Resource
+      def es
+        @es ||= SpanishSubmission.new(@transport)
+      end
+
       def retrieve
         request("retrieveAccountTaxRegime", retry_safe: true)
       end
     end
+    class SpanishSubmission < Resource
+      def upload_certificate(certificate_file:, certificate_password: nil)
+        content = certificate_file.read(128 * 1024 + 1) || ""
+        raise ArgumentError, "certificate_file must be at most 128 KiB" if content.bytesize > 128 * 1024
+
+        request("uploadAccountCertificate", multipart: { certificate_file: content, certificate_password: certificate_password })
+      end
+
+      def verify_representation
+        request("verifyAccountRepresentation")
+      end
+
+      def verify_submission
+        request("verifyAccountSubmission")
+      end
+
+      def cancel_submission_change
+        request("cancelAccountSubmissionChange")
+      end
+    end
   end
 end

data/lib/fiscalrail/transport.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 require "uri"
 require "thread"
+require "securerandom"
 
 module FiscalRail
   # The adapter boundary also makes custom proxy/TLS/instrumentation possible.
@@ -63,7 +64,7 @@ module FiscalRail
       @api_key, @base_url, @max_retries, @adapter, @sleeper = api_key, base_url.sub(%r{/+\z}, ""), max_retries, adapter, sleeper
     end
 
-    def request(method:, path:, body: nil, params: {}, headers: {}, retry_safe:, idempotency_key: nil)
+    def request(method:, path:, body: nil, multipart: nil, params: {}, headers: {}, retry_safe:, idempotency_key: nil)
       uri = URI("#{@base_url}#{path}")
       query = Serialization.json_value(params.reject { |_, value| value.nil? })
       uri.query = URI.encode_www_form(query) unless query.empty?
@@ -74,6 +75,17 @@ module FiscalRail
       request_headers["Idempotency-Key"] = idempotency_key if idempotency_key
       request_headers["Content-Type"] = "application/json" unless body.nil?
       encoded = body.nil? ? nil : JSON.generate(Serialization.json_value(body))
+      if multipart
+        boundary = "fiscalrail-#{SecureRandom.hex(24)}"
+        request_headers["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        encoded = "--#{boundary}\r\nContent-Disposition: form-data; name=\"certificate_file\"; filename=\"certificate.p12\"\r\nContent-Type: application/x-pkcs12\r\n\r\n".b
+        encoded << multipart.fetch(:certificate_file).b << "\r\n".b
+        unless multipart[:certificate_password].nil?
+          encoded << "--#{boundary}\r\nContent-Disposition: form-data; name=\"certificate_password\"\r\n\r\n".b
+          encoded << multipart.fetch(:certificate_password).b << "\r\n".b
+        end
+        encoded << "--#{boundary}--\r\n".b
+      end
       attempt = 0
       loop do
         begin

data/lib/fiscalrail/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiscalRail
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiscalrail
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - FiscalRail