MX-Banxico 1.0.2

data/lib/MX/Banxico/version.rb

@@ -0,0 +1,14 @@
+# Módulo para todo lo relacionado con México.
+#
+module MX
+  
+  # Herramientas para trabajar con información del Banco de México (Banxico).
+  #
+  module Banxico
+    
+    # Versión de la gema.
+    #
+    VERSION = "1.0.2"
+    
+  end
+end

data/lib/MX/Banxico/web_services.rb

@@ -0,0 +1,4 @@
+# Módulo para los webservices soportados.
+#
+module MX::Banxico::WebServices
+end

data/lib/MX/Banxico/web_services/tipo_de_cambio.rb

@@ -0,0 +1,83 @@
+# Modelo para conectarse al servicio web de Banxico y obtener los tipos de cambio vigentes al día de hoy.
+#
+# Esta clase hereda de {MX::Banxico::WebServices::WebService} para especializarse en la recuperación de los tipos de cambio.
+#
+class MX::Banxico::WebServices::TipoDeCambio < MX::Banxico::WebServices::WebService
+  
+  
+  # Tipos de cambio soportados.
+  #
+  TIPOS_DE_CAMBIO = MX::Banxico::Series.tipos_de_cambio.keys.dup.freeze
+  
+  # Inicialización del cliente de {http://savonrb.com/version2/testing.html Savon}.
+  #
+  self.init_client
+  
+  # @!method operations
+  # Operaciones soportadas en este web service via {http://savonrb.com/version2/testing.html Savon}.
+  #
+  operations :tipos_de_cambio_banxico
+
+  
+  # Obtiene el tipo de cambio del día.
+  #
+  # @param tipo [Symbol] el tipo de cambio deseado. Ver {TIPOS_DE_CAMBIO}.
+  # @param intentos [Ingeger] el número de intentos para obtener el tipo de cambio.
+  #
+  # @return [MX::Banxico::TipoDeCambio] si la petición es exitosa, la estructura con el tipo de cambio.
+  # @return [String] si la petición no es exitosa, una cadena con la descripción del error.
+  #
+  # @raise [ArgumentError] cuando el tipo dado no está soportado. Ver {TIPOS_DE_CAMBIO}.
+  #
+  def obtener(tipo, intentos = 5)
+    raise ArgumentError.new("El tipo de cambio no está soportado (#{tipo}).") unless TIPOS_DE_CAMBIO.member?(tipo.to_sym)
+    respuesta = realizar_operacion(:tipos_de_cambio_banxico, intentos)
+    if respuesta.errores?
+      return respuesta.errores
+    else
+      xml_doc_cuerpo_respuesta = Nokogiri::XML(respuesta.cuerpo, nil, CODIFICACION_WS )
+      nodo_valor = xml_doc_cuerpo_respuesta.root.at_xpath(xpath_tipo_de_cambio(tipo))
+      if nodo_valor
+        tdc_o_error = procesar_nodo_obs_tipo_de_cambio(nodo_valor, tipo)
+        return tdc_o_error
+      else
+        return "No fue posible extraer los valores del XML del nodo bm:Obs al consultar el servicio web." +
+          " Operación: #{:tipos_de_cambio_banxico}. XPath: #{xpath_tipo_de_cambio(tipo)}." +
+          "\n\n #{respuesta.cuerpo}"
+      end
+    end
+  end
+
+
+
+  private
+    
+    # Procesa el nodo del XML de la respuesta de la petición que contiene la información del tipo de cambio.
+    #
+    # @param nodo_valor [Nokogiri::XML::Node] nodo de la serie con el valor y fecha del tipo de cambio (bm:Obs).
+    # @param tipo [Symbol] el tipo de cambio solicitado. Ver {TIPOS_DE_CAMBIO}.
+    #
+    # @return [MX::Banxico::TipoDeCambio] si la obtención del valor y la fecha es exitosa, la estructura con el tipo de cambio.
+    # @return [String] si la obtención del valor y la fecha no es exitosa, una cadena con la descripción del error.
+    #
+    def procesar_nodo_obs_tipo_de_cambio(nodo_valor, tipo)
+      begin
+        return MX::Banxico::TipoDeCambio.new(tipo, nodo_valor[:TIME_PERIOD], nodo_valor[:OBS_VALUE])
+      rescue ArgumentError => e
+        return "Error al crear el tipo de cambio a partir del nodo bm:Obs. Error: #{e.message}"
+      end
+    end
+
+    # XPath con la ruta del nodo `bm:Obs` del identificador de la serie de acuerdo a su tipo.
+    #
+    # @param tipo [Symbol] el tipo de cambio solicitado. Ver {TIPOS_DE_CAMBIO}.
+    #
+    # @return [String] la ruta (XPath) del nodo de la serie de acuerdo al tipo dado.
+    #
+    def xpath_tipo_de_cambio(tipo)
+      id = MX::Banxico::Series.identificador(:tipos_de_cambio, tipo)
+      %Q{bm:DataSet/bm:Series[@IDSERIE="#{id}"]/bm:Obs}
+    end
+
+
+end

