vindi-rails 0.2.0

data/WIKI.pt-BR.md

@@ -0,0 +1,246 @@
+# Wiki do SDK Vindi
+
+[Read in English (WIKI.md)](./WIKI.md)
+
+Bem-vindo à Wiki do SDK `vindi-rails`. Este documento detalha todos os recursos mapeados, operações suportadas e guias de uso.
+
+---
+
+## 1. Design & Arquitetura do SDK
+
+O SDK utiliza o `RestClient` internamente para se comunicar com a API da Vindi.
+Os recursos são representados como objetos Ruby que herdam de `Vindi::Resource`. Os atributos retornados pela API são acessíveis através de métodos getter dinâmicos nas instâncias.
+
+### Tratamento de Erros
+
+O SDK lança exceções específicas de acordo com os códigos de status HTTP retornados. Todos os erros herdam de `Vindi::Error`:
+
+- `Vindi::UnauthorizedError` (401)
+- `Vindi::ForbiddenError` (403)
+- `Vindi::NotFoundError` (404)
+- `Vindi::UnprocessableEntityError` (422)
+- `Vindi::RateLimitError` (429)
+- `Vindi::InternalServerError` (500+)
+- `Vindi::APIError` (Tratamento genérico para outros códigos HTTP)
+
+---
+
+## 2. Mapeamento de Recursos e Operações CRUD
+
+A tabela abaixo lista todos os recursos mapeados e suas operações disponíveis:
+
+| Classe do Recurso | Endpoint | Operações CRUD Habilitadas |
+| :--- | :--- | :--- |
+| `Vindi::Customer` | `customers` | `list`, `create`, `update`, `delete` |
+| `Vindi::PaymentProfile` | `payment_profiles` | `list`, `create`, `delete` |
+| `Vindi::Subscription` | `subscriptions` | `list`, `create`, `update`, `delete` |
+| `Vindi::Charge` | `charges` | `list`, `create`, `update` |
+| `Vindi::Plan` | `plans` | `list`, `create`, `update`, `delete` |
+| `Vindi::Product` | `products` | `list`, `create`, `update`, `delete` |
+| `Vindi::ProductItem` | `product_items` | `list`, `create`, `update`, `delete` |
+| `Vindi::Discount` | `discounts` | `list`, `create`, `delete` |
+| `Vindi::Bill` | `bills` | `list`, `create`, `update`, `delete` |
+| `Vindi::BillItem` | `bill_items` | `list` |
+| `Vindi::Period` | `periods` | `list` |
+| `Vindi::Transaction` | `transactions` | `list`, `create` |
+| `Vindi::Usage` | `usages` | `list`, `create`, `delete` |
+| `Vindi::Invoice` | `invoices` | `list` |
+| `Vindi::Movement` | `movements` | `list` |
+| `Vindi::Message` | `messages` | `list` |
+| `Vindi::ExportBatch` | `export_batches` | `list`, `create` |
+| `Vindi::ImportBatch` | `import_batches` | `list`, `create` |
+| `Vindi::Issue` | `issues` | `list`, `update` |
+| `Vindi::Notification` | `notifications` | `list` |
+| `Vindi::Merchant` | `merchants` | `list` |
+| `Vindi::MerchantUser` | `merchant_users` | `list` |
+| `Vindi::Role` | `roles` | `list` |
+| `Vindi::User` | `users` | `list` |
+| `Vindi::Public` | `public` | Nenhuma (Configuração Estática) |
+| `Vindi::Affiliate` | `affiliates` | `list` |
+| `Vindi::Partner` | `partner` | `list` |
+
+---
+
+## 3. Exemplos de Uso
+
+### Clientes (`Vindi::Customer`)
+
+```ruby
+# Criar um cliente
+cliente = Vindi::Customer.create(
+  name: "João Silva",
+  email: "joao@exemplo.com"
+)
+
+# Acessar atributos do retorno
+puts cliente.id
+puts cliente.name
+
+# Atualizar cliente
+atualizado = Vindi::Customer.update(cliente.id, email: "joao.novo@exemplo.com")
+
+# Excluir cliente
+Vindi::Customer.delete(cliente.id)
+```
+
+### Perfis de Pagamento (`Vindi::PaymentProfile`)
+
+```ruby
+# Criar perfil de pagamento com cartão
+perfil = Vindi::PaymentProfile.create(
+  customer_id: 12345,
+  payment_company_code: "visa",
+  holder_name: "JOAO SILVA",
+  card_number: "4111111111111111",
+  card_expiration_date: "12/2030",
+  card_cvv: "123"
+)
+
+# Excluir perfil de pagamento
+Vindi::PaymentProfile.delete(perfil.id)
+```
+
+### Assinaturas (`Vindi::Subscription`)
+
+```ruby
+# Criar assinatura
+assinatura = Vindi::Subscription.create(
+  customer_id: cliente.id,
+  plan_id: plano.id,
+  payment_method_code: "credit_card"
+)
+
+# Cancelar/Excluir assinatura
+Vindi::Subscription.delete(assinatura.id)
+```
+
+### Cobranças (`Vindi::Charge`)
+
+```ruby
+# Listar cobranças pendentes
+cobrancas = Vindi::Charge.list(status: "pending")
+
+# Obter valor da primeira cobrança
+puts cobrancas.first.amount
+```
+
+### Planos (`Vindi::Plan`)
+
+```ruby
+# Criar um plano
+plano = Vindi::Plan.create(
+  name: "Plano Ouro Premium",
+  code: "gold_premium",
+  interval: "months",
+  interval_count: 1
+)
+
+# Listar planos
+planos = Vindi::Plan.list
+```
+
+### Produtos & Itens de Produto (`Vindi::Product` & `Vindi::ProductItem`)
+
+```ruby
+# Criar um produto
+produto = Vindi::Product.create(
+  name: "Serviço de Hospedagem",
+  code: "hosting"
+)
+
+# Associar um produto a um plano/assinatura
+item_produto = Vindi::ProductItem.create(
+  product_id: produto.id,
+  plan_id: plano.id
+)
+```
+
+### Descontos (`Vindi::Discount`)
+
+```ruby
+# Criar/aplicar um desconto
+desconto = Vindi::Discount.create(
+  amount: 15.00,
+  discount_type: "percentage",
+  percentage: 10
+)
+```
+
+### Faturas & Itens de Fatura (`Vindi::Bill` & `Vindi::BillItem`)
+
+```ruby
+# Criar uma fatura manualmente
+fatura = Vindi::Bill.create(
+  customer_id: cliente.id,
+  payment_method_code: "credit_card",
+  bill_items: [
+    { product_id: produto.id, amount: 99.90 }
+  ]
+)
+
+# Listar itens de uma fatura
+itens = Vindi::BillItem.list(bill_id: fatura.id)
+```
+
+### Períodos (`Vindi::Period`)
+
+```ruby
+# Listar períodos de uma assinatura
+periodos = Vindi::Period.list(subscription_id: assinatura.id)
+```
+
+### Transações (`Vindi::Transaction`)
+
+```ruby
+# Criar uma transação manual (captura de cobrança)
+transacao = Vindi::Transaction.create(
+  charge_id: cobranca.id,
+  amount: 99.90
+)
+
+# Listar transações
+transacoes = Vindi::Transaction.list
+```
+
+### Consumos/Usos (`Vindi::Usage`)
+
+```ruby
+# Informar consumo de uso de uma assinatura
+uso = Vindi::Usage.create(
+  subscription_id: assinatura.id,
+  quantity: 50,
+  description: "Chamadas de API consumidas"
+)
+
+# Listar consumos informados
+usos = Vindi::Usage.list(subscription_id: assinatura.id)
+```
+
+### Notas Fiscais (`Vindi::Invoice`)
+
+```ruby
+# Listar notas fiscais emitidas
+notas_fiscais = Vindi::Invoice.list(status: "issued")
+```
+
+### Problemas/Pendências (`Vindi::Issue`)
+
+```ruby
+# Atualizar status de uma pendência (ex: marcar como resolvida)
+pendencia = Vindi::Issue.update(issue_id, status: "resolved")
+```
+
+### Lotes de Importação/Exportação (`Vindi::ImportBatch` & `Vindi::ExportBatch`)
+
+```ruby
+# Iniciar lote para importação de clientes/assinaturas
+lote_importacao = Vindi::ImportBatch.create(
+  batch_type: "customer",
+  file_url: "https://exemplo.com/importacao.csv"
+)
+
+# Solicitar lote de exportação de dados
+lote_exportacao = Vindi::ExportBatch.create(
+  batch_type: "bill"
+)
+```

