vindi-rails 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +11 -0
- data/CHANGELOG.pt-BR.md +11 -0
- data/README.md +96 -74
- data/README.pt-BR.md +97 -74
- data/WIKI.md +479 -246
- data/WIKI.pt-BR.md +479 -246
- data/lib/vindi/api_operations/create.rb +18 -14
- data/lib/vindi/api_operations/update.rb +18 -14
- data/lib/vindi/resource.rb +36 -31
- data/lib/vindi/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 0d47de92a057d08eecb40383f35a7083241a21c2ab5d1cf4a8570e9e785745c2
|
|
4
|
+
data.tar.gz: 63e9778169289f179efb040ccdcae656b50bff4ac180d28d2682cd8376965a30
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4e541c8084c6ccd3ed0f6c2a35992771cb28e3d32255f4627de72a6a495b1cf10fbb9689c9f9cf16ef6b0c58d16844274a04f3766f78a53a3f15ae2bf6c3cc16
|
|
7
|
+
data.tar.gz: 8b9df8873fbf4da7ff52d843942727bc358cb3c9e9361760d91c185487d5c93e169c17a7baf40ae9a932000ab75c25b37a2b6a65d15cfb463bbfefa7e50828dd
|
data/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [0.3.0] - 2026-06-13
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- **Idempotency Key Support**: Support for `Idempotency-Key` headers on POST/PUT actions via optional `opts` parameter in `.create` and `.update` operations.
|
|
11
|
+
- **Docker Caching Improvement**: Copy `Gemfile.lock` during the dependencies caching build step inside `Dockerfile` to prevent runtime version mismatch issues.
|
|
12
|
+
|
|
13
|
+
## [0.2.1] - 2026-06-12
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
- **Documentation**: Updated README and WIKI (both EN and PT-BR) to document the new modular webhook handlers features provided by the companion `vindi-rails-integrations` gem.
|
|
17
|
+
|
|
7
18
|
## [0.2.0] - 2026-06-10
|
|
8
19
|
|
|
9
20
|
### Added
|
data/CHANGELOG.pt-BR.md
CHANGED
|
@@ -4,6 +4,17 @@ Todas as alterações notáveis neste projeto serão documentadas neste arquivo.
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [0.3.0] - 13-06-2026
|
|
8
|
+
|
|
9
|
+
### Adicionado
|
|
10
|
+
- **Suporte a Chave de Idempotência**: Suporte ao cabeçalho `Idempotency-Key` em ações de POST/PUT através de parâmetro opcional `opts` nas operações `.create` e `.update`.
|
|
11
|
+
- **Melhoria no Cache do Docker**: Cópia do `Gemfile.lock` durante o passo de caching das dependências no `Dockerfile` para prevenir erros de incompatibilidade de versão de gemas em runtime.
|
|
12
|
+
|
|
13
|
+
## [0.2.1] - 12-06-2026
|
|
14
|
+
|
|
15
|
+
### Alterado
|
|
16
|
+
- **Documentação**: Atualizados o README e WIKI (tanto EN quanto PT-BR) para documentar os novos recursos de handlers de webhook modulares fornecidos pela gem complementar `vindi-rails-integrations`.
|
|
17
|
+
|
|
7
18
|
## [0.2.0] - 10-06-2026
|
|
8
19
|
|
|
9
20
|
### Adicionado
|
data/README.md
CHANGED
|
@@ -1,74 +1,96 @@
|
|
|
1
|
-
# Vindi Rails SDK
|
|
2
|
-
|
|
3
|
-
[Leia em Português (README.pt-BR.md)](./README.pt-BR.md)
|
|
4
|
-
|
|
5
|
-
Ruby/Rails integration SDK for the Vindi API v1 (recurring billing platform).
|
|
6
|
-
|
|
7
|
-
## Installation
|
|
8
|
-
|
|
9
|
-
Add this line to your application's Gemfile:
|
|
10
|
-
|
|
11
|
-
```ruby
|
|
12
|
-
gem 'vindi-rails'
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
And then execute:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
$ bundle install
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
## Configuration
|
|
22
|
-
|
|
23
|
-
Configure the SDK. In a Rails application, you can run the installation generator to create the initializer template:
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
$ rails generate vindi:install
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
This will create `config/initializers/vindi.rb` where you can set your keys:
|
|
30
|
-
|
|
31
|
-
```ruby
|
|
32
|
-
Vindi.configure do |config|
|
|
33
|
-
config.api_key = 'your_private_api_key'
|
|
34
|
-
# Optional: Define base URL (default is Sandbox)
|
|
35
|
-
# config.api_url = 'https://gp.vindi.com.br/api/v1'
|
|
36
|
-
end
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Usage
|
|
40
|
-
|
|
41
|
-
Resources are mapped directly under the `Vindi` namespace.
|
|
42
|
-
|
|
43
|
-
### Customers
|
|
44
|
-
|
|
45
|
-
```ruby
|
|
46
|
-
# List customers
|
|
47
|
-
customers = Vindi::Customer.list(page: 1, per_page: 20)
|
|
48
|
-
|
|
49
|
-
# Create a customer
|
|
50
|
-
customer = Vindi::Customer.create(
|
|
51
|
-
name: 'John Doe',
|
|
52
|
-
email: 'john.doe@example.com',
|
|
53
|
-
registry_code: '12345678909' # CPF/CNPJ
|
|
54
|
-
)
|
|
55
|
-
|
|
56
|
-
#
|
|
57
|
-
Vindi::Customer.
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
1
|
+
# Vindi Rails SDK
|
|
2
|
+
|
|
3
|
+
[Leia em Português (README.pt-BR.md)](./README.pt-BR.md)
|
|
4
|
+
|
|
5
|
+
Ruby/Rails integration SDK for the Vindi API v1 (recurring billing platform).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
Add this line to your application's Gemfile:
|
|
10
|
+
|
|
11
|
+
```ruby
|
|
12
|
+
gem 'vindi-rails'
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
And then execute:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
$ bundle install
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Configuration
|
|
22
|
+
|
|
23
|
+
Configure the SDK. In a Rails application, you can run the installation generator to create the initializer template:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
$ rails generate vindi:install
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
This will create `config/initializers/vindi.rb` where you can set your keys:
|
|
30
|
+
|
|
31
|
+
```ruby
|
|
32
|
+
Vindi.configure do |config|
|
|
33
|
+
config.api_key = 'your_private_api_key'
|
|
34
|
+
# Optional: Define base URL (default is Sandbox)
|
|
35
|
+
# config.api_url = 'https://gp.vindi.com.br/api/v1'
|
|
36
|
+
end
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
Resources are mapped directly under the `Vindi` namespace.
|
|
42
|
+
|
|
43
|
+
### Customers
|
|
44
|
+
|
|
45
|
+
```ruby
|
|
46
|
+
# List customers
|
|
47
|
+
customers = Vindi::Customer.list(page: 1, per_page: 20)
|
|
48
|
+
|
|
49
|
+
# Create a customer
|
|
50
|
+
customer = Vindi::Customer.create(
|
|
51
|
+
name: 'John Doe',
|
|
52
|
+
email: 'john.doe@example.com',
|
|
53
|
+
registry_code: '12345678909' # CPF/CNPJ
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
# Create a customer with an idempotency key (prevents duplicates)
|
|
57
|
+
customer = Vindi::Customer.create(
|
|
58
|
+
{ name: 'John Doe', email: 'john.doe@example.com' },
|
|
59
|
+
idempotency_key: 'unique-uuid-or-key'
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
# Update a customer
|
|
63
|
+
Vindi::Customer.update(customer.id, name: 'John Doe Updated')
|
|
64
|
+
|
|
65
|
+
# Delete a customer
|
|
66
|
+
Vindi::Customer.delete(customer.id)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Extensible Rails Integrations & Engines
|
|
70
|
+
|
|
71
|
+
To keep the SDK lightweight and free of framework dependencies, Rails-specific features are organized into extensible companion gems:
|
|
72
|
+
|
|
73
|
+
### 1. Backend Integrations ([`vindi-rails-integrations`](https://github.com/wesleyskap/vindi-rails-integrations))
|
|
74
|
+
Handles webhook processing, background jobs, and ActiveRecord synchronization:
|
|
75
|
+
- **`rails generate vindi:webhook`**: Creates a webhooks controller and background queue job stub to process payment/subscription events safely with built-in security filters and idempotency checks.
|
|
76
|
+
- **`rails generate vindi:webhook_handler [EventName]`**: Generates a modular event-specific service handler class (e.g. for `subscription_canceled`), which is automatically dispatched by the main `WebhookJob`.
|
|
77
|
+
- **`rails generate vindi:sync [Model]`**: Adds `vindi_customer_id` and database migrations to synchronize your models (e.g. `User`) automatically with Vindi via ActiveRecord callbacks.
|
|
78
|
+
- **`rails generate vindi:outbox`**: Generates a database migration for the transactional outbox table to enable resilient, asynchronous synchronization of ActiveRecord models (avoiding inline external API requests).
|
|
79
|
+
- **`rails vindi:status`**: A diagnostics Rake task to safely check configured Vindi API credentials, active environments, and verify connectivity.
|
|
80
|
+
|
|
81
|
+
### 2. Frontend Engines ([`vindi-rails-engines`](https://github.com/wesleyskap/vindi-rails-engines))
|
|
82
|
+
A mountable Rails Engine carrying pre-built Views, HTML templates, and card tokenization scripts:
|
|
83
|
+
- **`rails generate vindi:checkout`**: Copies ready-to-use checkout UI templates and Stimulus JS components using Vindi's public keys encryption.
|
|
84
|
+
|
|
85
|
+
For detailed integration guides, please refer to [WIKI.md](./WIKI.md).
|
|
86
|
+
|
|
87
|
+
## Running Tests
|
|
88
|
+
|
|
89
|
+
To run the Minitest suite:
|
|
90
|
+
```bash
|
|
91
|
+
bundle exec rake test
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Detailed Documentation
|
|
95
|
+
|
|
96
|
+
For a full list of mapped resources and detailed usage instructions, check out the [WIKI.md](./WIKI.md).
|
data/README.pt-BR.md
CHANGED
|
@@ -1,74 +1,97 @@
|
|
|
1
|
-
# Vindi Rails SDK
|
|
2
|
-
|
|
3
|
-
[Read in English (README.md)](./README.md)
|
|
4
|
-
|
|
5
|
-
SDK de integração Ruby/Rails para a API v1 da Vindi (plataforma de cobranças recorrentes).
|
|
6
|
-
|
|
7
|
-
## Instalação
|
|
8
|
-
|
|
9
|
-
Adicione esta linha ao Gemfile da sua aplicação:
|
|
10
|
-
|
|
11
|
-
```ruby
|
|
12
|
-
gem 'vindi-rails'
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
E então execute:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
$ bundle install
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
## Configuração
|
|
22
|
-
|
|
23
|
-
Configure o SDK. Em aplicações Rails, você pode rodar o gerador de instalação para criar o template de inicializador:
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
$ rails generate vindi:install
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Isso criará o arquivo `config/initializers/vindi.rb` onde você poderá configurar suas chaves:
|
|
30
|
-
|
|
31
|
-
```ruby
|
|
32
|
-
Vindi.configure do |config|
|
|
33
|
-
config.api_key = 'sua_chave_privada_da_api'
|
|
34
|
-
# Opcional: Define a URL base (padrão é o Sandbox da Vindi)
|
|
35
|
-
# config.api_url = 'https://gp.vindi.com.br/api/v1'
|
|
36
|
-
end
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Utilização
|
|
40
|
-
|
|
41
|
-
Os recursos são mapeados diretamente sob o namespace `Vindi`.
|
|
42
|
-
|
|
43
|
-
### Clientes
|
|
44
|
-
|
|
45
|
-
```ruby
|
|
46
|
-
# Listar clientes
|
|
47
|
-
clientes = Vindi::Customer.list(page: 1, per_page: 20)
|
|
48
|
-
|
|
49
|
-
# Criar cliente
|
|
50
|
-
cliente = Vindi::Customer.create(
|
|
51
|
-
name: 'João Silva',
|
|
52
|
-
email: 'joao.silva@exemplo.com',
|
|
53
|
-
registry_code: '12345678909' # CPF/CNPJ
|
|
54
|
-
)
|
|
55
|
-
|
|
56
|
-
#
|
|
57
|
-
Vindi::Customer.
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
1
|
+
# Vindi Rails SDK
|
|
2
|
+
|
|
3
|
+
[Read in English (README.md)](./README.md)
|
|
4
|
+
|
|
5
|
+
SDK de integração Ruby/Rails para a API v1 da Vindi (plataforma de cobranças recorrentes).
|
|
6
|
+
|
|
7
|
+
## Instalação
|
|
8
|
+
|
|
9
|
+
Adicione esta linha ao Gemfile da sua aplicação:
|
|
10
|
+
|
|
11
|
+
```ruby
|
|
12
|
+
gem 'vindi-rails'
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
E então execute:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
$ bundle install
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Configuração
|
|
22
|
+
|
|
23
|
+
Configure o SDK. Em aplicações Rails, você pode rodar o gerador de instalação para criar o template de inicializador:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
$ rails generate vindi:install
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Isso criará o arquivo `config/initializers/vindi.rb` onde você poderá configurar suas chaves:
|
|
30
|
+
|
|
31
|
+
```ruby
|
|
32
|
+
Vindi.configure do |config|
|
|
33
|
+
config.api_key = 'sua_chave_privada_da_api'
|
|
34
|
+
# Opcional: Define a URL base (padrão é o Sandbox da Vindi)
|
|
35
|
+
# config.api_url = 'https://gp.vindi.com.br/api/v1'
|
|
36
|
+
end
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Utilização
|
|
40
|
+
|
|
41
|
+
Os recursos são mapeados diretamente sob o namespace `Vindi`.
|
|
42
|
+
|
|
43
|
+
### Clientes
|
|
44
|
+
|
|
45
|
+
```ruby
|
|
46
|
+
# Listar clientes
|
|
47
|
+
clientes = Vindi::Customer.list(page: 1, per_page: 20)
|
|
48
|
+
|
|
49
|
+
# Criar cliente
|
|
50
|
+
cliente = Vindi::Customer.create(
|
|
51
|
+
name: 'João Silva',
|
|
52
|
+
email: 'joao.silva@exemplo.com',
|
|
53
|
+
registry_code: '12345678909' # CPF/CNPJ
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
# Criar um cliente com chave de idempotência (evita duplicados)
|
|
57
|
+
cliente = Vindi::Customer.create(
|
|
58
|
+
{ name: 'João Silva', email: 'joao.silva@exemplo.com' },
|
|
59
|
+
idempotency_key: 'chave-unica-aqui'
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
# Atualizar cliente
|
|
63
|
+
Vindi::Customer.update(cliente.id, name: 'João Silva Alterado')
|
|
64
|
+
|
|
65
|
+
# Excluir cliente
|
|
66
|
+
Vindi::Customer.delete(cliente.id)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Integrações & Engines Rails Extensíveis
|
|
70
|
+
|
|
71
|
+
Para manter o SDK base leve e sem dependências rígidas de frameworks, as integrações específicas para o Rails foram separadas em Gems extensíveis:
|
|
72
|
+
|
|
73
|
+
### 1. Integrações de Backend ([`vindi-rails-integrations`](https://github.com/wesleyskap/vindi-rails-integrations))
|
|
74
|
+
Lida com webhooks, jobs em segundo plano e sincronização do ActiveRecord:
|
|
75
|
+
- **`rails generate vindi:webhook`**: Cria a infraestrutura para recebimento de webhooks com validação de assinaturas e tratamento em background.
|
|
76
|
+
- **`rails generate vindi:webhook_handler [NomeDoEvento]`**: Cria uma classe de serviço modular especializada para processar um evento específico (ex: `subscription_canceled`), que é automaticamente despachada pelo `WebhookJob` principal.
|
|
77
|
+
- **`rails generate vindi:sync [Model]`**: Cria migrações e concerns no modelo (ex: `User`) para sincronização automática com a Vindi.
|
|
78
|
+
- **`rails generate vindi:outbox`**: Cria a migração para a tabela do outbox transacional, habilitando a sincronização resiliente e assíncrona de modelos do ActiveRecord (evitando chamadas HTTP síncronas de API).
|
|
79
|
+
- **`rails vindi:status`**: Rake task de diagnóstico para checar com segurança credenciais da API Vindi, ambiente ativo e validar conectividade.
|
|
80
|
+
|
|
81
|
+
### 2. Componentes Front-End ([`vindi-rails-engines`](https://github.com/wesleyskap/vindi-rails-engines))
|
|
82
|
+
Uma Rails Engine contendo Views e componentes prontos de criptografia e captura de cartão de crédito no navegador:
|
|
83
|
+
- **`rails generate vindi:checkout`**: Copia templates de formulário HTML/ERB e Stimulus JS integrando a criptografia de chave pública da Vindi.
|
|
84
|
+
|
|
85
|
+
Para guias e detalhes de integração, consulte a [WIKI.pt-BR.md](./WIKI.pt-BR.md).
|
|
86
|
+
|
|
87
|
+
## Rodando os Testes com Docker Compose
|
|
88
|
+
|
|
89
|
+
Para construir e executar a suíte de testes Minitest dentro do Docker:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
bundle exec rake test
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Documentação Detalhada
|
|
96
|
+
|
|
97
|
+
Para ver a lista completa de recursos mapeados e instruções de uso detalhadas, confira a [WIKI.pt-BR.md](./WIKI.pt-BR.md).
|