trevol 0.1.0

data/lib/trevol/transporte.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'securerandom'
+require_relative 'errors'
+
+module Trevol
+  # El transporte: lo que hace que las llamadas se comporten igual en los 7 SDK (docs/api/43 §2.6.2 a §2.6.5).
+  #
+  # Es un middleware de Faraday (el punto de extensión del código generado): pone las cabeceras y la Idempotency-Key, reintenta y convierte
+  # toda respuesta que no es 2xx en un error tipado que atraviesa el código generado sin envolverse (`ApiClient#call_api` solo atrapa
+  # `Faraday::TimeoutError` y `Faraday::ConnectionFailed`, y convierte en `ApiError` lo que le llega como respuesta).
+  class Transporte < Faraday::Middleware
+    ESTADOS_REINTENTABLES = [429, 500, 502, 503, 504].freeze
+    CODES_EN_CURSO = %w[request_in_progress previous_event_pending].freeze
+    PROBLEMA = 'application/problem+json'
+    ACCEPT = {
+      'pdf' => "application/pdf, #{PROBLEMA}", 'xml' => "application/xml, #{PROBLEMA}", 'zip' => "application/zip, #{PROBLEMA}"
+    }.tap { |h| h.default = "application/json, #{PROBLEMA}" }.freeze
+    CLAVE_VALIDA = /\A[!-~]{1,255}\z/
+
+    # Qué pasó en un intento: `tipo` :respuesta (con `estado`) o :red (sin respuesta). `retry_after` en segundos, ya resuelto.
+    Resultado = Struct.new(:tipo, :estado, :code, :retryable, :retry_after, keyword_init: true)
+    Decision = Struct.new(:reintentar, :espera, :motivo)
+
+    # Lo que necesita el middleware. La llave nunca sale en un inspect.
+    Opciones = Struct.new(:llave, :api_version, :user_agent, :max_reintentos, :max_retry_after, :ruta_base, :dormir, :azar, :uuid, :ahora, keyword_init: true) do
+      def inspect = "#<Trevol::Transporte::Opciones api_version=#{api_version.inspect} max_reintentos=#{max_reintentos.inspect}>"
+      alias_method :to_s, :inspect
+    end
+
+    class << self
+      # La espera propia antes del intento siguiente: 0,5 · 2^(intento−1), con tope de 8 s, por un factor al azar en [0,75; 1].
+      def espera_propia(intento, azar)
+        [0.5 * (2**(intento - 1)), 8.0].min * (0.75 + (0.25 * azar))
+      end
+
+      # Función PURA: ¿se reintenta y cuánto se espera? Las mismas reglas y los mismos casos (`pruebas/datos/transporte.json`) en los 7 SDK.
+      def decidir(intento:, reintento:, max_reintentos:, max_retry_after:, azar:, resultado:)
+        r = resultado
+        return Decision.new(false, nil, 'exito') if r.tipo == :respuesta && r.estado && r.estado >= 200 && r.estado < 300
+
+        reintentable =
+          if r.tipo == :red
+            reintento == 'seguro'
+          elsif reintento == 'solo_429'
+            r.estado == 429
+          elsif r.estado == 402
+            false
+          else
+            ESTADOS_REINTENTABLES.include?(r.estado) || CODES_EN_CURSO.include?(r.code) || r.retryable == true
+          end
+        return Decision.new(false, nil, nil) unless reintentable
+        return Decision.new(false, nil, 'agotado') if intento > max_reintentos
+
+        propia = espera_propia(intento, azar)
+        pedida = r.tipo == :respuesta && r.retry_after && r.retry_after.positive? ? r.retry_after : 0.0
+        return Decision.new(false, nil, 'retry_after_excede') if pedida > max_retry_after
+
+        Decision.new(true, [pedida, propia].max, nil)
+      end
+
+      def validar_clave(clave)
+        return if clave.is_a?(String) && CLAVE_VALIDA.match?(clave)
+
+        raise ConfigurationError, 'La idempotency_key debe tener de 1 a 255 caracteres ASCII visibles (sin espacios).'
+      end
+
+      # La operación (tablas) de un método y una ruta SIN el prefijo /v1. Las rutas fijas ganan a las plantillas
+      # (GET /radian_events/tacit_acceptance frente a GET /radian_events/{id}).
+      def operacion(metodo, ruta)
+        indices[:exactas]["#{metodo} #{ruta}"] ||
+          indices[:plantillas].find { |o, re| o[:metodo] == metodo && re.match?(ruta) }&.first
+      end
+
+      private
+
+      def indices
+        @indices ||= begin
+          exactas = {}
+          plantillas = []
+          TrevolGenerado::Tablas::OPERACIONES.each do |o|
+            if o[:ruta].include?('{')
+              plantillas << [o, Regexp.new("\\A#{Regexp.escape(o[:ruta]).gsub(/\\\{[a-z_]+\\\}/, '[^/]+')}\\z")]
+            else
+              exactas["#{o[:metodo]} #{o[:ruta]}"] = o
+            end
+          end
+          { exactas: exactas, plantillas: plantillas }
+        end
+      end
+    end
+
+    def initialize(app, opciones)
+      super(app)
+      @o = opciones
+    end
+
+    def call(env)
+      metodo = env.method.to_s.upcase
+      ruta = env.url.path
+      ruta = ruta.delete_prefix(@o.ruta_base) unless @o.ruta_base.to_s.empty?
+      op = self.class.operacion(metodo, ruta)
+      reintento = op ? op[:reintento] : (metodo == 'GET' ? 'seguro' : 'solo_429')
+
+      # La Idempotency-Key: una por llamada, la misma en todos los reintentos.
+      clave = nil
+      if op && op[:idempotente]
+        dada = env.request_headers['Idempotency-Key']
+        if dada.nil?
+          clave = @o.uuid.call
+        else
+          self.class.validar_clave(dada)
+          clave = dada
+        end
+        env.request_headers['Idempotency-Key'] = clave
+      else
+        env.request_headers.delete('Idempotency-Key')
+      end
+      h = env.request_headers
+      h['Authorization'] = "Bearer #{@o.llave}"
+      h['Trevol-Version'] = @o.api_version
+      h['User-Agent'] = @o.user_agent
+      h['Accept'] = ACCEPT[op && op[:binario]]
+
+      cuerpo_pedido = env.body
+      destino = env.request.on_data # descarga en flujo: se junta por intento y solo la 2xx llega a quien la pidió
+      intento = 0
+      loop do
+        intento += 1
+        env.body = cuerpo_pedido
+        trozos = []
+        env.request.on_data = proc { |trozo, *| trozos << trozo.dup } if destino
+        respuesta = nil
+        causa = nil
+        begin
+          respuesta = @app.call(env)
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+          causa = e
+        end
+
+        if respuesta
+          estado = respuesta.status
+          if estado >= 200 && estado < 300
+            if destino
+              total = 0
+              trozos.each { |t| total += t.bytesize; destino.call(t, total) }
+              env.request.on_data = destino
+            end
+            return respuesta
+          end
+          texto = respuesta.body.to_s
+          texto = trozos.join if texto.empty? && !trozos.empty?
+          error = Errores.de_respuesta(estado, texto.dup.force_encoding('UTF-8').scrub, respuesta.headers, clave, @o.ahora.call)
+          decision = self.class.decidir(
+            intento: intento, reintento: reintento, max_reintentos: @o.max_reintentos, max_retry_after: @o.max_retry_after, azar: @o.azar.call,
+            resultado: Resultado.new(tipo: :respuesta, estado: estado, code: error.code, retryable: error.retryable, retry_after: error.retry_after)
+          )
+          raise error unless decision.reintentar
+        else
+          decision = self.class.decidir(
+            intento: intento, reintento: reintento, max_reintentos: @o.max_reintentos, max_retry_after: @o.max_retry_after, azar: @o.azar.call,
+            resultado: Resultado.new(tipo: :red)
+          )
+          unless decision.reintentar
+            raise APIConnectionError.new("No pude conectar con la API de Trevol (#{causa.message.to_s[0, 200]}).", idempotency_key: clave), cause: causa
+          end
+        end
+        @o.dormir.call(decision.espera || 0.0)
+      end
+    end
+  end
+end