data/lib/generators/vindi/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Vindi
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Vindi initializer to configure your API credentials."
+
+      def copy_initializer
+        template "vindi.rb", "config/initializers/vindi.rb"
+      end
+    end
+  end
+end

data/lib/generators/vindi/templates/vindi.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Vindi.configure do |config|
+  # Set your Vindi private API key.
+  # We recommend using Rails credentials or environment variables.
+  config.api_key = ENV["VINDI_API_KEY"]
+
+  # Set the base URL for the API (default is sandbox).
+  # For production, use: "https://gp.vindi.com.br/api/v1"
+  # config.api_url = "https://sandbox-gp.vindi.com.br/api/v1"
+end

data/lib/vindi/api_operations/create.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  module APIOperations
+    module Create
+      def create(params = {})
+        response = Client.request(:post, endpoint, params)
+        singular_key = endpoint.end_with?("batches") ? endpoint.sub(/es$/, "").to_sym : endpoint.chomp("s").to_sym
+        resource_attrs = response.key?(singular_key) ? response[singular_key] : response
+        new(resource_attrs)
+      end
+    end
+  end
+end

data/lib/vindi/api_operations/delete.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Vindi
+  module APIOperations
+    module Delete
+      def delete(id)
+        response = Client.request(:delete, "#{endpoint}/#{id}")
+        singular_key = endpoint.end_with?("batches") ? endpoint.sub(/es$/, "").to_sym : endpoint.chomp("s").to_sym
+        resource_attrs = response.key?(singular_key) ? response[singular_key] : response
+        new(resource_attrs)
+      end
+      alias destroy delete
+    end
+  end
+end

