dni_peru 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7847ab9a63151aa066c6e6132fb8c153607a992011a09029718bb7de1f4aca2e
+  data.tar.gz: b68a9e93403b81cb5add28774122308fcbeb046de481378a5fd6793139fa1034
+SHA512:
+  metadata.gz: ab9be7bab4c723630871fc454df03c13ba5e17b8c2ba9233b1ec6ce6b6628fc3c4e7a6a150f4b334deb20cd3d44cacb41d0419f6875e7f088e670ea999131dca
+  data.tar.gz: 0ec1fefcc683bcd0af7a048d2c4203e9e5b3464b78ebd97c2739520233cd8870c1320bd458740bb37904493113246f88d278e8a02f3071ca8dc5d871a8d23e0c

data/.env.example

@@ -0,0 +1,7 @@
+# Decolecta API Configuration
+# Get your API key from: https://decolecta.com/profile/
+DECOLECTA_API_KEY=your_decolecta_api_key_here
+
+# ApiPeruDev API Configuration (optional alternative provider)
+# Get your API key from: https://apiperu.dev/
+API_PERU_DEV_KEY=your_apiperu_dev_key_here

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,42 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Exclude:
+    - 'examples/**/*'
+
+Metrics/AbcSize:
+  Exclude:
+    - 'examples/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Layout/LineLength:
+  Max: 120
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-28
+
+### Added
+- Initial release
+- Support for multiple API providers
+- Built-in providers: Decolecta (decolecta.com) and ApiPeruDev (apiperu.dev)
+- Decolecta as default provider (official RENIEC data source)
+- Configuration system with API key management
+- Comprehensive error handling
+- Response normalization across providers
+- DNI validation (8-digit format)
+- Configurable timeouts and automatic retries
+- Full documentation and usage examples
+- RSpec test suite with WebMock
+- Rails integration guide
+
+### Security
+- HTTPS-only connections
+- Bearer token authentication
+- API key validation
+- Backend-only access (CORS disabled)

