sat_mx 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1d5bf99d58cf85c782f3b4154b95ec56f8e3dcc1d3b8081d5199052e43decb9
-  data.tar.gz: 3e2b16a973bebaddec739002feaa9bfe144d276bdb3ca81d3d57a84e903f3af6
+  metadata.gz: 24d8984a200bf9e2d95a2fcb90e10097f54a4ed496e418c3880df1848dd5c302
+  data.tar.gz: 01a221e8d1bcab95919dc4990677ca9c63bc775e1e1f03281c5c07be2653805c
 SHA512:
-  metadata.gz: 8e29de979da7288e094a4f668d2944c8b4af02193a9c85912101edd383cfc7494bb03074b4f3ed5e4fd103d2d09e5a76a8b0fb558f087a3bf93610ecb2e27490
-  data.tar.gz: 9dbc83b0df6d6af8d2c06296fb727ca19566d3bded5b3d77f949a048f36b60024bfdcb3aa50cafc4150f664f5df0ca4d4b5a24c7b1235e47239aedf7aeb4ecf2
+  metadata.gz: 3e1905940a68f281204884f848fea09806e6cc7ce242389aba92154e95777d5563b0b400dd731832982f824c626f4353bf204138f75a5ca26b1f4db063adabbe
+  data.tar.gz: 3535c79dafbb37cc18fc887a3d266a7ce9f1474e4f0d5add1ae6cfae652c88e64dd72b7fc73867c4d9a82b941c5179a2f447943df63170ee8ad01a0c69f1e18c

data/README.md

@@ -1,39 +1,98 @@
 # 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
+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: 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` | Request CFDI download |
+| `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/Rakefile

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 

data/lib/sat_mx/{bulk_download.rb → authentication.rb}

@@ -1,43 +1,39 @@
-require "openssl"
 require "httpx"
-require "xmldsig"
 require "time"
+require "base64"
 
 module SatMx
-  Result = Data.define(:success?, :value)
-
-  class BulkDownload
-    AUTH_URL = "https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/Autenticacion/Autenticacion.svc".freeze
-    HEADERS = {
-      "content-type" => "text/xml; charset=utf-8",
-      "accept" => "text/xml",
-      "SOAPAction" => "http://DescargaMasivaTerceros.gob.mx/IAutenticacion/Autentica"
-    }.freeze
-    private_constant :AUTH_URL
-    private_constant :HEADERS
-
-    def self.authenticate(certificate:, private_key:, id: nil)
+  # @api private
+  class Authentication
+    def self.authenticate(certificate:, private_key:, uuid: SecureRandom.uuid)
       new(
-        xml_auth_body: XmlAuthBody.new(certificate:, private_key:, id:)
+        xml_auth_body: XmlAuthBody.new(
+          certificate:,
+          uuid:
+        ),
+        client: Client.new(
+          private_key:,
+          access_token: ""
+        )
       ).authenticate
     end
 
-    def initialize(xml_auth_body:)
+    def initialize(xml_auth_body:, client:)
       @xml_auth_body = xml_auth_body
+      @client = client
     end
 
     def authenticate
-      response = HTTPX.post(
-        AUTH_URL,
-        headers: HEADERS,
-        body: xml_auth_body.sign
-      )
+      response = client.authenticate(xml_auth_body.generate)
 
       case response.status
       when 200..299
-        Result.new(success?: true, value: response.xml)
+        Result.new(success?: true,
+          value: response.xml.xpath("//xmlns:AutenticaResult",
+            xmlns: "http://DescargaMasivaTerceros.gob.mx").inner_text,
+          xml: response.xml)
       when 400..599
-        Result.new(success?: false, value: response.xml)
+        Result.new(success?: false, value: nil, xml: response.xml)
       else
         SatMx::Error
       end
@@ -45,39 +41,29 @@ module SatMx
 
     private
 
-    attr_reader :xml_auth_body
+    attr_reader :xml_auth_body, :client
   end
 
+  # @api private
   class XmlAuthBody
-    def initialize(certificate:, private_key:, id: "uuid-#{SecureRandom.uuid}-1")
+    def initialize(certificate:, uuid:)
       @certificate = certificate
-      @private_key = private_key
-      @id = id
+      @uuid = uuid
     end
 
-    def sign
-      Xmldsig::SignedDocument.new(xml_document).sign do |data|
-        private_key.sign(OpenSSL::Digest.new("SHA1"), data)
-      end
-    end
-
-    private
-
-    attr_reader :private_key, :certificate, :id
-
-    def xml_document
+    def generate
       <<~XML
         <S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
           <S11:Header>
             <wsse:Security S11:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
               #{timestamp}
