sat_mx 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecf0432037eb033ade4de9f89e9d9edfcd4a7174391758d2c1dc47c5771e44b0
-  data.tar.gz: 0aaf19d6965d16cc6c28047964fe4d00be5c925e9cc921f37f3e86985f50993e
+  metadata.gz: a6f23a9065a4facc1ea12963a7a27587c8055775cbb729e3070c0a5a2a8144cd
+  data.tar.gz: c043c861ed94a4cb049b3664f37b6a3b13e502917e28dd7b6f07608f15212485
 SHA512:
-  metadata.gz: 21ce855b92d37223820e13056c03468880473bd0a791987d2ba8adc65c7d6da11f5f058a52a7d2f3ca26b1cd4d2434c1308cd9e3f10235add7d6ab9a1b7c5a98
-  data.tar.gz: 8a5b7724f51b3698d1a71b15da5e75fa905082ce7b631d261e2c20fec9f0cc47fb4ea4f2992012437afc94759ae419b34b4aa565f79bace0ca1f8632eed97084
+  metadata.gz: 7a4ca5be6421a81e686b084207556f320fc4294d0d9731d9febd8e4d303a49bf10dcbfde496d86d2a8eef72fb172d69b7948ae2812e79f9c950d6749e038c8d8
+  data.tar.gz: 6dfb7a7364d74260cb0eb5e804b19b2e113e3fbfd8a5a61baee671e22cb15a109618decae7c7851b941e07901e61b93ec9ba12ede074b736e08fe355717bc227

data/README.md

@@ -1,39 +1,99 @@
 # SatMx
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sat_mx`. To experiment with that code, run `bin/console` for an interactive prompt.
+Ruby client for SAT (Mexican Tax Administration) web services to download CFDI invoices.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```bash
+gem install sat_mx
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or add to your Gemfile:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem "sat_mx"
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Configuration
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+SatMx.configure do |config|
+  config[:certificate] = "path/to/certificate.cer"
+  config[:private_key] = "path/to/private.key"
+  config[:password] = "key_password"
+end
+```
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sat_mx. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/sat_mx/blob/master/CODE_OF_CONDUCT.md).
+```ruby
+# 1. Authenticate
+result = SatMx.authenticate
+raise "Auth failed" unless result.success?
+
+token = result.value
+
+# 2. Request download of received CFDI
+result = SatMx.download_request_received(
+  start_date: Time.new(2024, 1, 1),
+  end_date: Time.new(2024, 1, 31),
+  request_type: :cfdi,
+  recipient_rfc: "ABC010101ABC",
+  requester_rfc: "ABC010101ABC",
+  issuing_rfc: "XYZ020202XYZ",
+  document_status: "Vigente",
+  access_token: token
+)
+raise "Request failed" unless result.success?
+
+request_id = result.value
+
+# 3. Verify status (poll until ready)
+loop do
+  result = SatMx.verify_request(
+    request_id: request_id,
+    requester_rfc: "ABC010101ABC",
+    access_token: token
+  )
+
+  case result.value[:request_status]
+  when :finished
+    break result.value[:package_ids]
+  when :error, :rejected, :expired
+    raise "Request failed: #{result.value}"
+  end
+
+  sleep 5
+end
+
+# 4. Download packages
+package_ids.each do |package_id|
+  result = SatMx.download_petition(
+    package_id: package_id,
+    requester_rfc: "ABC010101ABC",
+    access_token: token
+  )
+
+  File.write("#{package_id}.zip", result.value) if result.success?
+end
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `SatMx.configure` | Configure certificate and private key |
+| `SatMx.configuration` | Get current configuration |
+| `SatMx.authenticate` | Get access token |
+| `SatMx.download_request_received` | Request download of received CFDI |
+| `SatMx.verify_request` | Check request status |
+| `SatMx.download_petition` | Download package |
+
+All methods return a `Result` object with:
+- `success?` - Boolean indicating success
+- `value` - Data on success, error hash `{:cod_estatus, :mensaje}` on failure
+- `xml` - Raw XML response
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the SatMx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sat_mx/blob/master/CODE_OF_CONDUCT.md).
+MIT

data/lib/sat_mx/authentication.rb

@@ -3,6 +3,7 @@ require "time"
 require "base64"
 
 module SatMx