data/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in dni_peru.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "simplecov", "~> 0.21"
+gem "vcr", "~> 6.0"
+gem "webmock", "~> 3.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ruben Paz
+
+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,322 @@
+# DniPeru
+
+A Ruby gem that provides a unified interface to query DNI (Documento Nacional de Identidad) information from multiple Peruvian API providers.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dni_peru'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install dni_peru
+
+## Getting Started
+
+### 1. Get Your API Key
+
+To use this gem, you need to register and get an API key from Decolecta:
+
+1. Visit https://decolecta.com/profile/
+2. Sign up for a free account
+3. Generate your API token
+4. Copy the token for configuration
+
+### 2. Store Your API Key Securely
+
+**For Rails applications**, add to your credentials:
+
+```bash
+EDITOR="code --wait" rails credentials:edit
+```
+
+Add:
+```yaml
+decolecta:
+  api_key: your_api_key_here
+```
+
+**For other applications**, use environment variables:
+
+```bash
+export DECOLECTA_API_KEY="your_api_key_here"
+```
+
+Or use a `.env` file with the `dotenv` gem.
+
+## Configuration
+
+Configure the gem with your preferred settings and API keys:
+
+```ruby
+DniPeru.configure do |config|
+  # Set the default provider (optional, defaults to :decolecta)
+  config.default_provider = :decolecta
+  
+  # Set timeout in seconds (optional, defaults to 30)
+  config.timeout = 30
+  
+  # Set API keys for different providers
+  config.set_api_key(:decolecta, ENV['DECOLECTA_API_KEY'])
+  config.set_api_key(:api_peru_dev, ENV['API_PERU_DEV_KEY'])
+end
+```
+
+### Quick Start
+
+```ruby
+require 'dni_peru'
+
+# Configure with your API key
+DniPeru.configure do |config|
+  config.set_api_key(:decolecta, 'your-api-key')
+end
+
+# Query a DNI
+response = DniPeru.query('12345678')
+
+if response.success?
+  puts "Nombre: #{response.nombre_completo}"
+  # => "Nombre: DOE SMITH, JOHN"
+end
+```
+
+## Usage
+
+### Basic Usage
+
+Query a DNI using the default provider:
+
+```ruby
+response = DniPeru.query('12345678')
+
+if response.success?
+  puts response.nombre_completo
+  # => "DOE SMITH, JOHN"
+  
+  puts response.nombres
+  # => "JOHN"
+  
+  puts response.apellido_paterno
+  # => "DOE"
+  
+  puts response.apellido_materno
+  # => "SMITH"
+  
+  puts response.dni
+  # => "12345678"
+end
+```
+
+### Using a Specific Provider
+
+You can specify which provider to use for a query:
+
+```ruby
+# Using decolecta.com (recommended)
+response = DniPeru.query('12345678', provider: :decolecta)
+
+# Using apiperu.dev
+response = DniPeru.query('12345678', provider: :api_peru_dev)
+```
+
+### Using the Client Directly
+
+For more control, you can create a client instance:
+
+```ruby
+client = DniPeru::Client.new(provider: :decolecta)
+response = client.query('12345678')
+
+puts response.to_h
+# => {
+#   dni: "12345678",
+#   nombres: "JOHN",
+#   apellido_paterno: "DOE",
+#   apellido_materno: "SMITH",
+#   nombre_completo: "DOE SMITH, JOHN",
+#   provider: "Decolecta"
+# }
+```
+
+### Error Handling
+
+The gem raises specific errors for different scenarios:
+
+```ruby
+begin
+  response = DniPeru.query('12345678')
+rescue DniPeru::InvalidDniError => e
+  puts "Invalid DNI format: #{e.message}"
+rescue DniPeru::NotFoundError => e
+  puts "DNI not found: #{e.message}"
+rescue DniPeru::UnauthorizedError => e
+  puts "Invalid API key: #{e.message}"
+rescue DniPeru::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue DniPeru::ConnectionError => e
+  puts "Connection failed: #{e.message}"
+rescue DniPeru::ApiError => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Supported Providers
+
+### Decolecta (Recommended)
+
+Provider identifier: `:decolecta`
+
+- Website: https://decolecta.com/
+- Documentation: https://decolecta.gitbook.io/docs
+- Registration: https://decolecta.com/profile/
+- **Requires API key** (register for free)
+- Data source: RENIEC (official government registry)
+- Security: HTTPS only, Bearer token authentication
+- Features: DNI, RUC, Exchange rates
+- Status monitor: https://status.apis.net.pe/
+- Configuration: `config.set_api_key(:decolecta, 'your-api-key')`
+
+**API Endpoint:**
+```bash
+curl -H 'Accept: application/json' -H "Authorization: Bearer YOUR_TOKEN" \
+  'https://api.decolecta.com/v1/reniec/dni?numero=12345678'
+```
+
+### apiperu.dev
+
+Provider identifier: `:api_peru_dev`
+
+- Website: https://apiperu.dev/
+- Requires API key
+- Free tier: 100 queries/month
+- Data source: SUNAT reduced registry and public sources
+- Configuration: `config.set_api_key(:api_peru_dev, 'your-key')`
+
+## Rails Integration
+
+### Initializer
+
+Create an initializer file `config/initializers/dni_peru.rb`:
+
+```ruby
+DniPeru.configure do |config|
+  config.default_provider = :decolecta
+  config.timeout = 30
+  config.set_api_key(:decolecta, Rails.application.credentials.dig(:decolecta, :api_key))
+  config.set_api_key(:api_peru_dev, Rails.application.credentials.dig(:api_peru_dev, :api_key))
+end
+```
+
+### Usage in Models
+
+```ruby
+class User < ApplicationRecord
+  validates :dni, presence: true, length: { is: 8 }
+  
+  def fetch_dni_info
+    begin
+      response = DniPeru.query(self.dni)
+      update(
+        first_name: response.nombres,
+        paternal_surname: response.apellido_paterno,
+        maternal_surname: response.apellido_materno
+      )
+    rescue DniPeru::Error => e
+      errors.add(:dni, "Could not verify DNI: #{e.message}")
+      false
+    end
+  end
+end
+```
+
+### Usage in Controllers
+
+```ruby
+class UsersController < ApplicationController
+  def verify_dni
+    @response = DniPeru.query(params[:dni])
+    render json: @response.to_h
+  rescue DniPeru::Error => e
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+end
+```
+
+## Response Object
+
+The `Response` object provides the following attributes:
+
+- `dni` - The DNI number
+- `nombres` - First/given names
+- `apellido_paterno` - Paternal surname
+- `apellido_materno` - Maternal surname
+- `nombre_completo` - Full name in format "PATERNAL MATERNAL, NAMES"
+- `provider` - The provider used for the query
+- `raw_data` - Raw data from the API response
+
+Methods:
+- `success?` - Returns true if the query was successful
+- `to_h` - Returns a hash representation of the response
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Testing Your Configuration
+
+Test your API configuration quickly:
+
+```bash
+export DECOLECTA_API_KEY='your-api-key'
+ruby examples/test_config.rb 12345678
+```
+
+### Examples
+
+The `examples/` directory contains practical examples:
+
+- `examples/basic_usage.rb` - Basic gem usage examples
+- `examples/rails_integration.rb` - Rails integration patterns (services, controllers, models, jobs)
+- `examples/test_config.rb` - Configuration testing script
+
+## Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run with coverage:
+
+```bash
+COVERAGE=true bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubenpazch/dni-peru.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DniPeru project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rubenpazch/dni-peru/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/TEST_COVERAGE.md

