Module: SatMx

Defined in:
lib/sat_mx.rb,
lib/sat_mx/body.rb,
lib/sat_mx/client.rb,
lib/sat_mx/result.rb,
lib/sat_mx/signer.rb,
lib/sat_mx/version.rb,
lib/sat_mx/configuration.rb,
lib/sat_mx/authentication.rb,
lib/sat_mx/verify_request.rb,
lib/sat_mx/download_request.rb,
lib/sat_mx/download_petition.rb,
lib/sat_mx/verify_request_body.rb,
lib/sat_mx/download_request_body.rb,
lib/sat_mx/download_petition_body.rb,
lib/sat_mx/download_request_received.rb,
lib/sat_mx/download_request_received_body.rb

Defined Under Namespace

Modules: Body Classes: Authentication, Client, Configuration, DownloadPetition, DownloadPetitionBody, DownloadRequest, DownloadRequestBody, DownloadRequestReceived, DownloadRequestReceivedBody, Error, Result, Signer, VerifyRequest, VerifyRequestBody, XmlAuthBody

Constant Summary collapse

VERSION = 
"0.4.1"

Class Method Summary collapse

Class Method Details

.authenticate(certificate: nil, private_key: nil) ⇒ SatMx::Result

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

Parameters:

  • certificate (OpenSSL::X509::Certificate, nil) (defaults to: nil) —

    Certificate object (uses configuration if nil)

  • private_key (OpenSSL::PKey::RSA, nil) (defaults to: nil) —

    Private key object (uses configuration if nil)

Returns:

  • (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 Also:



61
62
63
64
65
66
67
68
 
# File 'lib/sat_mx.rb', line 61

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

.configuration ⇒ Object 



36
37
38
 
# File 'lib/sat_mx.rb', line 36

def configuration
  @configuration ||= Configuration.new
end

.configure {|config| ... } ⇒ Object

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 = "path/to/certificate.cer" config = "path/to/private.key" config = "key_password" end

Yields:

  • (config) 


30
31
32
33
34
 
# File 'lib/sat_mx.rb', line 30

def configure
  config = {}
  yield(config)
  @configuration = Configuration.new(**config)
end

.download_petition(package_id:, requester_rfc:, access_token:, **options) ⇒ SatMx::Result

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

Parameters:

  • package_id (String) —

    The package ID from SatMx.verify_request

  • requester_rfc (String) —

    RFC of the requester

  • access_token (String) —

    Authentication token from SatMx.authenticate

  • certificate (String, nil) —

    Path to certificate file (uses configuration if nil)

  • private_key (String, nil) —

    Path to private key file (uses configuration if nil)

Returns:

  • (SatMx::Result) —

    A Result object containing:

    • success?: [Boolean] whether the download was successful
    • value: [String, nil] Base64 encoded ZIP content if successful, or mensaje: on failure
    • xml: [Nokogiri::XML::Document] the raw XML response from the service

See Also:



250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/sat_mx.rb', line 250

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

.download_request(start_date:, end_date:, request_type:, issuing_rfc:, recipient_rfcs:, requester_rfc:, access_token:, **options) ⇒ SatMx::Result

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

Parameters:

  • start_date (Time) —

    Start date for the search range

  • end_date (Time) —

    End date for the search range

  • request_type (Symbol) —

    Type of request (:cfdi or :retentions)

  • issuing_rfc (String) —

    RFC of the issuer

  • recipient_rfcs (Array<String>) —

    RFCs of the recipients

  • requester_rfc (String) —

    RFC of the requester

  • access_token (String) —

    Authentication token from SatMx.authenticate

  • certificate (String, nil) —

    Path to certificate file (uses configuration if nil)

  • private_key (String, nil) —

    Path to private key file (uses configuration if nil)

Returns:

  • (SatMx::Result) —

    A Result object containing:

    • success?: [Boolean] whether the request was successful
    • value: [String, nil] the request ID if successful, or mensaje: on failure
    • xml: [Nokogiri::XML::Document] the raw XML response from the service

See Also:



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/sat_mx.rb', line 104

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

.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) ⇒ SatMx::Result

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

Parameters:

  • start_date (Time) —

    Start date for the search range

  • end_date (Time) —

    End date for the search range

  • request_type (Symbol) —

    Type of request (:cfdi or :metadata)

  • access_token (String) —

    Authentication token from SatMx.authenticate

  • recipient_rfc (String) —

    RFC of the receiver (required)

  • requester_rfc (String, nil) (defaults to: nil) —

    RFC of the requester (optional)

  • issuing_rfc (String, nil) (defaults to: nil) —

    RFC of the issuer (optional)

  • complement (String, nil) (defaults to: nil) —

    Complement type to filter (e.g., "nomina12", "pagos10") This value is optional. If omitted, the SAT web service will return all documents.

  • document_status (String, nil) (defaults to: nil) —

    Document status filter (Todos, Cancelados, Vigentes) defaults to Todos

  • certificate (String, nil) —

    Certificate object (uses configuration if nil)

  • private_key (String, nil) —

    Private key object (uses configuration if nil)

Returns:

  • (SatMx::Result) —

    A Result object containing:

    • success?: [Boolean] whether the request was successful
    • value: [String, nil] the request ID if successful, or mensaje: on failure
    • xml: [Nokogiri::XML::Document] the raw XML response from the service

See Also:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/sat_mx.rb', line 156

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

.verify_request(request_id:, requester_rfc:, access_token:, **options) ⇒ SatMx::Result

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

Parameters:

  • request_id (String) —

    The ID returned from SatMx.download_request

  • requester_rfc (String) —

    RFC of the requester

  • access_token (String) —

    Authentication token from SatMx.authenticate

  • certificate (String, nil) —

    Path to certificate file (uses configuration if nil)

  • private_key (String, nil) —

    Path to private key file (uses configuration if nil)

Returns:

  • (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 mensaje: on failure
    • xml: [Nokogiri::XML::Document] the raw XML response from the service

See Also:



212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/sat_mx.rb', line 212

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