data/lib/MX/Banxico/web_services/web_service.rb

@@ -0,0 +1,99 @@
+#
+# Modelo para conectarse al servicio web de Banxico por medio de Savon::Model.
+#
+#
+# @note Savon crea métodos por omisión de acuerdo a las operaciones soportadas por el servicio web, tano a nivel
+#   de clase como de instancia.
+#
+class MX::Banxico::WebServices::WebService
+  extend Savon::Model
+  
+  
+  # Estructura para guardar el cuerpo de la respuesta de una operación o los errores
+  #
+  Respuesta = Struct.new(:cuerpo, :errores) do
+    
+    # Determina si la operación fue exitosa.
+    #
+    # @return `true` si tuvo éxito, `false` de lo contrario.
+    #
+    def exito?
+      errores.nil?
+    end
+    
+    # Determina si hubo errores en al efectuar la operación.
+    #
+    # @return `true` si hubieron errores, `false` de lo contrario.
+    #
+    def errores?
+      !exito?
+    end
+    
+  end
+  
+  
+  # URL con la definición del servicio web.
+  #
+  WSDL = "http://www.banxico.org.mx/DgieWSWeb/DgieWS?WSDL"
+
+  # Codificación de la petición y respuesta del servicio
+  # ¡guácala, no es UTF-8 la codificación que manejan en Banxico!
+  #
+  CODIFICACION_WS = "ISO-8859-1"
+  
+
+  # Operaciones soportadas por el servicio web de Banxico:
+  # * Reservas internacionales
+  # * Tasas de interés
+  # * Tipos de Cambio
+  # * UDIS
+  #
+  OPERACIONES_WS = [ :reservas_internacionales_banxico, :tasas_de_interes_banxico, :tipos_de_cambio_banxico, :udis_banxico ]
+
+  # @!method client
+  # Definición del cliente de Savon
+  #
+  
+  # Inicializa el cliente de Savon.
+  #
+  def self.init_client
+    client wsdl: WSDL, encoding: CODIFICACION_WS, open_timeout: 5, read_timeout: 5
+  end
+  
+  # Inicialización del cliente de Savon
+  #
+  self.init_client
+  
+  # Realiza la operación solicitada en un máximo de intentos dados.
+  #
+  # @param op [Symbol] el nombre de la operación soportada a efectuarse. Ver {OPERACIONES_WS}.
+  # @param intentos [Fixnum] el número de intentos en los que se tratará de recuperar la respuesta de la operación.
+  #
+  # @return [Hash] con el cuerpo de la respuesta de la operación en la llave `:cuerpo` o una descripción de los errores
+  #   ocurridos  en la llave `:errores`.
+  #
+  def realizar_operacion(op, intentos = 5)
+    raise ArgumentError.new("La operación #{op} no está soportada.") unless OPERACIONES_WS.member?(op.to_sym)
+    raise ArgumentError.new("El número de intentos debe ser mayor o igual a 1.") if (!intentos.is_a?(Integer) or intentos < 1)
+    errores = ""
+    1.upto(intentos) do |intento|
+      begin
+        resp = client.call(op.to_sym)
+        return Respuesta.new(resp.body[:"#{op}_response"][:result]) if resp.success?
+      rescue Exception => e
+        errores = "#{errores}Intento #{intento}: #{e.message}. "
+      end
+      errores = "#{errores}Número de intentos agotados #{intentos}." if intento == intentos
+    end
+    Respuesta.new(nil, errores)
+  end
+  
+  # Arreglo con las operaciones soportadas por el servicio web.
+  #
+  # @return [Array] un arreglo con las operaciones soportados.
+  #
+  def self.operaciones
+    OPERACIONES_WS
+  end
+  
+end