@@ -0,0 +1,122 @@
+# Test Coverage Report
+
+## Test Suite Structure
+
+```
+spec/
+├── client_spec.rb              # Client initialization and query logic
+├── configuration_spec.rb       # Configuration and API key management
+├── dni_peru_spec.rb           # Main module interface
+├── errors_spec.rb             # Error classes and hierarchy
+├── response_spec.rb           # Response parsing and formatting
+└── providers/
+    ├── base_spec.rb           # Base provider functionality
+    ├── decolecta_spec.rb      # Decolecta provider integration
+    └── api_peru_dev_spec.rb   # ApiPeruDev provider integration
+```
+
+## Coverage Areas
+
+### ✅ Core Functionality
+- [x] **DniPeru Module** - Main interface and delegation
+- [x] **Configuration** - Default settings, API key storage
+- [x] **Client** - Provider selection, DNI validation, error wrapping
+- [x] **Response** - Data parsing, normalization, full name generation
+- [x] **Errors** - All error types and hierarchy
+
+### ✅ Providers
+- [x] **Base Provider** - Connection setup, response parsing, error handling
+- [x] **Decolecta** - API integration, authentication, data normalization
+- [x] **ApiPeruDev** - API integration, nested data handling
+
+### ✅ Test Scenarios
+
+#### Configuration Tests
+- Default provider and timeout settings
+- API key storage and retrieval
+- Multiple provider support
+- Key overwriting
+
+#### Client Tests  
+- Provider initialization
+- DNI format validation (empty, short, invalid characters)
+- Integer to string conversion
+- Provider delegation
+- Faraday error wrapping
+- Default configuration fallback
+
+#### Provider Tests
+- API authentication (with/without keys)
+- Successful responses (200)
+- Error responses (401, 404, 429, 500)
+- Data normalization
+- Connection configuration
+- Response building
+
+#### Response Tests
+- Symbol and string key parsing
+- Different key formats (camelCase, snake_case)
+- Full name generation
+- Success validation
+- Hash conversion
+- Raw data preservation
+
+#### Error Tests
+- Error inheritance hierarchy
+- Custom error messages
+- Error catching patterns
+- API vs non-API error distinction
+
+## Running Tests
+
+### Run all tests
+```bash
+bundle exec rspec
+```
+
+### Run with coverage
+```bash
+COVERAGE=true bundle exec rspec
+```
+
+### Run specific test file
+```bash
+bundle exec rspec spec/client_spec.rb
+```
+
+### Run specific test
+```bash
+bundle exec rspec spec/client_spec.rb:15
+```
+
+### Run with documentation format
+```bash
+bundle exec rspec --format documentation
+```
+
+## Expected Coverage
+
+With the comprehensive test suite, we should achieve:
+
+- **Overall Coverage**: ~95-100%
+- **Core Classes**: 100%
+- **Providers**: ~95% (some edge cases may be hard to simulate)
+- **Error Handling**: 100%
+
+## Key Test Dependencies
+
+- **RSpec** - Testing framework
+- **WebMock** - HTTP request stubbing
+- **SimpleCov** - Coverage reporting
+
+## Coverage Report Location
+
+After running tests with `COVERAGE=true`, view the report at:
+```
+coverage/index.html
+```
+
+Open in browser:
+```bash
+open coverage/index.html
+```

data/dni_peru.gemspec