data/lib/trevol/webhook.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'standardwebhooks'
+require_relative 'errors'
+
+module Trevol
+  # Verificación de webhooks (docs/api/43 §2.6.9): Standard Webhooks sobre el CUERPO CRUDO (`request.raw_post`, `request.body.read`).
+  #
+  # La firma esperada la calcula la biblioteca abierta `standardwebhooks` (`StandardWebhooks::Webhook#sign`); la tolerancia de 5 minutos
+  # (con reloj inyectable en las pruebas), las cabeceras (en cualquier caja) y la comparación en tiempo constante son de este SDK: la
+  # biblioteca no deja inyectar el reloj, solo acepta cabeceras en minúsculas y entrega un Hash en vez del evento generado.
+  class Webhook
+    TOLERANCIA = 300 # segundos, hacia atrás y hacia adelante
+    NOMBRES = %w[webhook-id webhook-timestamp webhook-signature].freeze
+
+    # @param secret [String] el secreto del endpoint (`whsec_…`), que se muestra una sola vez al crearlo o rotarlo
+    # @param ahora [#call, nil] solo para pruebas: el reloj, en segundos
+    def initialize(secret, ahora: nil)
+      secret = secret.to_s.strip
+      raise ConfigurationError, 'Falta el secreto del webhook (whsec_…). Se muestra una sola vez al crear o rotar el endpoint.' if secret.empty? || secret == 'whsec_'
+
+      sin_prefijo = secret.delete_prefix('whsec_')
+      crudo = begin
+        Base64.strict_decode64(sin_prefijo)
+      rescue ArgumentError
+        nil
+      end
+      raise ConfigurationError, 'El secreto del webhook no tiene el formato esperado (whsec_ + base64).' if crudo.nil? || crudo.empty?
+
+      @firmador = StandardWebhooks::Webhook.new(secret)
+      @ahora = ahora || -> { Time.now.to_i }
+    end
+
+    # Las tres cabeceras en minúsculas, venga lo que venga (un Hash, `request.headers`, una lista de pares, valores en arreglo).
+    # La primera repetida gana.
+    def self.normalizar_cabeceras(cabeceras)
+      pares = cabeceras.respond_to?(:each_pair) ? cabeceras.each_pair.to_a : Array(cabeceras)
+      salida = {}
+      pares.each do |k, v|
+        nombre = k.to_s.downcase.tr('_', '-').sub(/\Ahttp-/, '')
+        v = v.first if v.is_a?(Array)
+        salida[nombre] ||= v.to_s if NOMBRES.include?(nombre) && !v.nil?
+      end
+      salida
+    end
+
+    # Verifica la firma y la fecha de una entrega y devuelve el evento (`TrevolGenerado::Event`).
+    # Lanza `Trevol::WebhookVerificationError` si algo no cuadra.
+    #
+    # Ojo: la verificación NO evita repeticiones dentro de los 5 minutos ni los reintentos de entrega: deduplica por `webhook-id`.
+    def verify(body, headers)
+      unless body.is_a?(String)
+        raise WebhookVerificationError.new(
+          'El cuerpo del webhook debe ser el CUERPO CRUDO (String), no un objeto ya parseado: la firma se calcula sobre los bytes exactos. ' \
+          'En Rails usa request.raw_post; en Sinatra, request.body.read.', :cuerpo
+        )
+      end
+      texto = body.dup.force_encoding('UTF-8')
+      raise WebhookVerificationError.new('El cuerpo del webhook no es UTF-8.', :cuerpo) unless texto.valid_encoding?
+
+      h = self.class.normalizar_cabeceras(headers)
+      NOMBRES.each do |n|
+        raise WebhookVerificationError.new("Falta la cabecera #{n}.", :cabeceras) if h[n].to_s.empty?
+      end
+      raise WebhookVerificationError.new('El webhook-timestamp no es un número de segundos.', :fecha) unless h['webhook-timestamp'].match?(/\A[0-9]{1,12}\z/)
+
+      marca = h['webhook-timestamp'].to_i
+      if (@ahora.call - marca).abs > TOLERANCIA
+        raise WebhookVerificationError.new('La fecha del webhook está fuera de la tolerancia de 5 minutos.', :fecha)
+      end
+
+      esperada = @firmador.sign(h['webhook-id'], marca.to_s, texto).split(',', 2)[1].to_s
+      coincide = false
+      h['webhook-signature'].split(' ').each do |firma|
+        version, valor = firma.split(',', 2)
+        coincide = true if version == 'v1' && valor && StandardWebhooks.secure_compare(esperada, valor) # basta una válida (rotación del secreto)
+      end
+      unless coincide
+        raise WebhookVerificationError.new('La firma del webhook no coincide: revisa el secreto y que el cuerpo sea el crudo, sin reescribir.', :firma)
+      end
+
+      begin
+        TrevolGenerado::Event.build_from_hash(JSON.parse(texto, symbolize_names: true))
+      rescue StandardError
+        raise WebhookVerificationError.new('El cuerpo firmado no es un evento válido.', :cuerpo)
+      end
+    end
+
+    # El `data` del evento como el modelo de su `type` (p. ej. `TrevolGenerado::DocumentEventData` para `invoice.accepted`). nil si el tipo
+    # es nuevo y este SDK todavía no lo conoce: el evento no se pierde, `evento.data` sigue ahí como Hash.
+    def event_data(evento)
+      nombre = TrevolGenerado::Tablas::EVENTO_MODELOS[evento.type.to_s]
+      return nil if nombre.nil? || evento.data.nil?
+
+      TrevolGenerado.const_get(nombre).build_from_hash(evento.data)
+    end
+  end
+end