data/spec/MX/Banxico/historico/tipo_de_cambio_spec.rb

@@ -0,0 +1,525 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../../spec_helper')
+require 'webmock/rspec'
+
+describe MX::Banxico::Historico::TipoDeCambio, :tipo_de_cambio_historico do
+  let!(:post_url){ "#{described_class::URL}#{described_class::POST_PATH}" }
+  
+  before(:context) { WebMock.disable! }
+  after(:context) { WebMock.reset! }
+  
+  
+  describe '#de_serie' do
+    
+    context 'cuando no existe la serie' do
+      let!(:serie){ :serie_inexistente }
+      let!(:historico_tdc){ described_class.new }
+      let!(:arr){ historico_tdc.de_serie(serie) }
+      
+      it 'es nil' do
+        historico_tdc = described_class.new
+        expect(historico_tdc.de_serie(:serie_inexistente)).to be_nil
+      end
+      
+      
+      describe '#errores' do
+        
+        it 'es la descripción del error' do
+          expect(historico_tdc.errores).to eq "Error: La serie no existe (serie: #{serie})."
+        end
+        
+      end
+      
+      
+      describe '#errores?' do
+        
+        it 'es true' do
+          expect(historico_tdc.errores?).to be_truthy
+        end
+        
+      end
+
+    end
+    
+    
+    context 'cuando la petición tuvo éxito' do
+      
+      context 'cuando no es una respuesta satisfactoria' do
+        before(:context) { WebMock.enable! }
+        let!(:serie){ :dolar_fix }
+        
+        [404, 500].each do |codigo|
+          
+          context "cuando no se encontró la página (#{codigo})" do
+            let!(:req){ stub_request(:any, post_url).to_return(status: codigo) }
+            let(:historico_tdc){ described_class.new }
+            let!(:arr){ historico_tdc.de_serie(serie) }
+
+            it 'es nil' do
+              expect(arr).to be_nil
+            end
+          
+          
+            describe '#errores' do
+              
+              it 'es la descripción del error' do
+                expect(historico_tdc.errores).to eq "Error: código de error #{codigo}."
+              end
+              
+            end
+            
+            
+            describe '#errores?' do
+              
+              it 'es true' do
+                expect(historico_tdc.errores?).to be_truthy
+              end
+              
+            end
+            
+          end
+        
+        end
+        
+      end
+      
+      
+      context 'cuando se obtuvo una respuesta satisfactoria (200 - OK)' do
+        let!(:serie){ :dolar_fix }
+        let!(:año){ 2015 }
+        
+        context 'cuando la respuesta tiene series' do
+          let(:historico_tdc){ described_class.new }
+          
+          
+          context 'cuando se realiza una conexión al servicio' do
+            before(:context) { WebMock.disable! }
+            let!(:arr){ historico_tdc.de_serie(serie, año, año) }
+          
+            it 'es un arreglo de MX::Banxico::TipoDeCambio' do
+              expect(arr).to be_a Array
+              arr.each do |tdc|
+                expect(tdc).to be_a MX::Banxico::TipoDeCambio
+                expect(tdc.moneda).to eq serie
+              end
+            end
+          
+            it 'el arreglo tiene un elemento por cada día el año' do
+              expect(arr.size).to eq dias_tipos_de_cambio_2015(serie)
+            end
+            
+            
+            describe '#errores' do
+        
+              it 'es la descripción del error' do
+                expect(historico_tdc.errores).to be_nil
+              end
+        
+            end
+      
+      
+            describe '#errores?' do
+        
+              it 'es true' do
+                expect(historico_tdc.errores?).to be_falsey
+              end
+        
+            end
+            
+          end
+          
+          
+          context 'cuando se usa un stub de la conexión' do
+            before(:context) { WebMock.enable! }
+            let!(:cuerpo_ok){ File.read("spec/fixtures/MX/Banxico/historico/tipo_de_cambio/dolar_fix/respuesta_correcta.xml") }
+            let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo_ok) }
+            let!(:arr){ historico_tdc.de_serie(serie, año, año) }
+          
+            it 'es un arreglo de MX::Banxico::TipoDeCambio' do
+              expect(arr).to be_a Array
+              arr.each do |tdc|
+                expect(tdc).to be_a MX::Banxico::TipoDeCambio
+                expect(tdc.moneda).to eq serie
+              end
+            end
+          
+            it 'el arreglo tiene un elemento por cada día el año' do
+              expect(arr.size).to eq dias_tipos_de_cambio_2015(serie)
+            end
+            
+            
+            describe '#errores' do
+        
+              it 'es la descripción del error' do
+                expect(historico_tdc.errores).to be_nil
+              end
+        
+            end
+      
+      
+            describe '#errores?' do
+        
+              it 'es true' do
+                expect(historico_tdc.errores?).to be_falsey
+              end
+        
+            end
+            
+          end
+          
+        end
+        
+        
+        context 'cuando la respuesta no tiene serie' do
+          before(:context) { WebMock.enable! }
+          let!(:cuerpo_sin_series){ File.read("spec/fixtures/MX/Banxico/historico/tipo_de_cambio/dolar_fix/sin_serie.xml") }
+          let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo_sin_series) }
+          let!(:historico_tdc){ described_class.new }
+          let!(:arr){ historico_tdc.de_serie(serie, año, año) }
+          
+          it 'es nil' do
+            expect(arr).to be_nil
+          end
+            
+            
+          describe '#errores' do
+            
+            it 'es la descripción del error' do
+              expect(historico_tdc.errores).to eq "Error: No se encontró información de la serie #{serie} dentro de la respuesta de la petición."
+            end
+      
+          end
+          
+          
+          describe '#errores?' do
+            
+            it 'es true' do
+              expect(historico_tdc.errores?).to be_truthy
+            end
+            
+          end
+          
+        end
+        
+        
+        context 'cuando la respuesta tiene series sin tipos de cambio' do
+          before(:context) { WebMock.enable! }
+          let!(:cuerpo_sin_tdc){ File.read("spec/fixtures/MX/Banxico/historico/tipo_de_cambio/dolar_fix/serie_sin_valores.xml") }
+          let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo_sin_tdc) }
+          let!(:historico_tdc){ described_class.new }
+          let!(:arr){ historico_tdc.de_serie(serie, año, año) }
+          
+          it 'es nil' do
+            expect(arr).to be_nil
+          end
+            
+            
+          describe '#errores' do
+      
+            it 'es la descripción del error' do
+              expect(historico_tdc.errores).to eq "Error: No se encontró información de la serie #{serie} dentro de la respuesta de la petición."
+            end
+            
+          end
+          
+          
+          describe '#errores?' do
+            
+            it 'es true' do
+              expect(historico_tdc.errores?).to be_truthy
+            end
+            
+          end
+          
+        end
+        
+        
+        context 'cuando la respuesta no tiene la estructura esperada' do
+          before(:context) { WebMock.enable! }
+          let!(:cuerpo){ File.read("spec/fixtures/MX/Banxico/historico/respuestas_incorrectas/mal_formado.xml") } 
+          let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo) }
+          let!(:historico_tdc){ described_class.new }
+          let!(:arr){ historico_tdc.de_serie(:dolar_fix) }
+          
+          it 'es nil' do
+            expect(arr).to be_nil
+          end
+          
+          
+          describe '#errores' do
+            
+            it 'tiene el mensaje de error' do
+              expect(historico_tdc.errores).to eq "Error: La respuesta de la petición no tiene el formato correcto."
+            end
+            
+          end
+          
+          
+          describe '#errores?' do
+            
+            it 'es true' do
+              expect(historico_tdc.errores?).to be_truthy
+            end
+            
+          end
+          
+        end
+        
+      end
+      
+    end
+
+  end
+  
+  
+  describe '#completo' do
+    
+    context 'cuando la petición tuvo éxito' do
+      
+      context 'cuando no es una respuesta satisfactoria' do
+        before(:context) { WebMock.enable! }
+        
+        [404, 500].each do |codigo|
+          
+          context "cuando no se encontró la página (#{codigo})" do
+            let!(:req){ stub_request(:any, post_url).to_return(status: codigo) }
+            let(:historico_tdc){ described_class.new }
+            let!(:arr){ historico_tdc.completo }
+
+            it 'es nil' do
+              expect(arr).to be_nil
+            end
+          
+          
+            describe '#errores' do
+              
+              it 'es la descripción del error' do
+                expect(historico_tdc.errores).to eq "Error: código de error #{codigo}."
+              end
+              
+            end
+            
+            
+            describe '#errores?' do
+              
+              it 'es true' do
+                expect(historico_tdc.errores?).to be_truthy
+              end
+              
+            end
+            
+          end
+        
+        end
+        
+      end
+      
+      
+      context 'cuando se obtuvo una respuesta satisfactoria (200 - OK)' do
+        let!(:año){ 2015 }
+        
+        context 'cuando la respuesta tiene series' do
+          let!(:nombres_series){ MX::Banxico::Series.nombres(:tipos_de_cambio) }
+          let(:historico_tdc){ described_class.new }
+          
+          
+          context 'cuando se realiza una conexión al servicio' do
+            before(:context) { WebMock.disable! }
+            let!(:arr){ historico_tdc.completo(año, año) }
+          
+            it 'es un arreglo de MX::Banxico::TipoDeCambio' do
+              expect(arr).to be_a Array
+              nombres_series.each do |serie|
+                arr.select{|t| t.moneda == serie }.each do |tdc|
+                  expect(tdc).to be_a MX::Banxico::TipoDeCambio
+                end
+              end
+            end
+          
+            it 'el arreglo tiene un elemento por cada día el año' do
+              nombres_series.each do |serie|
+                expect(arr.select{|t| t.moneda == serie }.size).to eq dias_tipos_de_cambio_2015(serie)
+              end
+            end
+            
+            
+            describe '#errores' do
+        
+              it 'es la descripción del error' do
+                expect(historico_tdc.errores).to be_nil
+              end
+        
+            end
+      
+      
+            describe '#errores?' do
+        
+              it 'es true' do
+                expect(historico_tdc.errores?).to be_falsey
+              end
+        
+            end
+            
+          end
+          
+          
+          context 'cuando se usa un stub de la conexión' do
+            before(:context) { WebMock.enable! }
+            let!(:cuerpo_ok){ File.read("spec/fixtures/MX/Banxico/historico/respuestas_correctas/tipo_de_cambio.xml") }
+            let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo_ok) }
+            let!(:arr){ historico_tdc.completo(año, año) }
+          
+            it 'es un arreglo de MX::Banxico::TipoDeCambio' do
+              expect(arr).to be_a Array
+              nombres_series.each do |serie|
+                arr.select{|t| t.moneda == serie }.each do |tdc|
+                  expect(tdc).to be_a MX::Banxico::TipoDeCambio
+                end
+              end
+            end
+          
+            it 'el arreglo tiene un elemento por cada día el año' do
+              nombres_series.each do |serie|
+                expect(arr.select{|t| t.moneda == serie }.size).to eq dias_tipos_de_cambio_2015(serie)
+              end
+            end
+            
+            
+            describe '#errores' do
+        
+              it 'es la descripción del error' do
+                expect(historico_tdc.errores).to be_nil
+              end
+        
+            end
+      
+      
+            describe '#errores?' do
+        
+              it 'es true' do
+                expect(historico_tdc.errores?).to be_falsey
+              end
+        
+            end
+            
+          end
+          
+        end
+        
+        
+        context 'cuando la respuesta no tiene series' do
+          before(:context) { WebMock.enable! }
+          let!(:cuerpo_sin_series){ File.read("spec/fixtures/MX/Banxico/historico/respuestas_incorrectas/sin_series.xml") }
+          let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo_sin_series) }
+          let!(:historico_tdc){ described_class.new }
+          let!(:arr){ historico_tdc.completo(año, año) }
+
+          it 'es nil' do
+            expect(arr).to be_nil
+          end
+            
+            
+          describe '#errores' do
+            
+            it 'es la descripción del error' do
+              expect(historico_tdc.errores).to eq "Error: No se encontraron series en la respuesta."
+            end
+            
+          end
+          
+          
+          describe '#errores?' do
+            
+            it 'es true' do
+              expect(historico_tdc.errores?).to be_truthy
+            end
+            
+          end
+          
+        end
+        
+        
+        context 'cuando la respuesta tiene series sin tipos de cambio' do
+          before(:context) { WebMock.enable! }
+          let!(:cuerpo_sin_tdc){ File.read("spec/fixtures/MX/Banxico/historico/respuestas_incorrectas/serie_sin_valores.xml") } 
+          let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo_sin_tdc) }
+          let!(:historico_tdc){ described_class.new }
+          let!(:arr){ historico_tdc.completo(año, año) }
+          
+          it 'es nil' do
+            expect(arr).to be_nil
+          end
+            
+            
+          describe '#errores' do
+            
+            it 'es la descripción del error' do
+              expect(historico_tdc.errores).to eq "Error: No se encontraron series en la respuesta."
+            end
+            
+          end
+          
+          
+          describe '#errores?' do
+            
+            it 'es true' do
+              expect(historico_tdc.errores?).to be_truthy
+            end
+            
+          end
+          
+        end
+        
+        
+        context 'cuando la respuesta no tiene la estructura esperada' do
+          before(:context) { WebMock.enable! }
+          let!(:cuerpo){ File.read("spec/fixtures/MX/Banxico/historico/respuestas_incorrectas/mal_formado.xml") } 
+          let!(:req){ stub_request(:any, post_url).to_return(status: 200, body: cuerpo) }
+          let!(:historico_tdc){ described_class.new }
+          let!(:arr){ historico_tdc.completo }
+          
+          it 'es nil' do
+            expect(arr).to be_nil
+          end
+          
+          
+          describe '#errores' do
+            
+            it 'tiene el mensaje de error' do
+              expect(historico_tdc.errores).to eq "Error: La respuesta de la petición no tiene el formato correcto."
+            end
+            
+          end
+          
+          
+          describe '#errores?' do
+            
+            it 'es true' do
+              expect(historico_tdc.errores?).to be_truthy
+            end
+            
+          end
+          
+        end
+        
+      end
+      
+    end
+    
+  end
+  
+  
+  
+  # Cuenta manual :'(
+  def dias_tipos_de_cambio_2015(serie)
+    case serie
+    when :dolar_canadiense
+      241
+    when :dolar_liquidacion
+      365
+    else
+      251
+    end
+  end
+  
+  
+end