@@ -0,0 +1,34 @@
+require_relative "lib/dni_peru/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dni_peru"
+  spec.version       = DniPeru::VERSION
+  spec.authors       = ["Ruben Paz"]
+  spec.email         = ["rubenpazch@gmail.com"]
+
+  spec.summary       = "Ruby gem to query DNI information from Peruvian API providers"
+  spec.description   = "A flexible Ruby gem that provides a unified interface to query DNI " \
+                       "(Documento Nacional de Identidad) information from multiple Peruvian API providers."
+  spec.homepage      = "https://github.com/rubenpazch/dni-peru"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/rubenpazch/dni-peru"
+  spec.metadata["changelog_uri"] = "https://github.com/rubenpazch/dni-peru/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+end

data/examples/basic_usage.rb

@@ -0,0 +1,103 @@
+# Example usage of dni_peru gem
+
+require "bundler/setup"
+require "dni_peru"
+
+# Configure the gem with your Decolecta API key
+# Get your API key from: https://decolecta.com/profile/
+DniPeru.configure do |config|
+  config.default_provider = :decolecta
+  config.timeout = 30
+
+  # Option 1: Use environment variable (recommended)
+  config.set_api_key(:decolecta, ENV.fetch("DECOLECTA_API_KEY", nil))
+
+  # Option 2: Hard-code (not recommended for production)
+  # config.set_api_key(:decolecta, "your-api-key-here")
+end
+
+# Example 1: Simple query
+puts "Example 1: Simple DNI Query"
+puts "-" * 50
+
+begin
+  response = DniPeru.query("12345678")
+
+  if response.success?
+    puts "DNI encontrado!"
+    puts "DNI: #{response.dni}"
+    puts "Nombres: #{response.nombres}"
+    puts "Apellido Paterno: #{response.apellido_paterno}"
+    puts "Apellido Materno: #{response.apellido_materno}"
+    puts "Nombre Completo: #{response.nombre_completo}"
+    puts "Proveedor: #{response.provider}"
+  else
+    puts "No se encontró información"
+  end
+rescue DniPeru::InvalidDniError => e
+  puts "Error: DNI inválido - #{e.message}"
+rescue DniPeru::UnauthorizedError => e
+  puts "Error: API key inválida - #{e.message}"
+rescue DniPeru::NotFoundError => e
+  puts "Error: DNI no encontrado - #{e.message}"
+rescue DniPeru::Error => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n"
+
+# Example 2: Using specific provider
+puts "Example 2: Using Specific Provider"
+puts "-" * 50
+
+begin
+  client = DniPeru::Client.new(provider: :decolecta)
+  response = client.query("87654321")
+
+  puts response.to_h.inspect
+rescue DniPeru::Error => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n"
+
+# Example 3: Validate DNI before querying
+puts "Example 3: DNI Validation"
+puts "-" * 50
+
+invalid_dnis = ["", "123", "1234567a", "123456789"]
+
+invalid_dnis.each do |dni|
+  DniPeru.query(dni)
+rescue DniPeru::InvalidDniError => e
+  puts "DNI '#{dni}': #{e.message}"
+end
+
+puts "\n"
+
+# Example 4: Error handling
+puts "Example 4: Comprehensive Error Handling"
+puts "-" * 50
+
+def query_dni_safely(dni)
+  response = DniPeru.query(dni)
+  {
+    success: true,
+    data: response.to_h
+  }
+rescue DniPeru::InvalidDniError => e
+  { success: false, error: "Formato inválido", message: e.message }
+rescue DniPeru::NotFoundError => e
+  { success: false, error: "No encontrado", message: e.message }
+rescue DniPeru::UnauthorizedError => e
+  { success: false, error: "No autorizado", message: e.message }
+rescue DniPeru::RateLimitError => e
+  { success: false, error: "Límite excedido", message: e.message }
+rescue DniPeru::ConnectionError => e
+  { success: false, error: "Error de conexión", message: e.message }
+rescue DniPeru::ApiError => e
+  { success: false, error: "Error de API", message: e.message }
+end
+
+result = query_dni_safely("12345678")
+puts result.inspect

data/examples/rails_integration.rb