-              <wsse:BinarySecurityToken wsu:Id="#{id}" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">#{Base64.strict_encode64(certificate.to_der)}</wsse:BinarySecurityToken>
+              <wsse:BinarySecurityToken wsu:Id="#{uuid}" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">#{Base64.strict_encode64(certificate.to_der)}</wsse:BinarySecurityToken>
               <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
                 #{signed_info}
                 <SignatureValue></SignatureValue>
                 <KeyInfo>
                   <wsse:SecurityTokenReference>
-                    <wsse:Reference ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" URI="##{id}" />
+                    <wsse:Reference ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" URI="##{uuid}" />
                   </wsse:SecurityTokenReference>
                 </KeyInfo>
               </Signature>
@@ -90,6 +76,10 @@ module SatMx
       XML
     end
 
+    private
+
+    attr_reader :certificate
+
     def timestamp
       current_time = Time.now.utc
       <<~XML
@@ -115,5 +105,9 @@ module SatMx
         </SignedInfo>
       XML
     end
+
+    def uuid
+      "uuid-#{@uuid}-1"
+    end
   end
 end

data/lib/sat_mx/body.rb

@@ -0,0 +1,66 @@
+require "base64"
+
+module SatMx
+  # @api private
+  module Body
+    S11 = "S11"
+    XMLNS = "xmlns"
+    DES = "des"
+    DS = "ds"
+
+    ENVELOPE_ATTRS = {
+      "#{XMLNS}:#{S11}" => "http://schemas.xmlsoap.org/soap/envelope/",
+      "#{XMLNS}:#{DES}" => "http://DescargaMasivaTerceros.sat.gob.mx",
+      "#{XMLNS}:#{DS}" => "http://www.w3.org/2000/09/xmldsig#"
+    }.freeze
+
+    NAMESPACE = ENVELOPE_ATTRS["#{XMLNS}:#{DES}"]
+
+    private
+
+    def envelope
+      Nokogiri::XML::Builder.new do |xml|
+        xml[S11].Envelope(
+          ENVELOPE_ATTRS
+        ) do
+          xml[S11].Header
+          xml[S11].Body do
+            yield xml
+          end
+        end
+      end.doc.root.to_xml
+    end
+
+    def signature(xml)
+      xml.Signature(XMLNS => "http://www.w3.org/2000/09/xmldsig#") do
+        xml.SignedInfo do
+          xml.CanonicalizationMethod("Algorithm" => "http://www.w3.org/TR/2001/REC-xml-c14n-20010315")
+          xml.SignatureMethod("Algorithm" => "http://www.w3.org/2000/09/xmldsig#rsa-sha1")
+          xml.Reference("URI" => "") do
+            xml.Transforms do
+              xml.Transform("Algorithm" => "http://www.w3.org/2000/09/xmldsig#enveloped-signature")
+            end
+            xml.DigestMethod("Algorithm" => "http://www.w3.org/2000/09/xmldsig#sha1")
+            xml.DigestValue
+          end
+        end
+        xml.SignatureValue
+        xml.KeyInfo do
+          xml.X509Data do
+            xml.X509IssuerSerial do
+              xml.X509IssuerName(certificate_issuer)
+              xml.X509SerialNumber(certificate_serial)
+            end
+            xml.X509Certificate(encoded_certificate)
+          end
+        end
+      end
+    end
+
+    def certificate_issuer = certificate.issuer.to_s(OpenSSL::X509::Name::RFC2253)
+
+    def certificate_serial = certificate.serial
+
+    def encoded_certificate = Base64.strict_encode64(certificate.to_der)
+  end
+end

data/lib/sat_mx/client.rb