+  # @api private
   class Authentication
     def self.authenticate(certificate:, private_key:, uuid: SecureRandom.uuid)
       new(
@@ -43,6 +44,7 @@ module SatMx
     attr_reader :xml_auth_body, :client
   end
 
+  # @api private
   class XmlAuthBody
     def initialize(certificate:, uuid:)
       @certificate = certificate

data/lib/sat_mx/body.rb

@@ -1,6 +1,7 @@
 require "base64"
 
 module SatMx
+  # @api private
   module Body
     S11 = "S11"
     XMLNS = "xmlns"

data/lib/sat_mx/client.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class Client
     HEADERS = {
       "content-type" => "text/xml; charset=utf-8",
@@ -32,6 +33,17 @@ module SatMx
       )
     end
 
+    def download_request_received(payload)
+      HTTPX.post(
+        "https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/SolicitaDescargaService.svc",
+        headers: {
+          "SOAPAction" => "http://DescargaMasivaTerceros.sat.gob.mx/ISolicitaDescargaService/SolicitaDescargaRecibidos"
+        }.merge(authorization)
+        .merge(HEADERS),
+        body: sign(payload)
+      )
+    end
+
     def verify_request(payload)
       HTTPX.post(
         "https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/VerificaSolicitudDescargaService.svc",

data/lib/sat_mx/configuration.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   Configuration = Data.define(:certificate, :private_key) do
     def initialize(certificate:, private_key:, password:)
       super(

data/lib/sat_mx/download_petition.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class DownloadPetition
     def self.call(package_id:, requester_rfc:, access_token:, certificate:, private_key:)
       new(
@@ -41,8 +42,8 @@ module SatMx
             success?: false,
             xml: response.xml,
             value: {
-              CodEstatus: response_tag["CodEstatus"],
-              Mensaje: response_tag["Mensaje"]
+              cod_estatus: response_tag["CodEstatus"],
+              mensaje: response_tag["Mensaje"]
             }
           )
         end

data/lib/sat_mx/download_petition_body.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class DownloadPetitionBody
     include Body
 

data/lib/sat_mx/download_request.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class DownloadRequest
     def self.call(start_date:,
       end_date:,
@@ -56,8 +57,8 @@ module SatMx
         Result.new(
           success?: false,
           value: {
-            CodEstatus: download_result_tag.attr("CodEstatus").value,
-            Mensaje: download_result_tag.attr("Mensaje").value
+            cod_estatus: download_result_tag.attr("CodEstatus").value,
+            mensaje: download_result_tag.attr("Mensaje").value
           },
           xml:
         )

data/lib/sat_mx/download_request_body.rb

@@ -1,6 +1,7 @@
 require "time"
 
 module SatMx
+  # @api private
   class DownloadRequestBody
     include Body
 

data/lib/sat_mx/download_request_received.rb

@@ -0,0 +1,110 @@
+require_relative "body"
+
+module SatMx
+  # @api private
+  class DownloadRequestReceived
+    def self.call(start_date:,
+      end_date:,
+      request_type:,
+      recipient_rfc:,
+      access_token:,
+      certificate:,
+      private_key:,
+      requester_rfc: nil,
+      issuing_rfc: nil,
+      complement: nil,
+      document_status: nil)
+      new(
+        download_request_received_body: DownloadRequestReceivedBody.new(
+          start_date:,
+          end_date:,
+          request_type:,
+          recipient_rfc:,
+          requester_rfc:,
+          certificate:,
+          issuing_rfc:,
+          complement:,
+          document_status:
+        ),
+        client: Client.new(private_key:, access_token:)
+      ).call
+    end
+
+    def initialize(download_request_received_body:, client:)
+      @download_request_received_body = download_request_received_body
+      @client = client
+    end
+
+    def call
+      if (validation_error = validate_complement!)
+        return validation_error
+      end
+
+      if (validation_error = validate_document_status!)
+        return validation_error
+      end
+
+      response = client.download_request_received(download_request_received_body.generate)
+
+      case response.status
+      when 200..299
+        check_body_status response.xml
+      when 400..599
+        Result.new(success?: false, value: nil, xml: response.xml)
+      else
+        Error
+      end
+    end
+
+    private
+
+    attr_reader :download_request_received_body, :client
+
+    def validate_complement!
+      complement = download_request_received_body.complement
+      return unless complement
+      return if DownloadRequestReceivedBody::COMPLEMENT_TYPES.include?(complement)
+
+      Result.new(
+        success?: false,
+        value: {cod_estatus: "INVALID_COMPLEMENT", mensaje: "Invalid complement type: #{complement}"},
+        xml: nil
+      )
+    end
+
+    def validate_document_status!
+      document_status = download_request_received_body.document_status
+      return unless document_status
+      return if DownloadRequestReceivedBody::DOCUMENT_STATUS.include?(document_status)
+
+      Result.new(
+        success?: false,
+        value: {cod_estatus: "INVALID_DOCUMENT_STATUS", mensaje: "Invalid document status: #{document_status}"},
+        xml: nil
+      )
+    end
+
+    def check_body_status(xml)
+      download_result_tag = xml.xpath(
+        "//xmlns:SolicitaDescargaRecibidosResult",
+        xmlns: Body::NAMESPACE
+      )
+      if download_result_tag.attr("CodEstatus").value == "5000"
+        Result.new(
+          success?: true,
+          value: download_result_tag.attr("IdSolicitud").value,
+          xml:
+        )
+      else
+        Result.new(
+          success?: false,
+          value: {
+            cod_estatus: download_result_tag.attr("CodEstatus").value,
+            mensaje: download_result_tag.attr("Mensaje").value
+          },
+          xml:
+        )
+      end
+    end
+  end
+end

data/lib/sat_mx/download_request_received_body.rb

@@ -0,0 +1,112 @@
+require "time"
+
+module SatMx
+  # @api private
+  class DownloadRequestReceivedBody
+    include Body
+
+    REQUEST_TYPES = {
+      cfdi: "CFDI",
+      metadata: "Metadata"
+    }.freeze
+
+    DOCUMENT_STATUS = %w[
+      Todos
+      Cancelado
+      Vigente
+    ].freeze
+
+    COMPLEMENT_TYPES = %w[
+      acreditamientoieps10
+      aerolineas
+      certificadodedestruccion
+      cfdiregistrofiscal
+      comercioexterior10
+      comercioexterior11
+      comprobante
+      consumodecombustibles
+      consumodecombustibles11
+      detallista
+      divisas
+      donat11
+      ecc11
+      ecc12
+      gastoshidrocarbonos10
+      iedu
+      implocal
+      ine11
+      ingresoshidrocarbonos
+      leyendasfisc
+      nomina11
+      nomina12
+      notariospublicos
+      obrasarteantiguedades
+      pagoenespecie
+      pagos10
+      pfic
+      renovacionysustitucionvehiculos
+      servicioparcialconstruccion
+      spei
+      terceros11
+      turistapasajeroextranjero
+      valesdedespensa
+      vehiculousado
+      ventavehiculos11
+    ].freeze
+
+    def initialize(
+      start_date:,
+      end_date:,
+      request_type:,
+      recipient_rfc:,
+      requester_rfc:,
+      certificate:,
+      issuing_rfc: nil,
+      complement: nil,
+      document_status: nil
+    )
+      @start_date = start_date
+      @end_date = end_date
+      @request_type = request_type
+      @recipient_rfc = recipient_rfc
+      @requester_rfc = requester_rfc
+      @certificate = certificate
+      @issuing_rfc = issuing_rfc
+      @complement = complement
+      @document_status = document_status
+    end
+
+    def generate
+      envelope do |xml|
+        xml[Body::DES].SolicitaDescargaRecibidos do
+          attrs = {
+            "FechaInicial" => start_date,
+            "FechaFinal" => end_date,
+            "TipoSolicitud" => request_type,
+            "RfcReceptor" => recipient_rfc
+          }
+          attrs["RfcEmisor"] = issuing_rfc if issuing_rfc
+          attrs["RfcSolicitante"] = requester_rfc if requester_rfc
+          attrs["Complemento"] = complement if complement
+          attrs["EstadoComprobante"] = document_status if document_status
+
+          xml[Body::DES].solicitud(attrs) do
+            signature(xml)
+          end
+        end
+      end
+    end
+
+    attr_reader :complement, :document_status
+
+    private
+
+    attr_reader :recipient_rfc, :requester_rfc, :certificate, :issuing_rfc
+
+    def start_date = @start_date.strftime("%Y-%m-%dT%H:%M:%S")
+
+    def end_date = @end_date.strftime("%Y-%m-%dT%H:%M:%S")
+
+    def request_type = REQUEST_TYPES.fetch(@request_type)
+  end
+end

data/lib/sat_mx/result.rb

@@ -1,3 +1,4 @@
 module SatMx
+  # @api private
   Result = Data.define(:success?, :value, :xml)
 end

data/lib/sat_mx/signer.rb

@@ -2,6 +2,7 @@ require "openssl"
 require "xmldsig"
 
 module SatMx
+  # @api private
   class Signer
     def self.sign(document:, private_key:)
       new(document:, private_key:).sign

data/lib/sat_mx/verify_request.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class VerifyRequest
     STATUS = {
       "1" => :accepted,
@@ -49,8 +50,8 @@ module SatMx
         Result.new(
           success?: false,
           value: {
-            CodEstatus: download_result_tag.attr("CodEstatus").value,
-            Mensaje: download_result_tag.attr("Mensaje").value
+            cod_status: download_result_tag.attr("CodEstatus").value,
+            mensaje: download_result_tag.attr("Mensaje").value
           },
           xml:
         )

data/lib/sat_mx/verify_request_body.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class VerifyRequestBody
     include Body
 

data/lib/sat_mx/version.rb

@@ -1,3 +1,3 @@
 module SatMx
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/sat_mx.rb

@@ -7,6 +7,8 @@ module SatMx
   autoload(:Authentication, "sat_mx/authentication")
   autoload(:DownloadRequest, "sat_mx/download_request")
   autoload(:DownloadRequestBody, "sat_mx/download_request_body")
+  autoload(:DownloadRequestReceived, "sat_mx/download_request_received")
+  autoload(:DownloadRequestReceivedBody, "sat_mx/download_request_received_body")
   autoload(:VerifyRequest, "sat_mx/verify_request")
   autoload(:VerifyRequestBody, "sat_mx/verify_request_body")
   autoload(:DownloadPetition, "sat_mx/download_petition")
@@ -46,6 +48,9 @@ module SatMx
     #     puts "Authentication failed"
     #   end
     #
+    # @param certificate [OpenSSL::X509::Certificate, nil] Certificate object (uses configuration if nil)
+    # @param private_key [OpenSSL::PKey::RSA, nil] Private key object (uses configuration if nil)
+    #
     # @return [SatMx::Result] A Result object containing:
     #   - success?: [Boolean] whether the authentication was successful
     #   - value: [String, nil] the authentication token if successful, nil otherwise
@@ -53,10 +58,204 @@ module SatMx
     #
     # @see SatMx::Authentication
     # @see SatMx::Result
-    def authenticate
+    def authenticate(certificate: nil, private_key: nil)
+      cert = certificate || configuration.certificate
+      key = private_key || configuration.private_key
       Authentication.authenticate(
-        certificate: configuration.certificate,
-        private_key: configuration.private_key
+        certificate: cert,
+        private_key: key
+      )
+    end
+
+    # Requests a download of CFDI documents from the SAT web service.
+    #
+    #   result = SatMx.download_request(
+    #     start_date: Time.new(2024, 1, 1),
+    #     end_date: Time.new(2024, 1, 31),
+    #     request_type: :cfdi,
+    #     issuing_rfc: "ABC010101ABC",
+    #     recipient_rfcs: ["XYZ020202XYZ"],
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     puts "Request ID: #{result.value}"
+    #   else
+    #     puts "Request failed: #{result.value}"
+    #   end
+    #
+    # @param start_date [Time] Start date for the search range
+    # @param end_date [Time] End date for the search range
+    # @param request_type [Symbol] Type of request (:cfdi or :retentions)
+    # @param issuing_rfc [String] RFC of the issuer
+    # @param recipient_rfcs [Array<String>] RFCs of the recipients
+    # @param requester_rfc [String] RFC of the requester
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param certificate [String, nil] Path to certificate file (uses configuration if nil)
+    # @param private_key [String, nil] Path to private key file (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the request was successful
+    #   - value: [String, nil] the request ID if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::DownloadRequest
+    # @see SatMx::Result
+    def download_request(start_date:, end_date:, request_type:, issuing_rfc:, recipient_rfcs:, requester_rfc:, access_token:, **options)
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      DownloadRequest.call(
+        start_date:,
+        end_date:,
+        request_type:,
+        issuing_rfc:,
+        recipient_rfcs:,
+        requester_rfc:,
+        access_token:,
+        certificate:,
+        private_key:
+      )
+    end
+
+    # Requests a download of received CFDI documents from the SAT web service SolicitaDescargaService with SOAPAction SolicitaDescargaRecibidos
+    #
+    #   result = SatMx.download_request_received(
+    #     start_date: Time.new(2024, 1, 1),
+    #     end_date: Time.new(2024, 1, 31),
+    #     request_type: :cfdi,
+    #     recipient_rfc: "ABC010101ABC",
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     puts "Request ID: #{result.value}"
+    #   else
+    #     puts "Request failed: #{result.value}"
+    #   end
+    #
+    # @param start_date [Time] Start date for the search range
+    # @param end_date [Time] End date for the search range
+    # @param request_type [Symbol] Type of request (:cfdi or :metadata)
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param recipient_rfc [String] RFC of the receiver (required)
+    # @param requester_rfc [String, nil] RFC of the requester (optional)
+    # @param issuing_rfc [String, nil] RFC of the issuer (optional)
+    # @param complement [String, nil] Complement type to filter (e.g., "nomina12", "pagos10")
+    #  This value is optional. If omitted, the SAT web service will return all documents.
+    # @param document_status [String, nil] Document status filter (Todos, Cancelados, Vigentes) defaults to Todos
+    # @param certificate [String, nil] Certificate object (uses configuration if nil)
+    # @param private_key [String, nil] Private key object (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the request was successful
+    #   - value: [String, nil] the request ID if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::DownloadRequestReceived
+    # @see SatMx::Result
+    def download_request_received(
+      access_token:,
+      start_date:,
+      end_date:,
+      request_type:,
+      recipient_rfc:,
+      issuing_rfc: nil,
+      requester_rfc: nil,
+      document_status: nil,
+      complement: nil,
+      **options
+    )
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      DownloadRequestReceived.call(
+        start_date:,
+        end_date:,
+        request_type:,
+        recipient_rfc:,
+        requester_rfc:,
+        issuing_rfc:,
+        complement:,
+        document_status:,
+        access_token:,
+        certificate:,
+        private_key:
+      )
+    end
+
+    # Verifies the status of a previously submitted download request.
+    #
+    #   result = SatMx.verify_request(
+    #     request_id: "606c5667-345a-4630-8979-0769734ac80b",
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     puts "Status: #{result.value[:request_status]}"
+    #     puts "Packages: #{result.value[:package_ids]}"
+    #   else
+    #     puts "Verification failed: #{result.value}"
+    #   end
+    #
+    # @param request_id [String] The ID returned from SatMx.download_request
+    # @param requester_rfc [String] RFC of the requester
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param certificate [String, nil] Path to certificate file (uses configuration if nil)
+    # @param private_key [String, nil] Path to private key file (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the verification was successful
+    #   - value: [Hash, nil] containing :request_status and :package_ids if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::VerifyRequest
+    # @see SatMx::Result
+    def verify_request(request_id:, requester_rfc:, access_token:, **options)
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      VerifyRequest.call(
+        request_id:,
+        requester_rfc:,
+        access_token:,
+        certificate:,
+        private_key:
+      )
+    end
+
+    # Downloads a package of CFDI documents from the SAT web service.
+    #
+    #   result = SatMx.download_petition(
+    #     package_id: "18015570-C084-4BE8-BE36-476F5D46A133_01",
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     File.write("package.zip", result.value)
+    #   else
+    #     puts "Download failed: #{result.value}"
+    #   end
+    #
+    # @param package_id [String] The package ID from SatMx.verify_request
+    # @param requester_rfc [String] RFC of the requester
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param certificate [String, nil] Path to certificate file (uses configuration if nil)
+    # @param private_key [String, nil] Path to private key file (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the download was successful
+    #   - value: [String, nil] Base64 encoded ZIP content if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::DownloadPetition
+    # @see SatMx::Result
+    def download_petition(package_id:, requester_rfc:, access_token:, **options)
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      DownloadPetition.call(
+        package_id:,
+        requester_rfc:,
+        access_token:,
+        certificate:,
+        private_key:
       )
     end
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sat_mx
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Oscar Rivas
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-03-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xmldsig
@@ -131,6 +130,8 @@ files:
 - lib/sat_mx/download_petition_body.rb
 - lib/sat_mx/download_request.rb
 - lib/sat_mx/download_request_body.rb
+- lib/sat_mx/download_request_received.rb
+- lib/sat_mx/download_request_received_body.rb
 - lib/sat_mx/result.rb
 - lib/sat_mx/signer.rb
 - lib/sat_mx/verify_request.rb
@@ -143,7 +144,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/kadru/sat_mx
   changelog_uri: https://github.com/kadru/sat_mx/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -158,8 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key: 
+rubygems_version: 4.0.4
 specification_version: 4
 summary: a client to connect to SAT web services
 test_files: []