data/lib/trevol.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# SDK de Ruby para la API de Trevol. Documentación: https://platform.trevol.si/docs
+require 'trevol_generado'
+require 'trevol_generado/tablas'
+require_relative 'trevol/errors'
+require_relative 'trevol/llave'
+require_relative 'trevol/paginacion'
+require_relative 'trevol/transporte'
+require_relative 'trevol/webhook'
+
+module Trevol
+  # La versión de este SDK y la de la API con que se generó (el valor de Trevol-Version por defecto).
+  VERSION = TrevolGenerado::Tablas::VERSION
+  API_VERSION = TrevolGenerado::Tablas::API_VERSION
+end
+
+require_relative 'trevol/client'

data/lib/trevol_generado/api/balance_api.rb

@@ -0,0 +1,220 @@
+=begin
+#API de Trevol
+
+#Trevol API. Documentación: https://platform.trevol.si/docs
+
+The version of the OpenAPI document: 2026-10-22
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.26.0
+
+=end
+
+require 'cgi'
+
+module TrevolGenerado
+  class BalanceApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Preparar una recarga del saldo (para el widget de Wompi)
+    # Prepara una recarga del saldo de la cuenta y devuelve lo que necesita el widget de Wompi (`WidgetCheckout`: `publicKey`, `currency`, `amountInCents`, `reference`, `signature: {integrity}` y `expirationTime`). El pago se hace en el widget; cuando Wompi lo aprueba, Trevol abona el saldo (y la factura de la recarga sale a nombre de `buyer`). Preparar no mueve saldo y la firma vence en una hora: si el widget venció, prepara otra. Solo llaves de escritura; exige `Idempotency-Key` (repetir con la misma clave devuelve la MISMA recarga). Sin `buyer`, la factura va a nombre de la empresa de la llave con sus datos (NIT, DV, razón social, correo, teléfono, dirección y municipio); si no alcanzan, 422 en `buyer.*`. El monto va entre la recarga mínima y la máxima (422 `top_up_below_minimum` / `top_up_above_maximum` con `minimum_cop` / `maximum_cop`). Es dinero real con cualquier llave (también `test`): el saldo es uno solo. Hasta 20 por llave cada 10 minutos (429).
+    # @param top_up_input [TopUpInput] 
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :idempotency_key Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).
+    # @return [TopUp]
+    def create_balance_top_up(top_up_input, opts = {})
+      data, _status_code, _headers = create_balance_top_up_with_http_info(top_up_input, opts)
+      data
+    end
+
+    # Preparar una recarga del saldo (para el widget de Wompi)
+    # Prepara una recarga del saldo de la cuenta y devuelve lo que necesita el widget de Wompi (`WidgetCheckout`: `publicKey`, `currency`, `amountInCents`, `reference`, `signature: {integrity}` y `expirationTime`). El pago se hace en el widget; cuando Wompi lo aprueba, Trevol abona el saldo (y la factura de la recarga sale a nombre de `buyer`). Preparar no mueve saldo y la firma vence en una hora: si el widget venció, prepara otra. Solo llaves de escritura; exige `Idempotency-Key` (repetir con la misma clave devuelve la MISMA recarga). Sin `buyer`, la factura va a nombre de la empresa de la llave con sus datos (NIT, DV, razón social, correo, teléfono, dirección y municipio); si no alcanzan, 422 en `buyer.*`. El monto va entre la recarga mínima y la máxima (422 `top_up_below_minimum` / `top_up_above_maximum` con `minimum_cop` / `maximum_cop`). Es dinero real con cualquier llave (también `test`): el saldo es uno solo. Hasta 20 por llave cada 10 minutos (429).
+    # @param top_up_input [TopUpInput] 
+    # @param [Hash] opts the optional parameters
+    # @option opts [String] :idempotency_key Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).
+    # @return [Array<(TopUp, Integer, Hash)>] TopUp data, response status code and response headers
+    def create_balance_top_up_with_http_info(top_up_input, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: BalanceApi.create_balance_top_up ...'
+      end
+      # verify the required parameter 'top_up_input' is set
+      if @api_client.config.client_side_validation && top_up_input.nil?
+        fail ArgumentError, "Missing the required parameter 'top_up_input' when calling BalanceApi.create_balance_top_up"
+      end
+      # resource path
+      local_var_path = '/balance/top_ups'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json', 'application/problem+json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+      header_params[:'Idempotency-Key'] = opts[:'idempotency_key'] if !opts[:'idempotency_key'].nil?
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(top_up_input)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'TopUp'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['llave']
+
+      new_options = opts.merge(
+        :operation => :"BalanceApi.create_balance_top_up",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: BalanceApi#create_balance_top_up\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Los movimientos del saldo de la cuenta
+    # Los movimientos del saldo de la cuenta (de todas sus empresas), del más nuevo al más viejo: lo mismo que «Saldo y recargas» en la app. Un documento es UNA fila (`type: document`) con su `status`: `pending` (apartado mientras la DIAN lo valida), `charged` (validado y cobrado) o `released` (la DIAN lo rechazó: no se cobró y `amount` es 0); `company` dice qué empresa lo emitió. Lo demás es una fila por movimiento: `top_up` (recarga, con su `reference`), `top_up_reversal`, `bonus`, `adjustment`, `license_fee`, `expiration` u `other`. `amount` es lo que el movimiento hizo con el disponible, con signo; `available_after`, el disponible justo después. Filtro `type`: `all` (por defecto), `documents`, `funding` (todo lo que no es un documento) o `top_ups`. Paginación por cursor: `limit` (1 a 100, 25 por defecto) y `starting_after` (el `id` de la última fila que tienes).
+    # @param [Hash] opts the optional parameters
+    # @option opts [Integer] :limit  (default to 25)
+    # @option opts [String] :starting_after 
+    # @option opts [String] :type  (default to 'all')
+    # @return [BalanceTransactionList]
+    def list_balance_transactions(opts = {})
+      data, _status_code, _headers = list_balance_transactions_with_http_info(opts)
+      data
+    end
+
+    # Los movimientos del saldo de la cuenta
+    # Los movimientos del saldo de la cuenta (de todas sus empresas), del más nuevo al más viejo: lo mismo que «Saldo y recargas» en la app. Un documento es UNA fila (&#x60;type: document&#x60;) con su &#x60;status&#x60;: &#x60;pending&#x60; (apartado mientras la DIAN lo valida), &#x60;charged&#x60; (validado y cobrado) o &#x60;released&#x60; (la DIAN lo rechazó: no se cobró y &#x60;amount&#x60; es 0); &#x60;company&#x60; dice qué empresa lo emitió. Lo demás es una fila por movimiento: &#x60;top_up&#x60; (recarga, con su &#x60;reference&#x60;), &#x60;top_up_reversal&#x60;, &#x60;bonus&#x60;, &#x60;adjustment&#x60;, &#x60;license_fee&#x60;, &#x60;expiration&#x60; u &#x60;other&#x60;. &#x60;amount&#x60; es lo que el movimiento hizo con el disponible, con signo; &#x60;available_after&#x60;, el disponible justo después. Filtro &#x60;type&#x60;: &#x60;all&#x60; (por defecto), &#x60;documents&#x60;, &#x60;funding&#x60; (todo lo que no es un documento) o &#x60;top_ups&#x60;. Paginación por cursor: &#x60;limit&#x60; (1 a 100, 25 por defecto) y &#x60;starting_after&#x60; (el &#x60;id&#x60; de la última fila que tienes).
+    # @param [Hash] opts the optional parameters
+    # @option opts [Integer] :limit  (default to 25)
+    # @option opts [String] :starting_after 
+    # @option opts [String] :type  (default to 'all')
+    # @return [Array<(BalanceTransactionList, Integer, Hash)>] BalanceTransactionList data, response status code and response headers
+    def list_balance_transactions_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: BalanceApi.list_balance_transactions ...'
+      end
+      allowable_values = ["all", "documents", "funding", "top_ups", "unknown_default_open_api"]
+      if @api_client.config.client_side_validation && opts[:'type'] && !allowable_values.include?(opts[:'type'])
+        fail ArgumentError, "invalid value for \"type\", must be one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/balance/transactions'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+      query_params[:'starting_after'] = opts[:'starting_after'] if !opts[:'starting_after'].nil?
+      query_params[:'type'] = opts[:'type'] if !opts[:'type'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json', 'application/problem+json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'BalanceTransactionList'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['llave']
+
+      new_options = opts.merge(
+        :operation => :"BalanceApi.list_balance_transactions",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: BalanceApi#list_balance_transactions\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # El saldo de la cuenta (lo comparten sus empresas)
+    # El saldo prepago de Trevol. Es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (`shared: true`) y cualquier llave de cualquiera de ellas, de lectura o de escritura, `test` o `live`, ve el mismo. Solo lo que se emite en producción (llaves `live`) lo consume; la habilitación (`test`) no cobra. `available` es lo que se puede gastar (en pesos); `held`, lo apartado por documentos que la DIAN todavía valida; `overdraft`, cuánto puede bajar `available` de cero al apartar un documento; `low_threshold`, el umbral del aviso de saldo bajo (el 20 % de la última recarga; `null` sin recargas). `level`: `empty` con `available` ≤ 0, `low` por debajo de `low_threshold`, si no `ok`. Con `available` por debajo del precio de un documento, emitir en producción responde 402 `insufficient_balance`. El evento `balance.low` avisa por webhook.
+    # @param [Hash] opts the optional parameters
+    # @return [Balance]
+    def retrieve_balance(opts = {})
+      data, _status_code, _headers = retrieve_balance_with_http_info(opts)
+      data
+    end
+
+    # El saldo de la cuenta (lo comparten sus empresas)
+    # El saldo prepago de Trevol. Es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (&#x60;shared: true&#x60;) y cualquier llave de cualquiera de ellas, de lectura o de escritura, &#x60;test&#x60; o &#x60;live&#x60;, ve el mismo. Solo lo que se emite en producción (llaves &#x60;live&#x60;) lo consume; la habilitación (&#x60;test&#x60;) no cobra. &#x60;available&#x60; es lo que se puede gastar (en pesos); &#x60;held&#x60;, lo apartado por documentos que la DIAN todavía valida; &#x60;overdraft&#x60;, cuánto puede bajar &#x60;available&#x60; de cero al apartar un documento; &#x60;low_threshold&#x60;, el umbral del aviso de saldo bajo (el 20 % de la última recarga; &#x60;null&#x60; sin recargas). &#x60;level&#x60;: &#x60;empty&#x60; con &#x60;available&#x60; ≤ 0, &#x60;low&#x60; por debajo de &#x60;low_threshold&#x60;, si no &#x60;ok&#x60;. Con &#x60;available&#x60; por debajo del precio de un documento, emitir en producción responde 402 &#x60;insufficient_balance&#x60;. El evento &#x60;balance.low&#x60; avisa por webhook.
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(Balance, Integer, Hash)>] Balance data, response status code and response headers
+    def retrieve_balance_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: BalanceApi.retrieve_balance ...'
+      end
+      # resource path
+      local_var_path = '/balance'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json', 'application/problem+json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'Balance'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['llave']
+
+      new_options = opts.merge(
+        :operation => :"BalanceApi.retrieve_balance",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: BalanceApi#retrieve_balance\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end