trevol 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca3520036480d9eb0112a8740a7b691619b86d3a024553c5d512fa95616c2364
+  data.tar.gz: cad373fe775779a5c8775e5a7fe91d076ee9d04d16061cf6d1d56bd2593c9fb7
+SHA512:
+  metadata.gz: 4c9107774f828c1d308589153110b2a7497bfb75b0b59b1d44abcfa4317319787d9ac9e5d4710ef557bdacd0a11e1e71086392edc4c0e5ca13763f42eecca937
+  data.tar.gz: 9df656532ba941372add5fada3acf0b47b5eadd621010d7e91be1b63ca88f2605348cbbdf0714d787b9502dc38f9ba96e7e38e34ac0abf92b29b77deb8fe2f73

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Registro de cambios
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el versionado, [SemVer](https://semver.org/lang/es/): antes
+de la 1.0, un cambio incompatible sube el número menor.
+
+## [0.1.0] — sin publicar
+
+Primera versión (API `2026-10-22`).
+
+- `Trevol::Client` con un recurso por etiqueta de la API (`invoices`, `credit_notes`, `debit_notes`, `support_documents`, `payrolls`,
+  `radian_events`, `webhook_endpoints`, `events`, `requests`, `balance`, `general`…) y los modelos generados de la especificación
+  (`TrevolGenerado::*`).
+- `Idempotency-Key` automática (la misma en los reintentos), reintentos con espera creciente que respetan `Retry-After`, errores tipados por
+  `code` (`Trevol::*Error`), entorno deducido del prefijo de la llave, `Trevol-Version` fijada.
+- `paginate` (`Enumerator::Lazy`), descargas de PDF, XML y ZIP como `Tempfile`, `Trevol::Webhook#verify` y `#event_data` (Standard Webhooks).

data/GENERADO.md

@@ -0,0 +1,14 @@
+# Código generado
+
+**No edites `lib/trevol_generado/`**: `sdks/generar.sh` la borra y la vuelve a escribir entera. La capa propia (cliente,
+reintentos, errores, paginación, webhooks) vive fuera de esa carpeta.
+
+| | |
+|---|---|
+| Generador | OpenAPI Generator 7.26.0 (`ruby`) |
+| Especificación | `especificacion/openapi.sdk.enums-abiertos.json` (variante 3.0.3 de `docs/api/openapi.json`, versión de la API 2026-10-22) |
+| sha256 de la especificación | `ca431c24f76cc576b9f989aa4c9df300f5df85fdce051a0704558fae65374bd1` |
+| Configuración | `openapi-generator.yaml` |
+
+Regenerar (desde el monorepo de Trevol): `sdks/generar.sh ruby`. Comprobar que lo del repositorio es lo que sale de la
+especificación: `sdks/generar.sh --comprobar ruby`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Montclair (Trevol)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,173 @@
+# trevol (Ruby)
+
+SDK de Ruby para la **API de Trevol**: facturación electrónica, documento soporte, documento equivalente, nómina electrónica y eventos
+RADIAN ante la DIAN (Colombia). Documentación: <https://platform.trevol.si/docs>.
+
+> **In English.** Ruby SDK for the Trevol API (Colombian e-invoicing, DIAN). Ruby ≥ 3.3, Faraday 2. Typed models and API clients generated from
+> the OpenAPI spec (OpenAPI Generator, module `TrevolGenerado`), plus a thin hand-written layer (module `Trevol`): automatic `Idempotency-Key`
+> (the same one on retries), retries with exponential backoff honouring `Retry-After`, typed errors by problem+json `code`, environment inferred
+> from the key prefix (`tvl_test_` = DIAN test environment, `tvl_live_` = production), pinned `Trevol-Version`, Standard Webhooks signature
+> verification, cursor pagination with `Enumerator::Lazy` and PDF/XML/ZIP downloads. Docs are in Spanish like the API.
+
+**Versión 0.1.0** — API `2026-10-22`. Licencia MIT.
+
+## Instalación
+
+```sh
+gem install trevol          # o, en tu Gemfile: gem 'trevol'
+```
+
+Necesita Ruby 3.3 o más nuevo. Depende de [Faraday](https://lostisland.github.io/faraday/) 2 y de la gema abierta
+[`standardwebhooks`](https://rubygems.org/gems/standardwebhooks) (MIT).
+
+## Uso
+
+La llave de la API se crea en la consola de desarrolladores (<https://platform.trevol.si/llaves>) y se guarda en el entorno de tu **servidor**:
+`TREVOL_API_KEY`. Una llave `tvl_test_…` llama a la habilitación de la DIAN; una `tvl_live_…`, a producción. El SDK deduce el entorno del
+prefijo (`trevol.environment`).
+
+```ruby
+require 'trevol'
+
+trevol = Trevol::Client.new # lee TREVOL_API_KEY; tvl_test_… → trevol.environment == :test
+
+begin
+  factura = trevol.invoices.create_invoice(
+    {
+      external_id: 'VENTA-2026-000123',
+      customer: { final_consumer: true },
+      items: [{ description: 'Café especial 500 g', quantity: '1', unit_price: '32000', taxes: [{ code: '01', rate: '19' }] }],
+      payment: { form: 'cash', methods: [{ code: '10' }] }
+    },
+    idempotency_key: 'VENTA-2026-000123' # opcional: si falta, el SDK pone una y la repite en los reintentos
+  )
+  if factura.status == 'processing'
+    # 202: la DIAN no contestó; Trevol lo termina y avisa por webhook. NO crees otro documento para la misma venta.
+  end
+rescue Trevol::ValidationError => e
+  e.errors.each { |x| warn "#{x[:pointer]} #{x[:message]}" }
+rescue Trevol::Error => e
+  warn "#{e.code} #{e.request_id}"
+end
+
+# Todas las páginas de un listado, perezosamente (Enumerator::Lazy)
+trevol.paginate { |cursor| trevol.invoices.list_invoices(limit: 100, starting_after: cursor) }.each do |f|
+  puts "#{f.id} #{f.status}"
+end
+
+# Los archivos llegan como Tempfile (ciérralo con close! cuando termines)
+pdf = trevol.invoices.download_invoice_pdf('inv_…')
+```
+
+Los nombres de los métodos son los del `operationId` de la [especificación](https://platform.trevol.si/docs/api) en `snake_case`
+(`create_invoice`, `list_invoices`, `retrieve_invoice`, `correct_invoice`, `send_invoice`, `download_invoice_pdf`…). Los parámetros de ruta y
+los de consulta obligatorios son posicionales; los opcionales (`limit:`, `starting_after:`, `idempotency_key:`) van con nombre. El cuerpo es un
+`Hash` con las claves **iguales a las de la API** (`external_id`) o el modelo generado (`TrevolGenerado::InvoiceInput.new(...)`); los importes y
+las fechas viajan como texto (`'32000.50'`, `'2026-10-31'`).
+
+## Lo que conviene saber
+
+### Idempotencia: manda `external_id` y tu propia clave
+
+El SDK genera una `Idempotency-Key` por llamada y **la repite en todos los reintentos de esa llamada**. Pero si tu proceso muere y vuelves a
+llamar, saldrá otra clave y, si no mandaste `external_id` (es opcional), podría duplicarse el documento. Por eso:
+
+- manda siempre `external_id` (tu id de la venta), y
+- pasa una `idempotency_key:` derivada de tu venta (`idempotency_key: 'VENTA-2026-000123'`).
+
+Ante un `Trevol::ConflictError` con `code == 'external_id_in_use'`, el documento ya existe: usa `e.problem[:existing_id]`. Todo error lleva la
+`idempotency_key` que se usó para reintentar más tarde con la misma. Un `APIConnectionError` también.
+
+### Respuestas 202 (`processing`, `sending`, `validating`, `contingency`)
+
+No son errores ni se reintentan: se devuelven como el modelo de la respuesta. **No crees otro documento**: espera el webhook o consulta con
+`retrieve_invoice`; repetir la misma llamada con la misma `Idempotency-Key` continúa el mismo documento. El PDF y el ZIP llegan después del
+`201` (evento `invoice.delivered`, o `delivery.status == 'completed'`).
+
+### Reintentos
+
+Hasta 2 reintentos (3 intentos) con espera creciente (0,5 s, 1 s, 2 s… con tope de 8 s y un poco de azar) ante un error de red, 429, 500,
+502, 503, 504, un 409 `request_in_progress` o `previous_event_pending`, y todo problema que diga `retryable: true` (salvo el 402). Respeta
+`Retry-After`; si pide más de `max_retry_after` (60 s) no espera y lanza el error con `retry_after`. Las operaciones sin `Idempotency-Key`
+(crear un endpoint, `…/send`, `DELETE`) solo se reintentan con 429. Los 202 y los errores finales (400, 401, 402, 403, 404, 422 y los 409
+`invalid_state`, `external_id_in_use`, `duplicate_document`) **nunca** se reintentan. El SDK no usa `faraday-retry`: es el único que reintenta.
+
+### La versión de la API
+
+El SDK fija `Trevol-Version: 2026-10-22` en cada petición. **Ojo:** una llave creada con la versión `2026-10-21` que empiece a usar este SDK
+pasa a `2026-10-22` (el encabezado manda): recibe `202 processing` donde antes recibía `503`. Si todavía no quieres ese cambio:
+`Trevol::Client.new(llave, api_version: '2026-10-21')`. Más en <https://platform.trevol.si/docs/versiones>.
+
+### Errores tipados
+
+`Trevol::Error` es la base; las clases salen del `code` del problem+json: `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
+`InvalidRequestError`, `IdempotencyError`, `ValidationError` (con `errors`: `field`, `pointer`, `message`), `ConflictError`,
+`PreconditionError`, `DianRejectedError` (con `problem[:document]` y `problem[:rules]`), `BalanceError`, `RateLimitError`,
+`DianUnavailableError` e `InternalServerError`. Un `code` que el SDK todavía no conoce llega como `Trevol::Error` con ese `code`: nunca rompe.
+Además: `APIConnectionError` (no hubo respuesta), `ConfigurationError` (mal uso, antes de llamar) y `WebhookVerificationError` (`reason`: `:firma`,
+`:fecha`, `:cabeceras` o `:cuerpo`). Cada error tiene `status`, `code`, `type`, `title`, `detail`, `request_id`, `retryable?`, `retry_after`,
+`errors`, `idempotency_key`, `problem` (el cuerpo completo, con claves símbolo) y `headers` (los de la respuesta). Ninguno incluye tu llave.
+
+### Webhooks
+
+```ruby
+# Rails
+class WebhooksController < ActionController::API
+  WH = Trevol::Webhook.new(ENV.fetch('TREVOL_WEBHOOK_SECRET')) # whsec_…
+
+  def trevol
+    evento = WH.verify(request.raw_post, request.headers) # el cuerpo CRUDO, no params
+    # Deduplica por evento.id (también llega en la cabecera webhook-id): la verificación no evita repeticiones.
+    datos = WH.event_data(evento) # el modelo según evento.type (p. ej. TrevolGenerado::DocumentEventData)
+    head :ok
+  rescue Trevol::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+En Sinatra usa `request.body.read`. La firma se calcula sobre los **bytes exactos**: no uses el cuerpo ya decodificado. `verify` acepta las
+cabeceras como `Hash` (cualquier caja, también el formato `HTTP_WEBHOOK_ID` de Rack) o `request.headers`; la firma esperada la calcula la gema
+de Standard Webhooks, y el SDK tolera 5 minutos hacia atrás y hacia adelante en `webhook-timestamp` y compara en tiempo constante.
+
+### Estado y cabeceras de la respuesta
+
+Cada método tiene una variante `…_with_http_info` que devuelve `[modelo, estado, cabeceras]`:
+`factura, estado, cabeceras = trevol.invoices.create_invoice_with_http_info(...)` (`cabeceras['request-id']`, `cabeceras['idempotent-replayed']`).
+
+### Cabeceras propias por llamada
+
+Cada método acepta `header_params: { 'X-Mi-Cabecera' => '…' }` (se mezcla con las del SDK) en su último argumento.
+
+## Opciones
+
+```ruby
+Trevol::Client.new(
+  llave,
+  api_version: '2026-10-22',   # Trevol-Version en cada petición
+  max_retries: 2,              # 0 los apaga
+  timeout: 65,                 # segundos por intento
+  max_retry_after: 60,         # segundos
+  base_url: 'https://api.trevol.si/v1',
+  environment: :test,          # si la llave no coincide: ConfigurationError antes de llamar
+  proxy: nil                   # p. ej. 'http://proxy.miempresa.co:3128'
+)
+```
+
+## Cómo está hecho
+
+- `lib/trevol_generado/` lo escribe [OpenAPI Generator](https://openapi-generator.tech) 7.26.0 (`ruby`, Faraday) desde la especificación
+  pública y **no se edita** (ver `GENERADO.md`). Para que un valor nuevo de un `enum` en lo que la API devuelve no rompa a quien ya integró,
+  los modelos de respuesta se generan sin `enum`.
+- Lo propio (`lib/trevol/`) vive fuera y solo usa el punto de extensión del código generado: un middleware de Faraday (`Trevol::Transporte`),
+  que lanza el error tipado y reintenta. La gema también declara `base64` y `cgi` porque `standardwebhooks` 1.1.0 y el código generado los
+  usan sin que Ruby 3.4/4.0 los traiga ya en la biblioteca estándar.
+- Las pruebas: `bundle install && bundle exec rake test` (unitarias sin red, contra un servidor HTTP local, con los mismos casos de los demás SDK
+  en `pruebas/datos/`); `TREVOL_PRISM_URL=http://127.0.0.1:4010 bundle exec rake prism` contra un servidor simulado
+  (`npx @stoplight/prism-cli mock pruebas/datos/openapi.json -p 4010`) que valida cada petición contra la especificación, y que además corre
+  como programa cada fragmento de código de la documentación.
+- `bundle exec ruby pruebas/humo/humo.rb` es la prueba de humo **real** (solo con una llave `tvl_test_`; no emite documentos).
+
+## Licencia
+
+MIT © 2026 Joshua Montclair (Trevol).

data/lib/trevol/client.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'securerandom'
+require 'rbconfig'
+require_relative 'errors'
+require_relative 'llave'
+require_relative 'paginacion'
+require_relative 'transporte'
+
+module Trevol
+  URL_BASE = 'https://api.trevol.si/v1'
+
+  # El cliente de la API de Trevol: un recurso por etiqueta (`invoices`, `credit_notes`, …), cada uno con los métodos generados de la
+  # especificación (`create_invoice`, `list_invoices`, `retrieve_invoice`…). Documentación: https://platform.trevol.si/docs
+  #
+  #   trevol = Trevol::Client.new # lee TREVOL_API_KEY; tvl_test_… → trevol.environment == :test
+  class Client
+    RECURSOS = {
+      balance: TrevolGenerado::BalanceApi, credit_notes: TrevolGenerado::CreditNotesApi, debit_notes: TrevolGenerado::DebitNotesApi,
+      equivalent_document_adjustments: TrevolGenerado::EquivalentDocumentAdjustmentsApi, equivalent_documents: TrevolGenerado::EquivalentDocumentsApi,
+      events: TrevolGenerado::EventsApi, general: TrevolGenerado::GeneralApi, invoices: TrevolGenerado::InvoicesApi,
+      payroll_adjustments: TrevolGenerado::PayrollAdjustmentsApi, payrolls: TrevolGenerado::PayrollsApi,
+      radian_events: TrevolGenerado::RadianEventsApi, requests: TrevolGenerado::RequestsApi,
+      support_document_adjustments: TrevolGenerado::SupportDocumentAdjustmentsApi, support_documents: TrevolGenerado::SupportDocumentsApi,
+      webhook_endpoints: TrevolGenerado::WebhookEndpointsApi
+    }.freeze
+
+    RECURSOS.each_key { |nombre| attr_reader nombre }
+
+    # @return [Symbol] :test (llave tvl_test_, habilitación de la DIAN) o :live (tvl_live_, producción)
+    attr_reader :environment
+    # @return [String] el valor de `Trevol-Version` que se manda en cada petición
+    attr_reader :api_version
+
+    # @param api_key [String, nil] `tvl_test_…` o `tvl_live_…`; si falta se lee `TREVOL_API_KEY`
+    # @param api_version [String, nil] el valor de `Trevol-Version` en cada petición (por defecto `Trevol::API_VERSION`)
+    # @param max_retries [Integer] reintentos tras el primer intento (3 intentos en total por defecto). 0 los apaga
+    # @param timeout [Numeric] segundos por intento (65 por defecto, como el playground)
+    # @param max_retry_after [Numeric] si `Retry-After` pide esperar más segundos que esto, no se espera: se lanza el error con `retry_after`
+    # @param base_url [String] por defecto https://api.trevol.si/v1 (para un servidor simulado en las pruebas)
+    # @param environment [Symbol, String, nil] :test o :live: si la llave no coincide, `ConfigurationError` ANTES de llamar
+    # @param proxy [String, nil] URL de un proxy (se pasa a Faraday)
+    # @param internos [Hash, nil] solo para pruebas: `dormir`, `azar`, `uuid` y `ahora`
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(api_key = nil, api_version: nil, max_retries: 2, timeout: 65, max_retry_after: 60, base_url: URL_BASE, environment: nil,
+                   proxy: nil, internos: nil)
+      llave = api_key.nil? ? ENV.fetch('TREVOL_API_KEY', nil) : api_key
+      if llave.nil? || llave.to_s.strip.empty?
+        raise ConfigurationError, 'Falta la llave de la API: pásala a Trevol::Client.new(...) o define la variable de entorno TREVOL_API_KEY.'
+      end
+
+      @environment = Llave.entorno(llave)
+      if environment && environment.to_sym != @environment
+        raise ConfigurationError, "Pediste el entorno «#{environment}» pero la llave es de «#{@environment}» " \
+                                  "(#{@environment == :test ? 'tvl_test_ = habilitación' : 'tvl_live_ = producción'})."
+      end
+      raise ConfigurationError, 'max_retries no puede ser negativo.' if max_retries.negative?
+
+      @api_version = api_version || API_VERSION
+      i = internos || {}
+      base_url = base_url.chomp('/')
+      opciones = Transporte::Opciones.new(
+        llave: llave.to_s.strip, api_version: @api_version, user_agent: "trevol-ruby/#{VERSION} (ruby #{RUBY_VERSION}; +https://platform.trevol.si/docs)",
+        max_reintentos: max_retries, max_retry_after: max_retry_after.to_f, ruta_base: URI.parse(base_url).path.chomp('/'),
+        dormir: i[:dormir] || ->(s) { sleep(s) }, azar: i[:azar] || -> { rand }, uuid: i[:uuid] || -> { SecureRandom.uuid }, ahora: i[:ahora] || -> { Time.now }
+      )
+      config = TrevolGenerado::Configuration.new
+      uri = URI.parse(base_url)
+      config.scheme = uri.scheme
+      config.host = uri.port && ![80, 443].include?(uri.port) ? "#{uri.host}:#{uri.port}" : uri.host
+      config.base_path = uri.path
+      config.timeout = timeout
+      config.logger = Logger.new(nil) # el generado escribe «Temp file written…» en cada descarga; la persona decide qué hacer con el archivo
+      config.proxy = proxy if proxy
+      config.use(Transporte, opciones)
+      config.configure_faraday_connection { |conexion| i[:conexion].call(conexion) } if i[:conexion]
+      @api_client = TrevolGenerado::ApiClient.new(config)
+      RECURSOS.each { |nombre, clase| instance_variable_set(:"@#{nombre}", clase.new(@api_client)) }
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Recorre todas las páginas de un listado, perezosamente (`Enumerator::Lazy`):
+    #
+    #   trevol.paginate { |cursor| trevol.invoices.list_invoices(limit: 100, starting_after: cursor) }.each { |f| puts f.id }
+    def paginate(&)
+      Paginacion.paginar(&)
+    end
+
+    # La llave no se guarda en el objeto; un inspect nunca debe enseñar nada sensible.
+    def inspect = "#<Trevol::Client environment=#{environment.inspect} api_version=#{api_version.inspect}>"
+    alias_method :to_s, :inspect
+  end
+end

data/lib/trevol/errors.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Trevol
+  # La base de todos los errores del SDK (docs/api/43 §2.6.5): un `rescue Trevol::Error` ya lo atrapa todo.
+  #
+  # Toda respuesta que no es 2xx llega como una subclase, según el `code` del problem+json (el mismo vocabulario que
+  # https://platform.trevol.si/docs/errores). Ninguna lleva la llave ni las cabeceras de la PETICIÓN.
+  class Error < StandardError
+    # @return [Integer, nil] el estado HTTP (nil si no hubo respuesta)
+    attr_reader :status
+    # @return [String, nil] el `code` del problem+json
+    attr_reader :code
+    attr_reader :type, :title, :detail, :request_id, :retryable, :retry_after, :idempotency_key, :problem, :headers
+    # @return [Array<Hash>] las `errors[]` de un 422: `{field:, pointer:, message:}`
+    attr_reader :errors
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(message = nil, status: nil, code: nil, type: nil, title: nil, detail: nil, request_id: nil, retryable: nil,
+                   retry_after: nil, errors: [], idempotency_key: nil, problem: nil, headers: {})
+      super(message)
+      @status = status
+      @code = code
+      @type = type
+      @title = title
+      @detail = detail
+      @request_id = request_id
+      @retryable = retryable
+      @retry_after = retry_after # segundos
+      @errors = errors
+      # La Idempotency-Key de la llamada: úsala para reintentar más tarde con la MISMA clave.
+      @idempotency_key = idempotency_key
+      # El cuerpo problem+json completo, con los campos extra (existing_id, reason, document, rules…), con claves símbolo.
+      @problem = problem
+      # Las cabeceras de la RESPUESTA.
+      @headers = headers
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def retryable? = retryable == true
+
+    # Clase, code, estado, detalle y request_id; nunca la llave ni cabeceras de la petición.
+    def to_s
+      partes = [self.class.name.to_s.split('::').last]
+      partes << code if code
+      partes << "HTTP #{status}" if status
+      cola = request_id ? " [request_id=#{request_id}]" : ''
+      "#{partes.join(' ')}: #{detail || title || super}#{cola}"
+    end
+
+    def inspect = "#<#{self.class} code=#{code.inspect} status=#{status.inspect} request_id=#{request_id.inspect}>"
+  end
+
+  class AuthenticationError < Error; end
+  class PermissionDeniedError < Error; end
+  class NotFoundError < Error; end
+  class InvalidRequestError < Error; end
+  class IdempotencyError < Error; end
+  # 422 `validation_error`: `errors` dice qué campo (`pointer`) y por qué.
+  class ValidationError < Error; end
+  class ConflictError < Error; end
+  class PreconditionError < Error; end
+  # 422 `dian_rejected`: `problem[:document]` trae el documento y `problem[:rules]` las reglas que la DIAN aplicó.
+  class DianRejectedError < Error; end
+  class BalanceError < Error; end
+  class RateLimitError < Error; end
+  class DianUnavailableError < Error; end
+  class InternalServerError < Error; end
+  # No hubo respuesta: red, DNS, TLS o tiempo agotado. Lleva la `idempotency_key` para reintentar sin duplicar.
+  class APIConnectionError < Error; end
+  # Mal uso del SDK, antes de llamar: llave mal formada, entorno que no coincide. Nunca incluye la llave.
+  class ConfigurationError < Error; end
+
+  # La firma, la fecha o las cabeceras de un webhook no son válidas. `reason`: :firma, :fecha, :cabeceras o :cuerpo.
+  class WebhookVerificationError < Error
+    attr_reader :reason
+
+    def initialize(message, reason)
+      super(message)
+      @reason = reason
+    end
+  end
+
+  # Convierte una respuesta que no es 2xx en su error tipado. @api private
+  module Errores
+    RECORTE = 2048
+
+    CLASES = {
+      'AuthenticationError' => AuthenticationError, 'PermissionDeniedError' => PermissionDeniedError, 'NotFoundError' => NotFoundError,
+      'InvalidRequestError' => InvalidRequestError, 'IdempotencyError' => IdempotencyError, 'ValidationError' => ValidationError,
+      'ConflictError' => ConflictError, 'PreconditionError' => PreconditionError, 'DianRejectedError' => DianRejectedError,
+      'BalanceError' => BalanceError, 'RateLimitError' => RateLimitError, 'DianUnavailableError' => DianUnavailableError,
+      'InternalServerError' => InternalServerError
+    }.freeze
+
+    module_function
+
+    def numero(valor)
+      return nil if valor == true || valor == false || valor.nil?
+
+      n = valor.is_a?(String) ? Float(valor.strip, exception: false) : valor
+      n.is_a?(Numeric) && n.finite? && n >= 0 ? n.to_f : nil
+    end
+
+    # El valor de `Retry-After`: segundos o una fecha HTTP. nil si no está o no se entiende.
+    def leer_retry_after(valor, ahora = Time.now)
+      return nil if valor.nil? || valor.to_s.strip.empty?
+
+      n = numero(valor)
+      return n if n
+
+      fecha = Time.httpdate(valor.to_s.strip)
+      [(fecha - ahora).ceil, 0].max.to_f
+    rescue ArgumentError
+      nil
+    end
+
+    # El cuerpo se lee como un mapa TOLERANTE (nunca con el modelo generado: un `code` nuevo o un campo que falta no puede romper el
+    # manejo de errores).
+    def de_respuesta(estado, texto, cabeceras, idempotency_key, ahora = Time.now)
+      cab = cabeceras.to_h.transform_keys { |k| k.to_s.downcase }
+      cuerpo = begin
+        j = JSON.parse(texto.to_s, symbolize_names: true)
+        j.is_a?(Hash) ? j : nil
+      rescue JSON::ParserError
+        nil
+      end
+      cadena = ->(clave) { cuerpo && cuerpo[clave].is_a?(String) ? cuerpo[clave] : nil }
+      code = cadena.call(:code)
+      detail = cadena.call(:detail)
+      title = cadena.call(:title)
+      errores = cuerpo && cuerpo[:errors].is_a?(Array) ? cuerpo[:errors].grep(Hash).map { |x| { field: nil, pointer: nil, message: nil }.merge(x) } : []
+      retryable = cuerpo && [true, false].include?(cuerpo[:retryable]) ? cuerpo[:retryable] : nil
+      retry_after = leer_retry_after(cab['retry-after'], ahora) || numero(cuerpo && cuerpo[:retry_after])
+      mensaje = detail || title || (cuerpo ? "La API respondió #{estado}" : "La API respondió #{estado} sin problem+json")
+      nombre = if code
+                 TrevolGenerado::Tablas::CLASE_POR_CODE[code] # un code que el SDK no conoce (la API sumó uno) da la base, nunca rompe
+               else
+                 TrevolGenerado::Tablas::CLASE_POR_ESTADO[estado.to_s] || (estado >= 500 ? TrevolGenerado::Tablas::CLASE_POR_ESTADO['5xx'] : nil)
+               end
+      clase = CLASES.fetch(nombre, Error)
+      clase.new(
+        mensaje, status: estado, code: code, type: cadena.call(:type), title: title,
+                 detail: cuerpo ? detail : (texto.to_s.strip[0, RECORTE].then { |t| t.empty? ? nil : t }),
+                 request_id: cadena.call(:request_id) || cab['request-id'], retryable: retryable, retry_after: retry_after,
+                 errors: errores, idempotency_key: idempotency_key, problem: cuerpo, headers: cabeceras.to_h
+      )
+    end
+  end
+end

data/lib/trevol/llave.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Trevol
+  # La llave de la API: su formato y el entorno que se deduce de su prefijo (docs/api/43 §2.6.1).
+  module Llave
+    FORMATO = /\Atvl_(test|live)_[0-9a-f]{64}\z/
+
+    module_function
+
+    # Valida la llave y devuelve su entorno: `:test` (habilitación de la DIAN) o `:live` (producción). El mensaje NUNCA incluye la llave.
+    def entorno(llave)
+      m = llave.is_a?(String) ? FORMATO.match(llave.strip) : nil
+      raise ConfigurationError, 'La llave de la API no tiene el formato esperado (tvl_test_… o tvl_live_… con 64 caracteres hexadecimales). ' \
+                                'Créala en https://platform.trevol.si/llaves y pásala completa o define TREVOL_API_KEY.' unless m
+
+      m[1].to_sym
+    end
+  end
+end

data/lib/trevol/paginacion.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Trevol
+  # Paginación con iteradores (docs/api/43 §2.6.7): la API pagina por cursor (`starting_after`).
+  module Paginacion
+    module_function
+
+    # Recorre todas las páginas de un listado, perezosamente (devuelve un `Enumerator::Lazy`).
+    #
+    # El bloque recibe el cursor (`starting_after`; nil la primera vez), pide UNA página y devuelve el sobre de lista generado
+    # (`data`, `has_more`, `next_cursor`). Sigue con `next_cursor` mientras `has_more`; si la página no lo trae, usa el `id` del último
+    # elemento (así lo arma la API). Se detiene si el cursor no avanza.
+    def paginar(&pagina)
+      raise ArgumentError, 'paginate necesita un bloque { |cursor| ... }' unless pagina
+
+      Enumerator.new do |y|
+        cursor = nil
+        loop do
+          p = pagina.call(cursor)
+          datos = Array(tomar(p, :data))
+          datos.each { |d| y << d }
+          break if tomar(p, :has_more) != true || datos.empty?
+
+          siguiente = tomar(p, :next_cursor)
+          siguiente = tomar(datos.last, :id) if siguiente.nil? || siguiente.to_s.empty?
+          break if siguiente.nil? || siguiente.to_s.empty? || siguiente == cursor
+
+          cursor = siguiente
+        end
+      end.lazy
+    end
+
+    def tomar(objeto, clave)
+      if objeto.respond_to?(clave)
+        objeto.public_send(clave)
+      elsif objeto.is_a?(Hash)
+        objeto[clave] || objeto[clave.to_s]
+      end
+    end
+  end
+end