@@ -0,0 +1,133 @@
+# Rails Example: DNI Verification Service
+# Place this in app/services/dni_verification_service.rb
+
+class DniVerificationService
+  def initialize(dni)
+    @dni = dni
+  end
+
+  def call
+    response = DniPeru.query(@dni)
+
+    if response.success?
+      {
+        success: true,
+        data: {
+          dni: response.dni,
+          nombres: response.nombres,
+          apellido_paterno: response.apellido_paterno,
+          apellido_materno: response.apellido_materno,
+          nombre_completo: response.nombre_completo
+        }
+      }
+    else
+      { success: false, error: "DNI no encontrado" }
+    end
+  rescue DniPeru::InvalidDniError => e
+    { success: false, error: "Formato de DNI inválido: #{e.message}" }
+  rescue DniPeru::NotFoundError
+    { success: false, error: "DNI no encontrado en RENIEC" }
+  rescue DniPeru::UnauthorizedError => e
+    Rails.logger.error "DniPeru API key error: #{e.message}"
+    { success: false, error: "Error de configuración del servicio" }
+  rescue DniPeru::RateLimitError => e
+    Rails.logger.warn "DniPeru rate limit exceeded: #{e.message}"
+    { success: false, error: "Servicio temporalmente no disponible. Intente más tarde." }
+  rescue DniPeru::ConnectionError => e
+    Rails.logger.error "DniPeru connection error: #{e.message}"
+    { success: false, error: "Error de conexión con el servicio" }
+  rescue DniPeru::ApiError => e
+    Rails.logger.error "DniPeru API error: #{e.message}"
+    { success: false, error: "Error en el servicio de verificación" }
+  end
+end
+
+# Usage in controller:
+# app/controllers/api/v1/dni_controller.rb
+
+module Api
+  module V1
+    class DniController < ApplicationController
+      def verify
+        result = DniVerificationService.new(params[:dni]).call
+
+        if result[:success]
+          render json: result[:data], status: :ok
+        else
+          render json: { error: result[:error] }, status: :unprocessable_entity
+        end
+      end
+    end
+  end
+end
+
+# Usage in model:
+# app/models/user.rb
+
+class User < ApplicationRecord
+  validates :dni, presence: true, length: { is: 8 }
+
+  # Callback to auto-fill names from DNI
+  before_validation :fetch_dni_info, if: :will_save_change_to_dni?
+
+  def verify_dni
+    result = DniVerificationService.new(dni).call
+
+    if result[:success]
+      data = result[:data]
+      update(
+        nombres: data[:nombres],
+        apellido_paterno: data[:apellido_paterno],
+        apellido_materno: data[:apellido_materno],
+        nombre_completo: data[:nombre_completo],
+        dni_verified: true,
+        dni_verified_at: Time.current
+      )
+    else
+      errors.add(:dni, result[:error])
+      false
+    end
+  end
+
+  private
+
+  def fetch_dni_info
+    return unless dni.present? && dni.length == 8
+
+    result = DniVerificationService.new(dni).call
+
+    if result[:success]
+      data = result[:data]
+      self.nombres = data[:nombres]
+      self.apellido_paterno = data[:apellido_paterno]
+      self.apellido_materno = data[:apellido_materno]
+      self.nombre_completo = data[:nombre_completo]
+    end
+  rescue StandardError => e
+    Rails.logger.error "Failed to fetch DNI info: #{e.message}"
+    # Don't block user creation if DNI service fails
+  end
+end
+
+# Usage in background job:
+# app/jobs/verify_dni_job.rb
+
+class VerifyDniJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id)
+    user = User.find(user_id)
+    result = DniVerificationService.new(user.dni).call
+
+    if result[:success]
+      user.update(
+        dni_verified: true,
+        dni_verified_at: Time.current,
+        **result[:data]
+      )
+    else
+      user.update(dni_verified: false)
+      Rails.logger.warn "DNI verification failed for user #{user.id}: #{result[:error]}"
+    end
+  end
+end