data/lib/vindi/api_operations/list.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  module APIOperations
+    module List
+      def list(params = {})
+        response = Client.request(:get, endpoint, params)
+        key = endpoint.to_sym
+        items = response[key] || response[:results] || []
+        items.map { |item_attrs| new(item_attrs) }
+      end
+    end
+  end
+end

data/lib/vindi/api_operations/update.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  module APIOperations
+    module Update
+      def update(id, params = {})
+        response = Client.request(:put, "#{endpoint}/#{id}", params)
+        singular_key = endpoint.end_with?("batches") ? endpoint.sub(/es$/, "").to_sym : endpoint.chomp("s").to_sym
+        resource_attrs = response.key?(singular_key) ? response[singular_key] : response
+        new(resource_attrs)
+      end
+    end
+  end
+end

data/lib/vindi/client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Vindi
+  class Client
+    class << self
+      def request(method, path, params = {}, headers = {})
+        api_key = Vindi.configuration.api_key
+        raise UnauthorizedError.new("API key is not configured.", status: 401) unless api_key
+
+        url = build_url(path)
+        payload = build_payload(method, params)
+        req_headers = build_headers(api_key, headers)
+
+        execute_request(method, url, payload, req_headers)
+      rescue RestClient::Exception => e
+        handle_rest_client_error(e)
+      end
+
+      private
+
+      def build_url(path)
+        "#{Vindi.configuration.api_url}/#{path.sub(%r{^/}, '')}"
+      end
+
+      def build_payload(method, params)
+        return nil if %i[get delete].include?(method.to_sym.downcase)
+        params.to_json
+      end
+
+      def build_headers(api_key, custom_headers)
+        auth = Base64.strict_encode64("#{api_key}:")
+        {
+          "Authorization" => "Basic #{auth}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json"
+        }.merge(custom_headers)
+      end
+
+      def execute_request(method, url, payload, headers)
+        options = { method: method.to_sym, url: url, headers: headers }
+        options[:payload] = payload if payload
+        response = RestClient::Request.execute(options)
+        JSON.parse(response.body, symbolize_names: true)
+      end
+
+      def handle_rest_client_error(error)
+        status = error.response&.code
+        body = error.response&.body
+        message = "HTTP request failed: #{error.message}. Response: #{body}"
+
+        raise_specific_error(message, status, body)
+      end
+
+      def raise_specific_error(msg, status, body)
+        case status
+        when 401 then raise UnauthorizedError.new(msg, status: status, response_body: body)
+        when 403 then raise ForbiddenError.new(msg, status: status, response_body: body)
+        when 404 then raise NotFoundError.new(msg, status: status, response_body: body)
+        when 422 then raise UnprocessableEntityError.new(msg, status: status, response_body: body)
+        when 429 then raise RateLimitError.new(msg, status: status, response_body: body)
+        when 500..599 then raise InternalServerError.new(msg, status: status, response_body: body)
+        else raise APIError.new(msg, status: status, response_body: body)
+        end
+      end
+    end
+  end
+end