@@ -0,0 +1,70 @@
+module SatMx
+  # @api private
+  class Client
+    HEADERS = {
+      "content-type" => "text/xml; charset=utf-8",
+      "accept" => "text/xml"
+    }.freeze
+    private_constant :HEADERS
+
+    def initialize(private_key:, access_token:)
+      @private_key = private_key
+      @access_token = access_token
+    end
+
+    def authenticate(payload)
+      HTTPX.post(
+        "https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/Autenticacion/Autenticacion.svc",
+        headers: {
+          "SOAPAction" => "http://DescargaMasivaTerceros.gob.mx/IAutenticacion/Autentica"
+        }.merge(HEADERS),
+        body: sign(payload)
+      )
+    end
+
+    def download_request(payload)
+      HTTPX.post(
+        "https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/SolicitaDescargaService.svc",
+        headers: {
+          "SOAPAction" => "http://DescargaMasivaTerceros.sat.gob.mx/ISolicitaDescargaService/SolicitaDescarga"
+        }.merge(authorization)
+        .merge(HEADERS),
+        body: sign(payload)
+      )
+    end
+
+    def verify_request(payload)
+      HTTPX.post(
+        "https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/VerificaSolicitudDescargaService.svc",
+        headers: {
+          "SOAPAction" => "http://DescargaMasivaTerceros.sat.gob.mx/IVerificaSolicitudDescargaService/VerificaSolicitudDescarga"
+        }.merge(authorization)
+        .merge(HEADERS),
+        body: sign(payload)
+      )
+    end
+
+    def download_petition(payload)
+      HTTPX.post(
+        "https://cfdidescargamasiva.clouda.sat.gob.mx/DescargaMasivaService.svc",
+        headers: {
+          "SOAPAction" => "http://DescargaMasivaTerceros.sat.gob.mx/IDescargaMasivaTercerosService/Descargar"
+        }.merge(authorization)
+        .merge(HEADERS),
+        body: sign(payload)
+      )
+    end
+
+    private
+
+    attr_reader :private_key, :access_token
+
+    def authorization
+      {"Authorization" => "WRAP access_token=\"#{access_token}\""}
+    end
+
+    def sign(payload)
+      Signer.sign(document: payload, private_key:)
+    end
+  end
+end

data/lib/sat_mx/configuration.rb

@@ -0,0 +1,14 @@
+module SatMx
+  # @api private
+  Configuration = Data.define(:certificate, :private_key) do
+    def initialize(certificate:, private_key:, password:)
+      super(
+        certificate: OpenSSL::X509::Certificate.new(File.read(certificate)),
+        private_key: OpenSSL::PKey::RSA.new(
+          File.read(private_key),
+          password
+        )
+      )
+    end
+  end
+end

data/lib/sat_mx/download_petition.rb

@@ -0,0 +1,65 @@
+module SatMx
+  # @api private
+  class DownloadPetition
+    def self.call(package_id:, requester_rfc:, access_token:, certificate:, private_key:)
+      new(
+        body: DownloadPetitionBody.new(
+          package_id:,
+          requester_rfc:,
+          certificate:
+        ),
+        client: Client.new(private_key:, access_token:)
+      ).call
+    end
+
+    def initialize(body:, client:)
+      @body = body
+      @client = client
+    end
+
+    def call
+      response = client.download_petition(body.generate)
+
+      case response.status
+      when 200..299
+        xml = response.xml
+        response_tag = xml.xpath(
+          "//xmlns:respuesta",
+          xmlns: "http://DescargaMasivaTerceros.sat.gob.mx"
+        )[0]
+
+        if response_tag["CodEstatus"] == "5000"
+          Result.new(
+            success?: true,
+            xml: response.xml,
+            value: response.xml.xpath(
+              "//xmlns:Paquete",
+              xmlns: "http://DescargaMasivaTerceros.sat.gob.mx"
+            ).inner_text
+          )
+        else
+          Result.new(
+            success?: false,
+            xml: response.xml,
+            value: {
+              cod_estatus: response_tag["CodEstatus"],
+              mensaje: response_tag["Mensaje"]
+            }
+          )
+        end
+      when 400..599
+        Result.new(
+          success?: false,
+          xml: nil,
+          value: nil
+        )
+      else
+        SatMx::Error
+      end
+    end
+
+    private
+
+    attr_reader :client, :body
+  end
+end

data/lib/sat_mx/download_petition_body.rb

@@ -0,0 +1,29 @@
+module SatMx
+  # @api private
+  class DownloadPetitionBody
+    include Body
+
+    def initialize(package_id:, requester_rfc:, certificate:)
+      @package_id = package_id
+      @requester_rfc = requester_rfc
+      @certificate = certificate
+    end
+
+    def generate
+      envelope do |xml|
+        xml[Body::DES].PeticionDescargaMasivaTercerosEntrada do
+          xml[Body::DES].peticionDescarga(
+            IdPaquete: package_id,
+            RfcSolicitante: requester_rfc
+          ) do
+            signature(xml)
+          end
+        end
+      end
+    end
+
+    private
+
+    attr_reader :package_id, :requester_rfc, :certificate
+  end
+end

data/lib/sat_mx/download_request.rb