data/examples/test_config.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# Test your Decolecta API configuration
+# Usage: ruby examples/test_config.rb
+
+require "bundler/setup"
+require "dni_peru"
+
+puts "=" * 60
+puts "DNI Peru Gem - Configuration Test"
+puts "=" * 60
+puts ""
+
+# Check if API key is set
+api_key = ENV.fetch("DECOLECTA_API_KEY", nil)
+
+if api_key.nil? || api_key.empty?
+  puts "❌ ERROR: DECOLECTA_API_KEY environment variable not set"
+  puts ""
+  puts "To fix this:"
+  puts "  1. Get your API key from: https://decolecta.com/profile/"
+  puts "  2. Set it as environment variable:"
+  puts "     export DECOLECTA_API_KEY='your-api-key-here'"
+  puts ""
+  exit 1
+end
+
+puts "✓ API key found in environment"
+puts ""
+
+# Configure the gem
+DniPeru.configure do |config|
+  config.set_api_key(:decolecta, api_key)
+  config.timeout = 30
+end
+
+puts "✓ Gem configured successfully"
+puts ""
+
+# Test with a sample DNI (you can change this)
+test_dni = ARGV[0] || "12345678"
+
+puts "Testing with DNI: #{test_dni}"
+puts "-" * 60
+
+begin
+  response = DniPeru.query(test_dni)
+
+  if response.success?
+    puts "✓ API connection successful!"
+    puts ""
+    puts "Response details:"
+    puts "  DNI: #{response.dni}"
+    puts "  Nombres: #{response.nombres}"
+    puts "  Apellido Paterno: #{response.apellido_paterno}"
+    puts "  Apellido Materno: #{response.apellido_materno}"
+    puts "  Nombre Completo: #{response.nombre_completo}"
+    puts "  Provider: #{response.provider}"
+    puts ""
+    puts "✓ Everything is working correctly!"
+  else
+    puts "⚠ API responded but no data found"
+  end
+rescue DniPeru::UnauthorizedError => e
+  puts "❌ Authentication Error"
+  puts "   #{e.message}"
+  puts ""
+  puts "Please check:"
+  puts "  1. Your API key is correct"
+  puts "  2. Your API key is active at https://decolecta.com/profile/"
+rescue DniPeru::NotFoundError
+  puts "⚠ DNI not found in database"
+  puts "   This is normal if the DNI doesn't exist"
+  puts "   Try with a different DNI number"
+rescue DniPeru::InvalidDniError => e
+  puts "❌ Invalid DNI format"
+  puts "   #{e.message}"
+  puts "   DNI must be exactly 8 digits"
+rescue DniPeru::RateLimitError => e
+  puts "⚠ Rate limit exceeded"
+  puts "   #{e.message}"
+  puts "   Please wait a moment before trying again"
+rescue DniPeru::ConnectionError => e
+  puts "❌ Connection Error"
+  puts "   #{e.message}"
+  puts ""
+  puts "Please check:"
+  puts "  1. Your internet connection"
+  puts "  2. Decolecta service status"
+rescue DniPeru::ApiError => e
+  puts "❌ API Error"
+  puts "   #{e.message}"
+rescue StandardError => e
+  puts "❌ Unexpected Error"
+  puts "   #{e.class}: #{e.message}"
+  puts ""
+  puts "   Please report this issue at:"
+  puts "   https://github.com/rubenpazch/dni-peru/issues"
+end
+
+puts ""
+puts "=" * 60
+puts "Test complete"
+puts "=" * 60

data/lib/dni_peru/client.rb

@@ -0,0 +1,46 @@
+require "faraday"
+require "faraday/retry"
+
+module DniPeru
+  class Client
+    attr_reader :provider
+
+    PROVIDERS = {
+      decolecta: Providers::Decolecta,
+      api_peru_dev: Providers::ApiPeruDev
+    }.freeze
+
+    def initialize(provider: nil)
+      @provider_name = provider || config.default_provider
+      @provider = load_provider(@provider_name)
+    end
+
+    def query(dni)
+      dni_string = validate_dni!(dni)
+      provider.query(dni_string)
+    rescue Faraday::Error => e
+      raise ConnectionError, "Failed to connect to provider: #{e.message}"
+    end
+
+    private
+
+    def load_provider(provider_name)
+      provider_class = PROVIDERS[provider_name.to_sym]
+      raise InvalidProviderError, "Unknown provider: #{provider_name}" unless provider_class
+
+      provider_class.new(config)
+    end
+
+    def validate_dni!(dni)
+      dni_string = dni.to_s
+      raise InvalidDniError, "DNI cannot be empty" if dni_string.empty?
+      raise InvalidDniError, "DNI must be 8 digits" unless dni_string.match?(/^\d{8}$/)
+
+      dni_string
+    end
+
+    def config
+      DniPeru.configuration || Configuration.new
+    end
+  end
+end

data/lib/dni_peru/configuration.rb