data/lib/vindi/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Configuration
+    attr_accessor :api_key, :api_url
+
+    DEFAULT_API_URL = "https://sandbox-gp.vindi.com.br/api/v1"
+
+    def initialize
+      @api_key = nil
+      @api_url = DEFAULT_API_URL
+    end
+  end
+end

data/lib/vindi/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :response_body
+
+    def initialize(message, status: nil, response_body: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+    end
+  end
+
+  class UnauthorizedError < APIError; end
+  class ForbiddenError < APIError; end
+  class NotFoundError < APIError; end
+  class UnprocessableEntityError < APIError; end
+  class RateLimitError < APIError; end
+  class InternalServerError < APIError; end
+end

data/lib/vindi/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Railtie < ::Rails::Railtie
+    # This class allows Rails to load generator configurations automatically
+  end
+end

data/lib/vindi/resource.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Resource
+    attr_reader :attributes
+
+    def initialize(attributes = {})
+      @attributes = attributes || {}
+    end
+
+    def inspect
+      "#<#{self.class} #{attributes.inspect}>"
+    end
+
+    def method_missing(method_name, *args, &block)
+      if attributes.key?(method_name)
+        attributes[method_name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      attributes.key?(method_name) || super
+    end
+
+    def self.endpoint
+      raise NotImplementedError, "Subclasses must implement .endpoint"
+    end
+  end
+end

data/lib/vindi/resources/affiliate.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Affiliate < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "affiliates"
+    end
+  end
+end

data/lib/vindi/resources/bill.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Bill < Resource
+    extend APIOperations::List
+    extend APIOperations::Create
+    extend APIOperations::Update
+    extend APIOperations::Delete
+
+    def self.endpoint
+      "bills"
+    end
+  end
+end

data/lib/vindi/resources/bill_item.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class BillItem < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "bill_items"
+    end
+  end
+end

data/lib/vindi/resources/charge.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Charge < Resource
+    extend APIOperations::List
+    extend APIOperations::Create
+    extend APIOperations::Update
+
+    def self.endpoint
+      "charges"
+    end
+  end
+end

data/lib/vindi/resources/customer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Customer < Resource
+    extend APIOperations::List
+    extend APIOperations::Create
+    extend APIOperations::Update
+    extend APIOperations::Delete
+
+    def self.endpoint
+      "customers"
+    end
+  end
+end

data/lib/vindi/resources/discount.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Discount < Resource
+    extend APIOperations::List
+    extend APIOperations::Create
+    extend APIOperations::Delete
+
+    def self.endpoint
+      "discounts"
+    end
+  end
+end

data/lib/vindi/resources/export_batch.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Vindi
+  class ExportBatch < Resource
+    extend APIOperations::List
+    extend APIOperations::Create
+
+    def self.endpoint
+      "export_batches"
+    end
+  end
+end

data/lib/vindi/resources/import_batch.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Vindi
+  class ImportBatch < Resource
+    extend APIOperations::List
+    extend APIOperations::Create
+
+    def self.endpoint
+      "import_batches"
+    end
+  end
+end

data/lib/vindi/resources/invoice.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Invoice < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "invoices"
+    end
+  end
+end

data/lib/vindi/resources/issue.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Issue < Resource
+    extend APIOperations::List
+    extend APIOperations::Update
+
+    def self.endpoint
+      "issues"
+    end
+  end
+end

data/lib/vindi/resources/merchant.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Merchant < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "merchants"
+    end
+  end
+end

data/lib/vindi/resources/merchant_user.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class MerchantUser < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "merchant_users"
+    end
+  end
+end

data/lib/vindi/resources/message.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Message < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "messages"
+    end
+  end
+end

data/lib/vindi/resources/movement.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Movement < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "movements"
+    end
+  end
+end

data/lib/vindi/resources/notification.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vindi
+  class Notification < Resource
+    extend APIOperations::List
+
+    def self.endpoint
+      "notifications"
+    end
+  end
+end