@@ -0,0 +1,68 @@
+module SatMx
+  # @api private
+  class DownloadRequest
+    def self.call(start_date:,
+      end_date:,
+      request_type:,
+      issuing_rfc:,
+      recipient_rfcs:,
+      requester_rfc:,
+      access_token:,
+      certificate:,
+      private_key:)
+      new(
+        download_request_body: DownloadRequestBody.new(
+          start_date:,
+          end_date:,
+          request_type:,
+          issuing_rfc:,
+          recipient_rfcs:,
+          requester_rfc:,
+          certificate:
+        ),
+        client: Client.new(private_key:, access_token:)
+      ).call
+    end
+
+    def initialize(download_request_body:, client:)
+      @download_request_body = download_request_body
+      @client = client
+    end
+
+    def call
+      response = client.download_request(download_request_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
+        SatMx::Error
+      end
+    end
+
+    private
+
+    attr_reader :download_request_body, :client
+
+    def check_body_status(xml)
+      download_result_tag = xml.xpath("//xmlns:SolicitaDescargaResult",
+        xmlns: Body::NAMESPACE)
+      if download_result_tag.attr("CodEstatus").value == "5000"
+        Result.new(success?: true,
+          value: download_result_tag.attr("IdSolicitud").value,
+          xml: 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_body.rb

@@ -0,0 +1,60 @@
+require "time"
+
+module SatMx
+  # @api private
+  class DownloadRequestBody
+    include Body
+
+    REQUEST_TYPES = {
+      cfdi: "CFDI",
+      metadata: "Metadata"
+    }.freeze
+
+    def initialize(start_date:,
+      end_date:,
+      request_type:,
+      issuing_rfc:,
+      recipient_rfcs:,
+      requester_rfc:,
+      certificate:)
+      @start_date = start_date
+      @end_date = end_date
+      @request_type = request_type
+      @issuing_rfc = issuing_rfc
+      @recipient_rfcs = recipient_rfcs
+      @requester_rfc = requester_rfc
+      @certificate = certificate
+    end
+
+    def generate
+      envelope do |xml|
+        xml[Body::DES].SolicitaDescarga do
+          xml[Body::DES].solicitud(
+            "FechaInicial" => start_date,
+            "FechaFinal" => end_date,
+            "RfcEmisor" => issuing_rfc,
+            "RfcSolicitante" => requester_rfc,
+            "TipoSolicitud" => request_type
+          ) do
+            xml[Body::DES].RfcReceptores do
+              @recipient_rfcs.each do |rfc|
+                xml[Body::DES].RfcReceptor(rfc)
+              end
+            end
+            signature(xml)
+          end
+        end
+      end
+    end
+
+    private
+
+    attr_reader :issuing_rfc, :requester_rfc, :certificate
+
+    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

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

data/lib/sat_mx/signer.rb

@@ -0,0 +1,26 @@
+require "openssl"
+require "xmldsig"
+
+module SatMx
+  # @api private
+  class Signer
+    def self.sign(document:, private_key:)
+      new(document:, private_key:).sign
+    end
+
+    def initialize(document:, private_key:)
+      @unsigned_document = Xmldsig::SignedDocument.new(document)
+      @private_key = private_key
+    end
+
+    def sign
+      unsigned_document.sign do |data|
+        private_key.sign(OpenSSL::Digest.new("SHA1"), data)
+      end
+    end
+
+    private
+
+    attr_reader :unsigned_document, :private_key
+  end
+end

data/lib/sat_mx/verify_request.rb

@@ -0,0 +1,70 @@
+module SatMx
+  # @api private
+  class VerifyRequest
+    STATUS = {
+      "1" => :accepted,
+      "2" => :in_proccess,
+      "3" => :finished,
+      "4" => :error,
+      "5" => :rejected,
+      "6" => :expired
+    }
+    private_constant :STATUS
+
+    def self.call(request_id:, requester_rfc:, access_token:, private_key:, certificate:)
+      new(
+        body: VerifyRequestBody.new(request_id:, requester_rfc:, certificate:),
+        client: Client.new(private_key:, access_token:)
+      ).call
+    end
+
+    def initialize(body:, client:)
+      @body = body
+      @client = client
+    end
+
+    def call
+      response = client.verify_request(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
+        SatMx::Error
+      end
+    end
+
+    private
+
+    attr_reader :body, :client
+
+    def check_body_status(xml)
+      download_result_tag = xml.xpath("//xmlns:VerificaSolicitudDescargaResult",
+        xmlns: Body::NAMESPACE)
+      if download_result_tag.attr("CodEstatus").value == "5000"
+        Result.new(success?: true,
+          value: value(download_result_tag, xml),
+          xml: xml)
+      else
+        Result.new(
+          success?: false,
+          value: {
+            cod_status: download_result_tag.attr("CodEstatus").value,
+            mensaje: download_result_tag.attr("Mensaje").value
+          },
+          xml:
+        )
+      end
+    end
+
+    def value(tag, xml)
+      {
+        request_status: STATUS.fetch(
+          tag.attribute("EstadoSolicitud").value
+        ),
+        package_ids: xml.xpath("//xmlns:IdsPaquetes", xmlns: Body::NAMESPACE).map(&:inner_text)
+      }
+    end
+  end
+end

data/lib/sat_mx/verify_request_body.rb

@@ -0,0 +1,29 @@
+module SatMx
+  # @api private
+  class VerifyRequestBody
+    include Body
+
+    def initialize(certificate:, request_id:, requester_rfc:)
+      @certificate = certificate
+      @request_id = request_id
+      @requester_rfc = requester_rfc
+    end
+
+    def generate
+      envelope do |xml|
+        xml[Body::DES].VerificaSolicitudDescarga do
+          xml[Body::DES].solicitud(
+            "IdSolicitud" => request_id,
+            "RfcSolicitante" => requester_rfc
+          ) do
+            signature(xml)
+          end
+        end
+      end
+    end
+
+    private
+
+    attr_reader :certificate, :request_id, :requester_rfc
+  end
+end

data/lib/sat_mx/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module SatMx
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/sat_mx.rb

@@ -1,8 +1,195 @@
-# frozen_string_literal: true
-
+require "httpx"
 require_relative "sat_mx/version"
 
 module SatMx
   class Error < StandardError; end
-  autoload(:BulkDownload, "sat_mx/bulk_download")
+  autoload(:Configuration, "sat_mx/configuration")
+  autoload(:Authentication, "sat_mx/authentication")
+  autoload(:DownloadRequest, "sat_mx/download_request")
+  autoload(:DownloadRequestBody, "sat_mx/download_request_body")
+  autoload(:VerifyRequest, "sat_mx/verify_request")
+  autoload(:VerifyRequestBody, "sat_mx/verify_request_body")
+  autoload(:DownloadPetition, "sat_mx/download_petition")
+  autoload(:DownloadPetitionBody, "sat_mx/download_petition_body")
+  autoload(:Body, "sat_mx/body")
+  autoload(:Result, "sat_mx/result")
+  autoload(:Signer, "sat_mx/signer")
+  autoload(:Client, "sat_mx/client")
+
+  class << self
+    # Configures the gem using a block, its not threadsafe, so its recommended call only when you're initializing
+    # your application, e.g. in your initializers directory of your rails app
+    #  @example
+    #   SatMx.configure do |config|
+    #     config[:certificate] = "path/to/certificate.cer"
+    #     config[:private_key] = "path/to/private.key"
+    #     config[:password] = "key_password"
+    #   end
+    def configure
+      config = {}
+      yield(config)
+      @configuration = Configuration.new(**config)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Authenticates with the SAT web service using the configured certificate and private key.
+    # This method uses SOAP to communicate with the SAT authentication service and returns
+    # a token that can be used for subsequent requests.
+    #
+    #   result = SatMx.authenticate
+    #   if result.success?
+    #     puts "Authentication token: #{result.value}"
+    #   else
+    #     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
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::Authentication
+    # @see SatMx::Result
+    def authenticate(certificate: nil, private_key: nil)
+      cert = certificate || configuration.certificate
+      key = private_key || configuration.private_key
+      Authentication.authenticate(
+        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
+
+    # 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
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sat_mx
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Oscar Rivas
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-03 00:00:00.000000000 Z
+date: 2026-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xmldsig
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -109,7 +123,18 @@ files:
 - README.md
 - Rakefile
 - lib/sat_mx.rb
-- lib/sat_mx/bulk_download.rb
+- lib/sat_mx/authentication.rb
+- lib/sat_mx/body.rb
+- lib/sat_mx/client.rb
+- lib/sat_mx/configuration.rb
+- lib/sat_mx/download_petition.rb
+- lib/sat_mx/download_petition_body.rb
+- lib/sat_mx/download_request.rb
+- lib/sat_mx/download_request_body.rb
+- lib/sat_mx/result.rb
+- lib/sat_mx/signer.rb
+- lib/sat_mx/verify_request.rb
+- lib/sat_mx/verify_request_body.rb
 - lib/sat_mx/version.rb
 - sig/sat_mx.rbs
 homepage: https://github.com/kadru/sat_mx
@@ -118,7 +143,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/kadru/sat_mx
   changelog_uri: https://github.com/kadru/sat_mx/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -134,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.11
-signing_key: 
+signing_key:
 specification_version: 4
 summary: a client to connect to SAT web services
 test_files: []