@@ -0,0 +1,19 @@
+module DniPeru
+  class Configuration
+    attr_accessor :default_provider, :timeout, :api_keys
+
+    def initialize
+      @default_provider = :decolecta
+      @timeout = 30
+      @api_keys = {}
+    end
+
+    def set_api_key(provider, key)
+      @api_keys[provider.to_sym] = key
+    end
+
+    def get_api_key(provider)
+      @api_keys[provider.to_sym]
+    end
+  end
+end

data/lib/dni_peru/errors.rb

@@ -0,0 +1,10 @@
+module DniPeru
+  class Error < StandardError; end
+  class InvalidDniError < Error; end
+  class InvalidProviderError < Error; end
+  class ConnectionError < Error; end
+  class ApiError < Error; end
+  class NotFoundError < ApiError; end
+  class UnauthorizedError < ApiError; end
+  class RateLimitError < ApiError; end
+end

data/lib/dni_peru/providers/api_peru_dev.rb

@@ -0,0 +1,33 @@
+module DniPeru
+  module Providers
+    class ApiPeruDev < Base
+      BASE_URL = "https://apiperu.dev/api/dni".freeze
+
+      def query(dni)
+        api_key = config.get_api_key(:api_peru_dev)
+
+        response = connection.get("#{BASE_URL}/#{dni}") do |req|
+          req.headers["Authorization"] = "Bearer #{api_key}" if api_key
+          req.headers["Content-Type"] = "application/json"
+        end
+
+        data = parse_response(response)
+        build_response(normalize_data(data))
+      end
+
+      private
+
+      def normalize_data(data)
+        # Extract from nested structure if present
+        person_data = data[:data] || data
+
+        {
+          dni: person_data[:numero] || person_data[:dni],
+          nombres: person_data[:nombres],
+          apellido_paterno: person_data[:apellido_paterno],
+          apellido_materno: person_data[:apellido_materno]
+        }
+      end
+    end
+  end
+end

data/lib/dni_peru/providers/apis_net_pe.rb

@@ -0,0 +1,32 @@
+module DniPeru
+  module Providers
+    class Decolecta < Base
+      BASE_URL = "https://api.decolecta.com/v1/reniec/dni".freeze
+
+      def query(dni)
+        api_key = config.get_api_key(:decolecta)
+        raise UnauthorizedError, "API key is required for Decolecta provider" unless api_key
+
+        response = connection.get(BASE_URL) do |req|
+          req.params["numero"] = dni
+          req.headers["Authorization"] = "Bearer #{api_key}"
+          req.headers["Accept"] = "application/json"
+        end
+
+        data = parse_response(response)
+        build_response(normalize_data(data))
+      end
+
+      private
+
+      def normalize_data(data)
+        {
+          dni: data[:numeroDocumento] || data[:numero_documento],
+          nombres: data[:nombres],
+          apellido_paterno: data[:apellidoPaterno] || data[:apellido_paterno],
+          apellido_materno: data[:apellidoMaterno] || data[:apellido_materno]
+        }
+      end
+    end
+  end
+end

data/lib/dni_peru/providers/base.rb

@@ -0,0 +1,52 @@
+require "faraday"
+require "json"
+
+module DniPeru
+  module Providers
+    class Base
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def query(dni)
+        raise NotImplementedError, "Subclasses must implement the query method"
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new do |f|
+          f.request :retry, max: 2, interval: 0.5, backoff_factor: 2
+          f.adapter Faraday.default_adapter
+          f.options.timeout = config.timeout
+          f.options.open_timeout = 10
+        end
+      end
+
+      def parse_response(response)
+        return JSON.parse(response.body, symbolize_names: true) if response.status == 200
+
+        handle_error_response(response)
+      end
+
+      def handle_error_response(response)
+        case response.status
+        when 404
+          raise NotFoundError, "DNI not found"
+        when 401
+          raise UnauthorizedError, "Invalid API key or unauthorized access"
+        when 429
+          raise RateLimitError, "Rate limit exceeded"
+        else
+          raise ApiError, "API returned status #{response.status}: #{response.body}"
+        end
+      end
+
+      def build_response(data)
+        Response.new(data, provider: self.class.name.split("::").last)
+      end
+    end
+  end
+end

data/lib/dni_peru/providers/decolecta.rb

