sat_mx 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24d8984a200bf9e2d95a2fcb90e10097f54a4ed496e418c3880df1848dd5c302
-  data.tar.gz: 01a221e8d1bcab95919dc4990677ca9c63bc775e1e1f03281c5c07be2653805c
+  metadata.gz: a6f23a9065a4facc1ea12963a7a27587c8055775cbb729e3070c0a5a2a8144cd
+  data.tar.gz: c043c861ed94a4cb049b3664f37b6a3b13e502917e28dd7b6f07608f15212485
 SHA512:
-  metadata.gz: 3e1905940a68f281204884f848fea09806e6cc7ce242389aba92154e95777d5563b0b400dd731832982f824c626f4353bf204138f75a5ca26b1f4db063adabbe
-  data.tar.gz: 3535c79dafbb37cc18fc887a3d266a7ce9f1474e4f0d5add1ae6cfae652c88e64dd72b7fc73867c4d9a82b941c5179a2f447943df63170ee8ad01a0c69f1e18c
+  metadata.gz: 7a4ca5be6421a81e686b084207556f320fc4294d0d9731d9febd8e4d303a49bf10dcbfde496d86d2a8eef72fb172d69b7948ae2812e79f9c950d6749e038c8d8
+  data.tar.gz: 6dfb7a7364d74260cb0eb5e804b19b2e113e3fbfd8a5a61baee671e22cb15a109618decae7c7851b941e07901e61b93ec9ba12ede074b736e08fe355717bc227

data/README.md

@@ -33,14 +33,15 @@ raise "Auth failed" unless result.success?
 
 token = result.value
 
-# 2. Request download
-result = SatMx.download_request(
+# 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,
-  issuing_rfc: "ABC010101ABC",
-  recipient_rfcs: ["XYZ020202XYZ"],
+  recipient_rfc: "ABC010101ABC",
   requester_rfc: "ABC010101ABC",
+  issuing_rfc: "XYZ020202XYZ",
+  document_status: "Vigente",
   access_token: token
 )
 raise "Request failed" unless result.success?
@@ -84,7 +85,7 @@ end
 | `SatMx.configure` | Configure certificate and private key |
 | `SatMx.configuration` | Get current configuration |
 | `SatMx.authenticate` | Get access token |
-| `SatMx.download_request` | Request CFDI download |
+| `SatMx.download_request_received` | Request download of received CFDI |
 | `SatMx.verify_request` | Check request status |
 | `SatMx.download_petition` | Download package |
 

data/lib/sat_mx/client.rb

@@ -33,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/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/version.rb

@@ -1,3 +1,3 @@
 module SatMx
-  VERSION = "0.3.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")
@@ -115,6 +117,71 @@ module SatMx
       )
     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(

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sat_mx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Oscar Rivas
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-23 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.11
-signing_key:
+rubygems_version: 4.0.4
 specification_version: 4
 summary: a client to connect to SAT web services
 test_files: []