@@ -0,0 +1,32 @@
+module DniPeru
+  module Providers
+    class Decolecta < Base
+      BASE_URL = "https://api.decolecta.com/v1/reniec/dni".freeze
+
+      def query(dni)
+        api_key = config.get_api_key(:decolecta)
+        raise UnauthorizedError, "API key is required for Decolecta provider" unless api_key
+
+        response = connection.get(BASE_URL) do |req|
+          req.params["numero"] = dni
+          req.headers["Authorization"] = "Bearer #{api_key}"
+          req.headers["Accept"] = "application/json"
+        end
+
+        data = parse_response(response)
+        build_response(normalize_data(data))
+      end
+
+      private
+
+      def normalize_data(data)
+        {
+          dni: data[:numeroDocumento] || data[:numero_documento],
+          nombres: data[:nombres],
+          apellido_paterno: data[:apellidoPaterno] || data[:apellido_paterno],
+          apellido_materno: data[:apellidoMaterno] || data[:apellido_materno]
+        }
+      end
+    end
+  end
+end

data/lib/dni_peru/response.rb

@@ -0,0 +1,51 @@
+module DniPeru
+  class Response
+    attr_reader :dni, :nombres, :apellido_paterno, :apellido_materno,
+                :nombre_completo, :raw_data, :provider
+
+    def initialize(data, provider:)
+      @provider = provider
+      @raw_data = data
+      parse_data(data)
+    end
+
+    def success?
+      !@dni.nil?
+    end
+
+    def to_h
+      {
+        dni: @dni,
+        nombres: @nombres,
+        apellido_paterno: @apellido_paterno,
+        apellido_materno: @apellido_materno,
+        nombre_completo: @nombre_completo,
+        provider: @provider
+      }
+    end
+
+    private
+
+    def parse_data(data)
+      @dni = extract_field(data, :dni, "dni")
+      @nombres = extract_field(data, :nombres, "nombres")
+      @apellido_paterno = extract_field(data, :apellido_paterno, "apellidoPaterno", "apellido_paterno")
+      @apellido_materno = extract_field(data, :apellido_materno, "apellidoMaterno", "apellido_materno")
+      @nombre_completo = extract_field(data, :nombre_completo, "nombreCompleto") || build_full_name
+    end
+
+    def extract_field(data, *keys)
+      keys.each do |key|
+        value = data[key]
+        return value if value
+      end
+      nil
+    end
+
+    def build_full_name
+      return nil unless @nombres && @apellido_paterno && @apellido_materno
+
+      "#{@apellido_paterno} #{@apellido_materno}, #{@nombres}"
+    end
+  end
+end

data/lib/dni_peru/version.rb

@@ -0,0 +1,3 @@
+module DniPeru
+  VERSION = "0.1.0".freeze
+end

data/lib/dni_peru.rb

@@ -0,0 +1,24 @@
+require_relative "dni_peru/version"
+require_relative "dni_peru/configuration"
+require_relative "dni_peru/errors"
+require_relative "dni_peru/response"
+require_relative "dni_peru/providers/base"
+require_relative "dni_peru/providers/decolecta"
+require_relative "dni_peru/providers/api_peru_dev"
+require_relative "dni_peru/client"
+
+module DniPeru
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  def self.query(dni, provider: nil)
+    client = Client.new(provider: provider)
+    client.query(dni)
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: dni_peru
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ruben Paz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A flexible Ruby gem that provides a unified interface to query DNI (Documento
+  Nacional de Identidad) information from multiple Peruvian API providers.
+email:
+- rubenpazch@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- TEST_COVERAGE.md
+- dni_peru.gemspec
+- examples/basic_usage.rb
+- examples/rails_integration.rb
+- examples/test_config.rb
+- lib/dni_peru.rb
+- lib/dni_peru/client.rb
+- lib/dni_peru/configuration.rb
+- lib/dni_peru/errors.rb
+- lib/dni_peru/providers/api_peru_dev.rb
+- lib/dni_peru/providers/apis_net_pe.rb
+- lib/dni_peru/providers/base.rb
+- lib/dni_peru/providers/decolecta.rb
+- lib/dni_peru/response.rb
+- lib/dni_peru/version.rb
+homepage: https://github.com/rubenpazch/dni-peru
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubenpazch/dni-peru
+  source_code_uri: https://github.com/rubenpazch/dni-peru
+  changelog_uri: https://github.com/rubenpazch/dni-peru/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby gem to query DNI information from Peruvian API providers
+test_files: []