perata-sdk 0.5.4 → 0.5.6

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.
@@ -9,7 +9,16 @@ module Perata
9
9
  @client = client
10
10
  end
11
11
 
12
- # Criar um benefício custom, license_key, feature_flag ou meter_credit; downloads e os benefícios do Discord e do GitHub se configuram no painel.
12
+ # Criar um benefício.
13
+ #
14
+ # Cria um benefício do tipo custom, license_key, feature_flag ou
15
+ # meter_credit. Os downloads e os benefícios do Discord e do GitHub se
16
+ # configuram no painel.
17
+ #
18
+ # Autenticação: chave de API da organização em Authorization: Bearer
19
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
20
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
21
+ # Respostas em JSON no envelope data; erros com error, message e fields.
13
22
  #
14
23
  # @param params [BenefitsCreateParams, Hash]
15
24
  # @return [Benefit]
@@ -18,7 +27,15 @@ module Perata
18
27
  Benefit.from_hash(data)
19
28
  end
20
29
 
21
- # Excluir um benefício: ele sai de todos os produtos e é revogado de quem o tem. The API answers 204, so there is nothing to return.
30
+ # Excluir um benefício. The API answers 204, so there is nothing to return.
31
+ #
32
+ # Exclui um benefício: ele sai de todos os produtos e é revogado de quem o
33
+ # tem.
34
+ #
35
+ # Autenticação: chave de API da organização em Authorization: Bearer
36
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
37
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
38
+ # Respostas em JSON no envelope data; erros com error, message e fields.
22
39
  #
23
40
  # @return [nil]
24
41
  def delete(benefit, idempotency_key: nil, api_key: nil)
@@ -28,13 +45,28 @@ module Perata
28
45
 
29
46
  # Ler um benefício.
30
47
  #
48
+ # Devolve um benefício pelo ID.
49
+ #
50
+ # Autenticação: chave de API da organização em Authorization: Bearer
51
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
52
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
53
+ # Respostas em JSON no envelope data; erros com error, message e fields.
54
+ #
31
55
  # @return [Benefit]
32
56
  def get(benefit, api_key: nil)
33
57
  data = @client.request("GET", "/api/v1/benefits/#{Perata.segment(benefit)}", api_key: api_key)
34
58
  Benefit.from_hash(data)
35
59
  end
36
60
 
37
- # Listar benefícios, opcionalmente de um tipo (type). One page; +list_iter+ walks every page.
61
+ # Listar benefícios. One page; +list_iter+ walks every page.
62
+ #
63
+ # Devolve uma página dos benefícios da organização. Com type, só os de um
64
+ # tipo.
65
+ #
66
+ # Autenticação: chave de API da organização em Authorization: Bearer
67
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
68
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
69
+ # Respostas em JSON no envelope data; erros com error, message e fields.
38
70
  #
39
71
  # @return [Page<Benefit>]
40
72
  def list(page: nil, limit: nil, type: nil, api_key: nil)
@@ -53,7 +85,15 @@ module Perata
53
85
  block ? items.each(&block) : items
54
86
  end
55
87
 
56
- # Listar as concessões de um benefício, opcionalmente de um cliente (customer_id) ou só as vigentes (is_granted). One page; +list_grants_iter+ walks every page.
88
+ # Listar as concessões de um benefício. One page; +list_grants_iter+ walks every page.
89
+ #
90
+ # Devolve uma página das concessões de um benefício. Com customer_id, só as
91
+ # de um cliente; com is_granted, só as vigentes ou só as revogadas.
92
+ #
93
+ # Autenticação: chave de API da organização em Authorization: Bearer
94
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
95
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
96
+ # Respostas em JSON no envelope data; erros com error, message e fields.
57
97
  #
58
98
  # @return [Page<BenefitGrant>]
59
99
  def list_grants(benefit, page: nil, limit: nil, customer_id: nil, is_granted: nil, api_key: nil)
@@ -72,7 +112,16 @@ module Perata
72
112
  block ? items.each(&block) : items
73
113
  end
74
114
 
75
- # Atualizar o nome, a visibilidade, as propriedades e os metadados de um benefício; o tipo e a descrição dada na criação não mudam, e o que a concessão já entregou fica como foi entregue.
115
+ # Atualizar um benefício.
116
+ #
117
+ # Muda o nome, a visibilidade, as propriedades e os metadados de um
118
+ # benefício. O tipo e a descrição dada na criação não mudam, e o que a
119
+ # concessão já entregou fica como foi entregue.
120
+ #
121
+ # Autenticação: chave de API da organização em Authorization: Bearer
122
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
123
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
124
+ # Respostas em JSON no envelope data; erros com error, message e fields.
76
125
  #
77
126
  # @param params [BenefitsUpdateParams, Hash]
78
127
  # @return [Benefit]
@@ -88,7 +137,16 @@ module Perata
88
137
  @client = client
89
138
  end
90
139
 
91
- # Criar um link de checkout: uma oferta durável de um ou mais produtos, com desconto, quantidade e páginas de retorno.
140
+ # Criar um link de checkout.
141
+ #
142
+ # Cria um link de checkout: uma oferta durável de um ou mais produtos, com
143
+ # desconto, quantidade e páginas de retorno. Cada visita ao link abre uma
144
+ # sessão de compra nova.
145
+ #
146
+ # Autenticação: chave de API da organização em Authorization: Bearer
147
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
148
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
149
+ # Respostas em JSON no envelope data; erros com error, message e fields.
92
150
  #
93
151
  # @param params [CheckoutLinksCreateParams, Hash]
94
152
  # @return [CheckoutLink]
@@ -97,7 +155,15 @@ module Perata
97
155
  CheckoutLink.from_hash(data)
98
156
  end
99
157
 
100
- # Excluir um link de checkout: ele deixa de abrir checkouts; os que já abriu continuam. The API answers 204, so there is nothing to return.
158
+ # Excluir um link de checkout. The API answers 204, so there is nothing to return.
159
+ #
160
+ # Exclui um link de checkout: ele deixa de abrir checkouts. Os que já abriu
161
+ # continuam.
162
+ #
163
+ # Autenticação: chave de API da organização em Authorization: Bearer
164
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
165
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
166
+ # Respostas em JSON no envelope data; erros com error, message e fields.
101
167
  #
102
168
  # @return [nil]
103
169
  def delete(checkout_link, idempotency_key: nil, api_key: nil)
@@ -107,6 +173,13 @@ module Perata
107
173
 
108
174
  # Ler um link de checkout.
109
175
  #
176
+ # Devolve um link de checkout pelo ID.
177
+ #
178
+ # Autenticação: chave de API da organização em Authorization: Bearer
179
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
180
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
181
+ # Respostas em JSON no envelope data; erros com error, message e fields.
182
+ #
110
183
  # @return [CheckoutLink]
111
184
  def get(checkout_link, api_key: nil)
112
185
  data = @client.request("GET", "/api/v1/checkout-links/#{Perata.segment(checkout_link)}", api_key: api_key)
@@ -115,6 +188,13 @@ module Perata
115
188
 
116
189
  # Listar links de checkout. One page; +list_iter+ walks every page.
117
190
  #
191
+ # Devolve uma página dos links de checkout da organização.
192
+ #
193
+ # Autenticação: chave de API da organização em Authorization: Bearer
194
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
195
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
196
+ # Respostas em JSON no envelope data; erros com error, message e fields.
197
+ #
118
198
  # @return [Page<CheckoutLink>]
119
199
  def list(page: nil, limit: nil, api_key: nil)
120
200
  query = { "page" => page, "limit" => limit }
@@ -132,7 +212,15 @@ module Perata
132
212
  block ? items.each(&block) : items
133
213
  end
134
214
 
135
- # Atualizar o rótulo, as páginas de retorno, os produtos e os metadados de um link; a quantidade e o desconto ficam como foram publicados.
215
+ # Atualizar um link de checkout.
216
+ #
217
+ # Muda o rótulo, as páginas de retorno, os produtos e os metadados de um
218
+ # link. A quantidade e o desconto ficam como foram publicados.
219
+ #
220
+ # Autenticação: chave de API da organização em Authorization: Bearer
221
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
222
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
223
+ # Respostas em JSON no envelope data; erros com error, message e fields.
136
224
  #
137
225
  # @param params [CheckoutLinksUpdateParams, Hash]
138
226
  # @return [CheckoutLink]
@@ -148,7 +236,23 @@ module Perata
148
236
  @client = client
149
237
  end
150
238
 
151
- # Criar um checkout: o endereço para onde o comprador é enviado e a sessão de compra aberta para ele, com o client_secret que o navegador do comprador usa nas rotas de cliente.
239
+ # Criar um checkout.
240
+ #
241
+ # Cria um checkout. Devolve o endereço para onde mandar o comprador e a
242
+ # sessão de compra aberta para ele, com o client_secret que o navegador do
243
+ # comprador usa para pagar sem chave de API; o client_secret vem só nesta
244
+ # resposta. Para cobrar um valor que o seu servidor define, envie
245
+ # amount_cents e items (preço de valor livre). Envie client_reference_id e
246
+ # metadata para achar o pedido depois. Em uma assinatura, envie as linhas do
247
+ # pedido em items (só para exibição, com a soma igual ao valor do preço) e o
248
+ # desconto em discount_id. Para uma assinatura que só começa a cobrar numa
249
+ # data, envie subscription_start_at com o preço recorrente: o cartão é
250
+ # guardado sem cobrança e a primeira cobrança acontece nesse dia.
251
+ #
252
+ # Autenticação: chave de API da organização em Authorization: Bearer
253
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
254
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
255
+ # Respostas em JSON no envelope data; erros com error, message e fields.
152
256
  #
153
257
  # @param params [CheckoutsCreateParams, Hash]
154
258
  # @return [CheckoutCreated]
@@ -157,7 +261,17 @@ module Perata
157
261
  CheckoutCreated.from_hash(data)
158
262
  end
159
263
 
160
- # Encerrar um checkout que não deve mais ser pago: a página, o client_secret e o QR do Pix deixam de valer (o Pix já gerado é cancelado na Cielo), e o evento checkout.expired é enviado; 409 se já foi pago ou se emitiu boleto.
264
+ # Encerrar um checkout.
265
+ #
266
+ # Encerra um checkout que não deve mais ser pago: a página, o client_secret
267
+ # e o QR do Pix deixam de valer (o Pix já gerado é cancelado na Cielo) e o
268
+ # evento checkout.expired é enviado. Repetir a chamada é seguro. Se o
269
+ # checkout já foi pago ou emitiu um boleto, a resposta é 409.
270
+ #
271
+ # Autenticação: chave de API da organização em Authorization: Bearer
272
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
273
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
274
+ # Respostas em JSON no envelope data; erros com error, message e fields.
161
275
  #
162
276
  # @return [CheckoutExpired]
163
277
  def expire(checkout, idempotency_key: nil, api_key: nil)
@@ -165,7 +279,14 @@ module Perata
165
279
  CheckoutExpired.from_hash(data)
166
280
  end
167
281
 
168
- # Ler um checkout: o endereço, o estado e as páginas de retorno.
282
+ # Ler um checkout.
283
+ #
284
+ # Devolve um checkout: o endereço, o estado e as páginas de retorno.
285
+ #
286
+ # Autenticação: chave de API da organização em Authorization: Bearer
287
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
288
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
289
+ # Respostas em JSON no envelope data; erros com error, message e fields.
169
290
  #
170
291
  # @return [Checkout]
171
292
  def get(checkout, api_key: nil)
@@ -173,11 +294,19 @@ module Perata
173
294
  Checkout.from_hash(data)
174
295
  end
175
296
 
176
- # Listar checkouts, opcionalmente de um client_reference_id, de um status, de um período ou de metadados. One page; +list_iter+ walks every page.
297
+ # Listar checkouts. One page; +list_iter+ walks every page.
298
+ #
299
+ # Devolve uma página dos checkouts. Filtre por client_reference_id, status,
300
+ # período ou metadados.
301
+ #
302
+ # Autenticação: chave de API da organização em Authorization: Bearer
303
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
304
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
305
+ # Respostas em JSON no envelope data; erros com error, message e fields.
177
306
  #
178
307
  # @return [Page<Checkout>]
179
- def list(page: nil, limit: nil, client_reference_id: nil, status: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil)
180
- query = { "page" => page, "limit" => limit, "client_reference_id" => client_reference_id, "status" => status, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting }
308
+ def list(page: nil, limit: nil, client_reference_id: nil, status: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil)
309
+ query = { "page" => page, "limit" => limit, "client_reference_id" => client_reference_id, "status" => status, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting, "metadata" => metadata }
181
310
  data = @client.request("GET", "/api/v1/checkouts", query: query, api_key: api_key)
182
311
  Page.from_hash(data) { |item| Checkout.from_hash(item) }
183
312
  end
@@ -185,14 +314,21 @@ module Perata
185
314
  # Walks every page of checkouts:list from +page+, item by item.
186
315
  #
187
316
  # @return [Enumerator<Checkout>]
188
- def list_iter(page: nil, limit: nil, client_reference_id: nil, status: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil, &block)
317
+ def list_iter(page: nil, limit: nil, client_reference_id: nil, status: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil, &block)
189
318
  items = Page.iterate(page) do |at|
190
- list(page: at, limit: limit, client_reference_id: client_reference_id, status: status, created_after: created_after, created_before: created_before, sorting: sorting, api_key: api_key)
319
+ list(page: at, limit: limit, client_reference_id: client_reference_id, status: status, created_after: created_after, created_before: created_before, sorting: sorting, metadata: metadata, api_key: api_key)
191
320
  end
192
321
  block ? items.each(&block) : items
193
322
  end
194
323
 
195
- # Atualizar o rótulo e as páginas de retorno de um checkout ativo.
324
+ # Atualizar um checkout.
325
+ #
326
+ # Muda o rótulo e as páginas de retorno de um checkout ativo.
327
+ #
328
+ # Autenticação: chave de API da organização em Authorization: Bearer
329
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
330
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
331
+ # Respostas em JSON no envelope data; erros com error, message e fields.
196
332
  #
197
333
  # @param params [CheckoutsUpdateParams, Hash]
198
334
  # @return [Checkout]
@@ -208,7 +344,16 @@ module Perata
208
344
  @client = client
209
345
  end
210
346
 
211
- # Entrar com um cliente no portal do cliente: o endereço o abre já autenticado.
347
+ # Abrir o portal do cliente.
348
+ #
349
+ # Abre uma sessão do portal do cliente para o cliente informado e devolve o
350
+ # endereço que o abre já autenticado. Com return_url, um endereço https do
351
+ # seu aplicativo, o portal oferece a volta.
352
+ #
353
+ # Autenticação: chave de API da organização em Authorization: Bearer
354
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
355
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
356
+ # Respostas em JSON no envelope data; erros com error, message e fields.
212
357
  #
213
358
  # @param params [CustomerSessionsCreateParams, Hash]
214
359
  # @return [CustomerSession]
@@ -224,7 +369,18 @@ module Perata
224
369
  @client = client
225
370
  end
226
371
 
227
- # Criar um cliente, com CPF ou CNPJ, telefone e endereço de cobrança se você os tem.
372
+ # Criar um cliente.
373
+ #
374
+ # Cria um cliente, com CPF ou CNPJ, telefone e endereço de cobrança, se você
375
+ # os tem. Se você enviar external_id e o e-mail já for de um cliente que
376
+ # ainda não tem ID externo (por exemplo, um que o checkout criou), esse
377
+ # cliente recebe o ID e os dados enviados, e a resposta é 200 em vez de 201.
378
+ # Se o e-mail for de um cliente com outro ID externo, a resposta é 422.
379
+ #
380
+ # Autenticação: chave de API da organização em Authorization: Bearer
381
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
382
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
383
+ # Respostas em JSON no envelope data; erros com error, message e fields.
228
384
  #
229
385
  # @param params [CustomersCreateParams, Hash]
230
386
  # @return [Customer]
@@ -233,7 +389,16 @@ module Perata
233
389
  Customer.from_hash(data)
234
390
  end
235
391
 
236
- # Excluir um cliente: as assinaturas terminam na hora, os benefícios são revogados e o ID externo é liberado; pedidos e pagamentos continuam. The API answers 204, so there is nothing to return.
392
+ # Excluir um cliente. The API answers 204, so there is nothing to return.
393
+ #
394
+ # Exclui um cliente: as assinaturas terminam na hora, os benefícios são
395
+ # revogados e o ID externo fica livre. Os pedidos e os pagamentos continuam
396
+ # nos registros.
397
+ #
398
+ # Autenticação: chave de API da organização em Authorization: Bearer
399
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
400
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
401
+ # Respostas em JSON no envelope data; erros com error, message e fields.
237
402
  #
238
403
  # @return [nil]
239
404
  def delete(customer, idempotency_key: nil, api_key: nil)
@@ -243,13 +408,28 @@ module Perata
243
408
 
244
409
  # Ler um cliente.
245
410
  #
411
+ # Devolve um cliente pelo ID.
412
+ #
413
+ # Autenticação: chave de API da organização em Authorization: Bearer
414
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
415
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
416
+ # Respostas em JSON no envelope data; erros com error, message e fields.
417
+ #
246
418
  # @return [Customer]
247
419
  def get(customer, api_key: nil)
248
420
  data = @client.request("GET", "/api/v1/customers/#{Perata.segment(customer)}", api_key: api_key)
249
421
  Customer.from_hash(data)
250
422
  end
251
423
 
252
- # Ler um cliente pelo ID dele no sistema do lojista (external_id).
424
+ # Ler um cliente pelo ID externo.
425
+ #
426
+ # Devolve o cliente que você identifica pelo ID dele no seu sistema
427
+ # (external_id).
428
+ #
429
+ # Autenticação: chave de API da organização em Authorization: Bearer
430
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
431
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
432
+ # Respostas em JSON no envelope data; erros com error, message e fields.
253
433
  #
254
434
  # @return [Customer]
255
435
  def get_external(external_id, api_key: nil)
@@ -257,7 +437,16 @@ module Perata
257
437
  Customer.from_hash(data)
258
438
  end
259
439
 
260
- # Ler o estado de um cliente: assinaturas ativas e benefícios vigentes, inclusive os feature flags.
440
+ # Ler o estado de um cliente.
441
+ #
442
+ # Devolve o estado de um cliente: as assinaturas ativas e os benefícios
443
+ # vigentes, inclusive os feature flags. É a leitura que o seu aplicativo faz
444
+ # para decidir o que o cliente pode usar.
445
+ #
446
+ # Autenticação: chave de API da organização em Authorization: Bearer
447
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
448
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
449
+ # Respostas em JSON no envelope data; erros com error, message e fields.
261
450
  #
262
451
  # @return [CustomerState]
263
452
  def get_state(customer, api_key: nil)
@@ -267,9 +456,17 @@ module Perata
267
456
 
268
457
  # Listar clientes. One page; +list_iter+ walks every page.
269
458
  #
459
+ # Devolve uma página dos clientes. Com email, só o cliente com esse e-mail,
460
+ # sem diferença entre maiúsculas e minúsculas.
461
+ #
462
+ # Autenticação: chave de API da organização em Authorization: Bearer
463
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
464
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
465
+ # Respostas em JSON no envelope data; erros com error, message e fields.
466
+ #
270
467
  # @return [Page<Customer>]
271
- def list(page: nil, limit: nil, api_key: nil)
272
- query = { "page" => page, "limit" => limit }
468
+ def list(page: nil, limit: nil, email: nil, api_key: nil)
469
+ query = { "page" => page, "limit" => limit, "email" => email }
273
470
  data = @client.request("GET", "/api/v1/customers", query: query, api_key: api_key)
274
471
  Page.from_hash(data) { |item| Customer.from_hash(item) }
275
472
  end
@@ -277,14 +474,22 @@ module Perata
277
474
  # Walks every page of customers:list from +page+, item by item.
278
475
  #
279
476
  # @return [Enumerator<Customer>]
280
- def list_iter(page: nil, limit: nil, api_key: nil, &block)
477
+ def list_iter(page: nil, limit: nil, email: nil, api_key: nil, &block)
281
478
  items = Page.iterate(page) do |at|
282
- list(page: at, limit: limit, api_key: api_key)
479
+ list(page: at, limit: limit, email: email, api_key: api_key)
283
480
  end
284
481
  block ? items.each(&block) : items
285
482
  end
286
483
 
287
- # Atualizar o nome, o e-mail, o ID externo, o CPF ou CNPJ, o telefone ou o endereço de cobrança de um cliente; o ID externo não muda depois de definido.
484
+ # Atualizar um cliente.
485
+ #
486
+ # Muda o nome, o e-mail, o ID externo, o CPF ou CNPJ, o telefone ou o
487
+ # endereço de cobrança. O ID externo só pode ser definido uma vez.
488
+ #
489
+ # Autenticação: chave de API da organização em Authorization: Bearer
490
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
491
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
492
+ # Respostas em JSON no envelope data; erros com error, message e fields.
288
493
  #
289
494
  # @param params [CustomersUpdateParams, Hash]
290
495
  # @return [Customer]
@@ -293,7 +498,15 @@ module Perata
293
498
  Customer.from_hash(data)
294
499
  end
295
500
 
296
- # Atualizar um cliente pelo ID dele no sistema do lojista (external_id).
501
+ # Atualizar um cliente pelo ID externo.
502
+ #
503
+ # Muda o cliente que você identifica pelo ID dele no seu sistema
504
+ # (external_id). Os campos são os de Atualizar um cliente.
505
+ #
506
+ # Autenticação: chave de API da organização em Authorization: Bearer
507
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
508
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
509
+ # Respostas em JSON no envelope data; erros com error, message e fields.
297
510
  #
298
511
  # @param params [CustomersUpdateExternalParams, Hash]
299
512
  # @return [Customer]
@@ -309,7 +522,16 @@ module Perata
309
522
  @client = client
310
523
  end
311
524
 
312
- # Criar um desconto percentual (basis_points) ou fixo em reais (amount_cents).
525
+ # Criar um desconto.
526
+ #
527
+ # Cria um desconto percentual (basis_points) ou de valor fixo em reais
528
+ # (amount_cents). O código é o que o comprador digita; sem ele, o desconto
529
+ # só vale num link de checkout ou pela API.
530
+ #
531
+ # Autenticação: chave de API da organização em Authorization: Bearer
532
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
533
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
534
+ # Respostas em JSON no envelope data; erros com error, message e fields.
313
535
  #
314
536
  # @param params [DiscountsCreateParams, Hash]
315
537
  # @return [Discount]
@@ -318,7 +540,15 @@ module Perata
318
540
  Discount.from_hash(data)
319
541
  end
320
542
 
321
- # Excluir um desconto: sai das listas e dos checkouts e o código fica livre; o que ele já descontou continua nos registros. The API answers 204, so there is nothing to return.
543
+ # Excluir um desconto. The API answers 204, so there is nothing to return.
544
+ #
545
+ # Exclui um desconto: ele sai das listas e dos checkouts, e o código fica
546
+ # livre. O que ele já descontou continua nos registros.
547
+ #
548
+ # Autenticação: chave de API da organização em Authorization: Bearer
549
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
550
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
551
+ # Respostas em JSON no envelope data; erros com error, message e fields.
322
552
  #
323
553
  # @return [nil]
324
554
  def delete(discount, idempotency_key: nil, api_key: nil)
@@ -328,6 +558,13 @@ module Perata
328
558
 
329
559
  # Ler um desconto.
330
560
  #
561
+ # Devolve um desconto pelo ID.
562
+ #
563
+ # Autenticação: chave de API da organização em Authorization: Bearer
564
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
565
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
566
+ # Respostas em JSON no envelope data; erros com error, message e fields.
567
+ #
331
568
  # @return [Discount]
332
569
  def get(discount, api_key: nil)
333
570
  data = @client.request("GET", "/api/v1/discounts/#{Perata.segment(discount)}", api_key: api_key)
@@ -336,6 +573,13 @@ module Perata
336
573
 
337
574
  # Listar descontos. One page; +list_iter+ walks every page.
338
575
  #
576
+ # Devolve uma página dos descontos da organização.
577
+ #
578
+ # Autenticação: chave de API da organização em Authorization: Bearer
579
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
580
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
581
+ # Respostas em JSON no envelope data; erros com error, message e fields.
582
+ #
339
583
  # @return [Page<Discount>]
340
584
  def list(page: nil, limit: nil, api_key: nil)
341
585
  query = { "page" => page, "limit" => limit }
@@ -353,7 +597,15 @@ module Perata
353
597
  block ? items.each(&block) : items
354
598
  end
355
599
 
356
- # Atualizar um desconto; o tipo e a duração não mudam, e depois do primeiro uso o valor e os meses também não.
600
+ # Atualizar um desconto.
601
+ #
602
+ # Muda um desconto. O tipo e a duração não mudam; depois do primeiro uso, o
603
+ # valor e os meses também não.
604
+ #
605
+ # Autenticação: chave de API da organização em Authorization: Bearer
606
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
607
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
608
+ # Respostas em JSON no envelope data; erros com error, message e fields.
357
609
  #
358
610
  # @param params [DiscountsUpdateParams, Hash]
359
611
  # @return [Discount]
@@ -371,13 +623,27 @@ module Perata
371
623
 
372
624
  # Ler uma disputa.
373
625
  #
626
+ # Devolve uma disputa pelo ID.
627
+ #
628
+ # Autenticação: chave de API da organização em Authorization: Bearer
629
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
630
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
631
+ # Respostas em JSON no envelope data; erros com error, message e fields.
632
+ #
374
633
  # @return [Dispute]
375
634
  def get(dispute, api_key: nil)
376
635
  data = @client.request("GET", "/api/v1/disputes/#{Perata.segment(dispute)}", api_key: api_key)
377
636
  Dispute.from_hash(data)
378
637
  end
379
638
 
380
- # Listar disputas, opcionalmente de um status (status). One page; +list_iter+ walks every page.
639
+ # Listar disputas. One page; +list_iter+ walks every page.
640
+ #
641
+ # Devolve uma página das disputas. Com status, só as que estão nele.
642
+ #
643
+ # Autenticação: chave de API da organização em Authorization: Bearer
644
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
645
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
646
+ # Respostas em JSON no envelope data; erros com error, message e fields.
381
647
  #
382
648
  # @return [Page<Dispute>]
383
649
  def list(page: nil, limit: nil, status: nil, api_key: nil)
@@ -403,7 +669,15 @@ module Perata
403
669
  @client = client
404
670
  end
405
671
 
406
- # Listar os eventos de consumo que as origens enviaram, do mais novo ao mais antigo. One page; +list_iter+ walks every page.
672
+ # Listar eventos de consumo. One page; +list_iter+ walks every page.
673
+ #
674
+ # Devolve uma página dos eventos de consumo que as fontes enviaram, do mais
675
+ # novo ao mais antigo.
676
+ #
677
+ # Autenticação: chave de API da organização em Authorization: Bearer
678
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
679
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
680
+ # Respostas em JSON no envelope data; erros com error, message e fields.
407
681
  #
408
682
  # @return [Page<Event>]
409
683
  def list(page: nil, limit: nil, customer_id: nil, start: nil, end_: nil, api_key: nil)
@@ -429,7 +703,15 @@ module Perata
429
703
  @client = client
430
704
  end
431
705
 
432
- # Ler um medidor: o filtro dos eventos que ele conta, a agregação e a unidade.
706
+ # Ler um medidor.
707
+ #
708
+ # Devolve um medidor: o filtro dos eventos que ele conta, a agregação e a
709
+ # unidade.
710
+ #
711
+ # Autenticação: chave de API da organização em Authorization: Bearer
712
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
713
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
714
+ # Respostas em JSON no envelope data; erros com error, message e fields.
433
715
  #
434
716
  # @return [Meter]
435
717
  def get(meter, api_key: nil)
@@ -437,7 +719,15 @@ module Perata
437
719
  Meter.from_hash(data)
438
720
  end
439
721
 
440
- # Listar medidores; os arquivados só com is_archived=true. One page; +list_iter+ walks every page.
722
+ # Listar medidores. One page; +list_iter+ walks every page.
723
+ #
724
+ # Devolve uma página dos medidores. Os arquivados só aparecem com
725
+ # is_archived=true.
726
+ #
727
+ # Autenticação: chave de API da organização em Authorization: Bearer
728
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
729
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
730
+ # Respostas em JSON no envelope data; erros com error, message e fields.
441
731
  #
442
732
  # @return [Page<Meter>]
443
733
  def list(page: nil, limit: nil, is_archived: nil, api_key: nil)
@@ -463,7 +753,15 @@ module Perata
463
753
  @client = client
464
754
  end
465
755
 
466
- # Ler um pedido: um checkout pago.
756
+ # Ler um pedido.
757
+ #
758
+ # Devolve um pedido: um checkout pago. Se ele pagou um ciclo de assinatura,
759
+ # traz subscription_id, cycle_sequence, period_start e period_end.
760
+ #
761
+ # Autenticação: chave de API da organização em Authorization: Bearer
762
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
763
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
764
+ # Respostas em JSON no envelope data; erros com error, message e fields.
467
765
  #
468
766
  # @return [Order]
469
767
  def get(order, api_key: nil)
@@ -471,7 +769,15 @@ module Perata
471
769
  Order.from_hash(data)
472
770
  end
473
771
 
474
- # Ler a fatura de um pedido, o documento comercial que o lojista gerou; sem ela, 404.
772
+ # Ler a fatura de um pedido.
773
+ #
774
+ # Devolve a fatura de um pedido, o documento comercial que o lojista gerou.
775
+ # Sem fatura, a resposta é 404.
776
+ #
777
+ # Autenticação: chave de API da organização em Authorization: Bearer
778
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
779
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
780
+ # Respostas em JSON no envelope data; erros com error, message e fields.
475
781
  #
476
782
  # @return [OrderInvoice]
477
783
  def get_invoice(order, api_key: nil)
@@ -479,7 +785,14 @@ module Perata
479
785
  OrderInvoice.from_hash(data)
480
786
  end
481
787
 
482
- # Ler o recibo de um pedido: o que foi pago, quando e como.
788
+ # Ler o recibo de um pedido.
789
+ #
790
+ # Devolve o recibo de um pedido: o que foi pago, quando e como.
791
+ #
792
+ # Autenticação: chave de API da organização em Authorization: Bearer
793
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
794
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
795
+ # Respostas em JSON no envelope data; erros com error, message e fields.
483
796
  #
484
797
  # @return [OrderReceipt]
485
798
  def get_receipt(order, api_key: nil)
@@ -487,11 +800,20 @@ module Perata
487
800
  OrderReceipt.from_hash(data)
488
801
  end
489
802
 
490
- # Listar pedidos (checkouts pagos), opcionalmente de um client_reference_id, de um cliente, de um período ou de metadados. One page; +list_iter+ walks every page.
803
+ # Listar pedidos. One page; +list_iter+ walks every page.
804
+ #
805
+ # Devolve uma página dos pedidos, que são os checkouts pagos. Filtre por
806
+ # client_reference_id, cliente, assinatura (subscription_id), período ou
807
+ # metadados.
808
+ #
809
+ # Autenticação: chave de API da organização em Authorization: Bearer
810
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
811
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
812
+ # Respostas em JSON no envelope data; erros com error, message e fields.
491
813
  #
492
814
  # @return [Page<Order>]
493
- def list(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil)
494
- query = { "page" => page, "limit" => limit, "client_reference_id" => client_reference_id, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting }
815
+ def list(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, subscription_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil)
816
+ query = { "page" => page, "limit" => limit, "client_reference_id" => client_reference_id, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "subscription_id" => subscription_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting, "metadata" => metadata }
495
817
  data = @client.request("GET", "/api/v1/orders", query: query, api_key: api_key)
496
818
  Page.from_hash(data) { |item| Order.from_hash(item) }
497
819
  end
@@ -499,9 +821,9 @@ module Perata
499
821
  # Walks every page of orders:list from +page+, item by item.
500
822
  #
501
823
  # @return [Enumerator<Order>]
502
- def list_iter(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil, &block)
824
+ def list_iter(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, subscription_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil, &block)
503
825
  items = Page.iterate(page) do |at|
504
- list(page: at, limit: limit, client_reference_id: client_reference_id, status: status, customer_id: customer_id, external_customer_id: external_customer_id, created_after: created_after, created_before: created_before, sorting: sorting, api_key: api_key)
826
+ list(page: at, limit: limit, client_reference_id: client_reference_id, status: status, customer_id: customer_id, external_customer_id: external_customer_id, subscription_id: subscription_id, created_after: created_after, created_before: created_before, sorting: sorting, metadata: metadata, api_key: api_key)
505
827
  end
506
828
  block ? items.each(&block) : items
507
829
  end
@@ -513,7 +835,15 @@ module Perata
513
835
  @client = client
514
836
  end
515
837
 
516
- # Parar de cobrar um cartão guardado; recusado enquanto uma assinatura ativa o cobra.
838
+ # Parar de cobrar um cartão guardado.
839
+ #
840
+ # Para de cobrar um cartão guardado. É recusado (409) enquanto uma
841
+ # assinatura ativa o cobra.
842
+ #
843
+ # Autenticação: chave de API da organização em Authorization: Bearer
844
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
845
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
846
+ # Respostas em JSON no envelope data; erros com error, message e fields.
517
847
  #
518
848
  # @return [PaymentMethodDetached]
519
849
  def detach(payment_method, idempotency_key: nil, api_key: nil)
@@ -521,7 +851,15 @@ module Perata
521
851
  PaymentMethodDetached.from_hash(data)
522
852
  end
523
853
 
524
- # Listar os cartões guardados de um cliente: bandeira, quatro últimos dígitos e validade. One page; +list_iter+ walks every page.
854
+ # Listar os cartões guardados de um cliente. One page; +list_iter+ walks every page.
855
+ #
856
+ # Devolve os cartões guardados de um cliente: bandeira, quatro últimos
857
+ # dígitos e validade. O número do cartão nunca aparece.
858
+ #
859
+ # Autenticação: chave de API da organização em Authorization: Bearer
860
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
861
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
862
+ # Respostas em JSON no envelope data; erros com error, message e fields.
525
863
  #
526
864
  # @return [Page<PaymentMethod>]
527
865
  def list(customer, page: nil, limit: nil, api_key: nil)
@@ -549,17 +887,32 @@ module Perata
549
887
 
550
888
  # Ler um pagamento.
551
889
  #
890
+ # Devolve um pagamento pelo ID.
891
+ #
892
+ # Autenticação: chave de API da organização em Authorization: Bearer
893
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
894
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
895
+ # Respostas em JSON no envelope data; erros com error, message e fields.
896
+ #
552
897
  # @return [Payment]
553
898
  def get(payment, api_key: nil)
554
899
  data = @client.request("GET", "/api/v1/payments/#{Perata.segment(payment)}", api_key: api_key)
555
900
  Payment.from_hash(data)
556
901
  end
557
902
 
558
- # Listar pagamentos, opcionalmente de um client_reference_id, de um estado, de um cliente, de um período ou de metadados. One page; +list_iter+ walks every page.
903
+ # Listar pagamentos. One page; +list_iter+ walks every page.
904
+ #
905
+ # Devolve uma página dos pagamentos. Filtre por client_reference_id, estado,
906
+ # cliente, assinatura (subscription_id), período ou metadados.
907
+ #
908
+ # Autenticação: chave de API da organização em Authorization: Bearer
909
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
910
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
911
+ # Respostas em JSON no envelope data; erros com error, message e fields.
559
912
  #
560
913
  # @return [Page<Payment>]
561
- def list(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil)
562
- query = { "page" => page, "limit" => limit, "client_reference_id" => client_reference_id, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting }
914
+ def list(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, subscription_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil)
915
+ query = { "page" => page, "limit" => limit, "client_reference_id" => client_reference_id, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "subscription_id" => subscription_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting, "metadata" => metadata }
563
916
  data = @client.request("GET", "/api/v1/payments", query: query, api_key: api_key)
564
917
  Page.from_hash(data) { |item| Payment.from_hash(item) }
565
918
  end
@@ -567,9 +920,9 @@ module Perata
567
920
  # Walks every page of payments:list from +page+, item by item.
568
921
  #
569
922
  # @return [Enumerator<Payment>]
570
- def list_iter(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil, &block)
923
+ def list_iter(page: nil, limit: nil, client_reference_id: nil, status: nil, customer_id: nil, external_customer_id: nil, subscription_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil, &block)
571
924
  items = Page.iterate(page) do |at|
572
- list(page: at, limit: limit, client_reference_id: client_reference_id, status: status, customer_id: customer_id, external_customer_id: external_customer_id, created_after: created_after, created_before: created_before, sorting: sorting, api_key: api_key)
925
+ list(page: at, limit: limit, client_reference_id: client_reference_id, status: status, customer_id: customer_id, external_customer_id: external_customer_id, subscription_id: subscription_id, created_after: created_after, created_before: created_before, sorting: sorting, metadata: metadata, api_key: api_key)
573
926
  end
574
927
  block ? items.each(&block) : items
575
928
  end
@@ -581,7 +934,16 @@ module Perata
581
934
  @client = client
582
935
  end
583
936
 
584
- # Criar um preço em reais, avulso ou recorrente.
937
+ # Criar um preço.
938
+ #
939
+ # Cria um preço em reais para um produto, avulso (one_time) ou recorrente
940
+ # (recurring). No recorrente, interval e interval_count dizem de quanto em
941
+ # quanto tempo ele renova: month com 3 é trimestral.
942
+ #
943
+ # Autenticação: chave de API da organização em Authorization: Bearer
944
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
945
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
946
+ # Respostas em JSON no envelope data; erros com error, message e fields.
585
947
  #
586
948
  # @param params [PricesCreateParams, Hash]
587
949
  # @return [Price]
@@ -590,7 +952,15 @@ module Perata
590
952
  Price.from_hash(data)
591
953
  end
592
954
 
593
- # Listar preços, opcionalmente de um produto (product_id). One page; +list_iter+ walks every page.
955
+ # Listar preços. One page; +list_iter+ walks every page.
956
+ #
957
+ # Devolve uma página dos preços da organização. Com product_id, só os de um
958
+ # produto.
959
+ #
960
+ # Autenticação: chave de API da organização em Authorization: Bearer
961
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
962
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
963
+ # Respostas em JSON no envelope data; erros com error, message e fields.
594
964
  #
595
965
  # @return [Page<Price>]
596
966
  def list(page: nil, limit: nil, product_id: nil, api_key: nil)
@@ -616,7 +986,15 @@ module Perata
616
986
  @client = client
617
987
  end
618
988
 
619
- # Arquivar um produto: sai das vendas novas e o que já foi vendido continua apontando para ele.
989
+ # Arquivar um produto.
990
+ #
991
+ # Arquiva um produto: ele sai das vendas novas, e o que já foi vendido
992
+ # continua apontando para ele.
993
+ #
994
+ # Autenticação: chave de API da organização em Authorization: Bearer
995
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
996
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
997
+ # Respostas em JSON no envelope data; erros com error, message e fields.
620
998
  #
621
999
  # @return [Product]
622
1000
  def archive(product, idempotency_key: nil, api_key: nil)
@@ -626,6 +1004,14 @@ module Perata
626
1004
 
627
1005
  # Criar um produto.
628
1006
  #
1007
+ # Cria um produto com nome e descrição. O preço se cria à parte, em Criar um
1008
+ # preço.
1009
+ #
1010
+ # Autenticação: chave de API da organização em Authorization: Bearer
1011
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1012
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1013
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1014
+ #
629
1015
  # @param params [ProductsCreateParams, Hash]
630
1016
  # @return [Product]
631
1017
  def create(params, idempotency_key: nil, api_key: nil)
@@ -635,6 +1021,13 @@ module Perata
635
1021
 
636
1022
  # Ler um produto.
637
1023
  #
1024
+ # Devolve um produto pelo ID.
1025
+ #
1026
+ # Autenticação: chave de API da organização em Authorization: Bearer
1027
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1028
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1029
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1030
+ #
638
1031
  # @return [Product]
639
1032
  def get(product, api_key: nil)
640
1033
  data = @client.request("GET", "/api/v1/products/#{Perata.segment(product)}", api_key: api_key)
@@ -643,6 +1036,13 @@ module Perata
643
1036
 
644
1037
  # Listar produtos. One page; +list_iter+ walks every page.
645
1038
  #
1039
+ # Devolve uma página dos produtos da organização, no ambiente da chave.
1040
+ #
1041
+ # Autenticação: chave de API da organização em Authorization: Bearer
1042
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1043
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1044
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1045
+ #
646
1046
  # @return [Page<Product>]
647
1047
  def list(page: nil, limit: nil, api_key: nil)
648
1048
  query = { "page" => page, "limit" => limit }
@@ -660,7 +1060,15 @@ module Perata
660
1060
  block ? items.each(&block) : items
661
1061
  end
662
1062
 
663
- # Atualizar o nome ou a descrição de um produto ativo.
1063
+ # Atualizar um produto.
1064
+ #
1065
+ # Muda o nome ou a descrição de um produto ativo. O que você não enviar fica
1066
+ # como está.
1067
+ #
1068
+ # Autenticação: chave de API da organização em Authorization: Bearer
1069
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1070
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1071
+ # Respostas em JSON no envelope data; erros com error, message e fields.
664
1072
  #
665
1073
  # @param params [ProductsUpdateParams, Hash]
666
1074
  # @return [Product]
@@ -676,7 +1084,21 @@ module Perata
676
1084
  @client = client
677
1085
  end
678
1086
 
679
- # Reembolsar parte ou todo um pagamento.
1087
+ # Reembolsar um pagamento ou um pedido.
1088
+ #
1089
+ # Devolve dinheiro de um pagamento, que você nomeia pelo payment_id ou pelo
1090
+ # order_id do pedido que ele pagou (os dois, só se forem do mesmo
1091
+ # pagamento). Sem amount_cents devolve tudo o que ainda pode ser devolvido;
1092
+ # com ele, uma parte, até esse limite. O reason, sem ele, é
1093
+ # requested_by_customer. O metadata fica no reembolso e volta nele e nos
1094
+ # eventos refund.*. A Idempotency-Key é obrigatória: sem ela, repetir a
1095
+ # chamada depois de um tempo esgotado seria devolver duas vezes; repetida
1096
+ # com a mesma chave, devolve o mesmo reembolso.
1097
+ #
1098
+ # Autenticação: chave de API da organização em Authorization: Bearer
1099
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1100
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1101
+ # Respostas em JSON no envelope data; erros com error, message e fields.
680
1102
  #
681
1103
  # @param params [RefundsCreateParams, Hash]
682
1104
  # @return [Refund]
@@ -685,11 +1107,36 @@ module Perata
685
1107
  Refund.from_hash(data)
686
1108
  end
687
1109
 
688
- # Listar reembolsos, opcionalmente de um pagamento (payment_id), de um status, de um cliente ou de um período. One page; +list_iter+ walks every page.
1110
+ # Ler um reembolso.
1111
+ #
1112
+ # Devolve um reembolso pelo ID, com o pedido de onde veio (order_id), o
1113
+ # client_reference_id desse pedido e o status: requested e pending esperam a
1114
+ # Cielo, succeeded devolveu o dinheiro.
1115
+ #
1116
+ # Autenticação: chave de API da organização em Authorization: Bearer
1117
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1118
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1119
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1120
+ #
1121
+ # @return [Refund]
1122
+ def get(refund, api_key: nil)
1123
+ data = @client.request("GET", "/api/v1/refunds/#{Perata.segment(refund)}", api_key: api_key)
1124
+ Refund.from_hash(data)
1125
+ end
1126
+
1127
+ # Listar reembolsos. One page; +list_iter+ walks every page.
1128
+ #
1129
+ # Devolve uma página dos reembolsos. Filtre por pagamento (payment_id),
1130
+ # status, cliente, período ou metadados do reembolso.
1131
+ #
1132
+ # Autenticação: chave de API da organização em Authorization: Bearer
1133
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1134
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1135
+ # Respostas em JSON no envelope data; erros com error, message e fields.
689
1136
  #
690
1137
  # @return [Page<Refund>]
691
- def list(page: nil, limit: nil, payment_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil)
692
- query = { "page" => page, "limit" => limit, "payment_id" => payment_id, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting }
1138
+ def list(page: nil, limit: nil, payment_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil)
1139
+ query = { "page" => page, "limit" => limit, "payment_id" => payment_id, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting, "metadata" => metadata }
693
1140
  data = @client.request("GET", "/api/v1/refunds", query: query, api_key: api_key)
694
1141
  Page.from_hash(data) { |item| Refund.from_hash(item) }
695
1142
  end
@@ -697,21 +1144,54 @@ module Perata
697
1144
  # Walks every page of refunds:list from +page+, item by item.
698
1145
  #
699
1146
  # @return [Enumerator<Refund>]
700
- def list_iter(page: nil, limit: nil, payment_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil, &block)
1147
+ def list_iter(page: nil, limit: nil, payment_id: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil, &block)
701
1148
  items = Page.iterate(page) do |at|
702
- list(page: at, limit: limit, payment_id: payment_id, status: status, customer_id: customer_id, external_customer_id: external_customer_id, created_after: created_after, created_before: created_before, sorting: sorting, api_key: api_key)
1149
+ list(page: at, limit: limit, payment_id: payment_id, status: status, customer_id: customer_id, external_customer_id: external_customer_id, created_after: created_after, created_before: created_before, sorting: sorting, metadata: metadata, api_key: api_key)
703
1150
  end
704
1151
  block ? items.each(&block) : items
705
1152
  end
706
1153
  end
707
1154
 
1155
+ # The API's showcase.
1156
+ class ShowcaseService
1157
+ def initialize(client)
1158
+ @client = client
1159
+ end
1160
+
1161
+ # Ler o showcase da chave.
1162
+ #
1163
+ # Devolve o showcase em que a chave foi criada: o ID (o showcase_id dos
1164
+ # objetos e dos eventos), o nome, se é o principal da organização e se tem
1165
+ # logo. Serve para o seu sistema, ou um assistente, saber onde está. Um
1166
+ # showcase se abre e se muda no painel, nunca por esta API.
1167
+ #
1168
+ # Autenticação: chave de API da organização em Authorization: Bearer
1169
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1170
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1171
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1172
+ #
1173
+ # @return [Showcase]
1174
+ def get(api_key: nil)
1175
+ data = @client.request("GET", "/api/v1/showcase", api_key: api_key)
1176
+ Showcase.from_hash(data)
1177
+ end
1178
+ end
1179
+
708
1180
  # The API's subscriptions.
709
1181
  class SubscriptionsService
710
1182
  def initialize(client)
711
1183
  @client = client
712
1184
  end
713
1185
 
714
- # Cancelar uma assinatura, por padrão no fim do período.
1186
+ # Cancelar uma assinatura.
1187
+ #
1188
+ # Cancela uma assinatura. Por padrão o cancelamento vale no fim do período
1189
+ # já pago.
1190
+ #
1191
+ # Autenticação: chave de API da organização em Authorization: Bearer
1192
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1193
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1194
+ # Respostas em JSON no envelope data; erros com error, message e fields.
715
1195
  #
716
1196
  # @param params [SubscriptionsCancelParams, Hash]
717
1197
  # @return [Subscription]
@@ -722,17 +1202,32 @@ module Perata
722
1202
 
723
1203
  # Ler uma assinatura.
724
1204
  #
1205
+ # Devolve uma assinatura pelo ID.
1206
+ #
1207
+ # Autenticação: chave de API da organização em Authorization: Bearer
1208
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1209
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1210
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1211
+ #
725
1212
  # @return [Subscription]
726
1213
  def get(subscription, api_key: nil)
727
1214
  data = @client.request("GET", "/api/v1/subscriptions/#{Perata.segment(subscription)}", api_key: api_key)
728
1215
  Subscription.from_hash(data)
729
1216
  end
730
1217
 
731
- # Listar assinaturas, opcionalmente de um cliente (customer_id ou external_customer_id), de um status, de um período ou de metadados. One page; +list_iter+ walks every page.
1218
+ # Listar assinaturas. One page; +list_iter+ walks every page.
1219
+ #
1220
+ # Devolve uma página das assinaturas. Filtre por cliente (customer_id ou
1221
+ # external_customer_id), status, período ou metadados.
1222
+ #
1223
+ # Autenticação: chave de API da organização em Authorization: Bearer
1224
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1225
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1226
+ # Respostas em JSON no envelope data; erros com error, message e fields.
732
1227
  #
733
1228
  # @return [Page<Subscription>]
734
- def list(page: nil, limit: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil)
735
- query = { "page" => page, "limit" => limit, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting }
1229
+ def list(page: nil, limit: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil)
1230
+ query = { "page" => page, "limit" => limit, "status" => status, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "created_after" => created_after, "created_before" => created_before, "sorting" => sorting, "metadata" => metadata }
736
1231
  data = @client.request("GET", "/api/v1/subscriptions", query: query, api_key: api_key)
737
1232
  Page.from_hash(data) { |item| Subscription.from_hash(item) }
738
1233
  end
@@ -740,14 +1235,23 @@ module Perata
740
1235
  # Walks every page of subscriptions:list from +page+, item by item.
741
1236
  #
742
1237
  # @return [Enumerator<Subscription>]
743
- def list_iter(page: nil, limit: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, api_key: nil, &block)
1238
+ def list_iter(page: nil, limit: nil, status: nil, customer_id: nil, external_customer_id: nil, created_after: nil, created_before: nil, sorting: nil, metadata: nil, api_key: nil, &block)
744
1239
  items = Page.iterate(page) do |at|
745
- list(page: at, limit: limit, status: status, customer_id: customer_id, external_customer_id: external_customer_id, created_after: created_after, created_before: created_before, sorting: sorting, api_key: api_key)
1240
+ list(page: at, limit: limit, status: status, customer_id: customer_id, external_customer_id: external_customer_id, created_after: created_after, created_before: created_before, sorting: sorting, metadata: metadata, api_key: api_key)
746
1241
  end
747
1242
  block ? items.each(&block) : items
748
1243
  end
749
1244
 
750
- # Reativar uma assinatura suspensa, que volta a ser cobrada (a cobrança do ciclo em aberto recomeça), ou retomar uma pausada; qualquer outra recebe 409.
1245
+ # Reativar uma assinatura.
1246
+ #
1247
+ # Reativa uma assinatura suspensa, que volta a ser cobrada (a cobrança do
1248
+ # ciclo em aberto recomeça), ou retoma uma pausada. Qualquer outra
1249
+ # assinatura recebe 409.
1250
+ #
1251
+ # Autenticação: chave de API da organização em Authorization: Bearer
1252
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1253
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1254
+ # Respostas em JSON no envelope data; erros com error, message e fields.
751
1255
  #
752
1256
  # @return [Subscription]
753
1257
  def resume(subscription, idempotency_key: nil, api_key: nil)
@@ -755,7 +1259,15 @@ module Perata
755
1259
  Subscription.from_hash(data)
756
1260
  end
757
1261
 
758
- # Trocar o plano de uma assinatura: outro preço e, se quiser, outra quantidade, com a forma de ratear a diferença (proration_behavior).
1262
+ # Trocar o plano de uma assinatura.
1263
+ #
1264
+ # Troca o plano de uma assinatura: outro preço e, se quiser, outra
1265
+ # quantidade. O proration_behavior diz como ratear a diferença.
1266
+ #
1267
+ # Autenticação: chave de API da organização em Authorization: Bearer
1268
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1269
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1270
+ # Respostas em JSON no envelope data; erros com error, message e fields.
759
1271
  #
760
1272
  # @param params [SubscriptionsUpdateParams, Hash]
761
1273
  # @return [Subscription]
@@ -773,6 +1285,26 @@ module Perata
773
1285
 
774
1286
  # Ingerir lote atômico de eventos de uso. Autentica com a credencial de uma fonte de ingestão (pus_test_… ou pus_live_…), não com a chave de API da organização.
775
1287
  #
1288
+ # Autorização: Bearer é o único formato de credencial suportado. As
1289
+ # credenciais são assinadas pela Peráta, expiram em 30 dias e são
1290
+ # verificadas em relação ao estado da fonte, associação atual do emissor e
1291
+ # permissões nativas. Organização, merchant e ambiente (teste, pus_test_…,
1292
+ # ou produção, pus_live_…) são derivados da fonte autenticada; o payload
1293
+ # JSON não pode sobrescrevê-los, e uma credencial de um ambiente nunca
1294
+ # escreve no outro. Em produção, a fonte só existe para uma organização que
1295
+ # a equipe da Peráta liberou. 1 a 100 eventos, no máximo 65536 bytes.
1296
+ # Contagens são strings decimais de inteiros, de 0 a 1000000000000, com pelo
1297
+ # menos um token por evento; a entrada exclui cache. Ocorrência RFC3339 em
1298
+ # segundos inteiros, com no máximo 90 dias atrás e até cinco minutos à
1299
+ # frente. Escopo/fonte/external_event_id identificam um registro; repetições
1300
+ # exatas contam como replay e conteúdo conflitante retorna 409. Todos os
1301
+ # novos eventos e emissões da outbox são confirmados ou revertidos juntos.
1302
+ # Rotação mantém a identidade da fonte e replay; credenciais revogadas ou
1303
+ # expiradas não podem ser reutilizadas. O sucesso vem no envelope data; todo
1304
+ # erro é o documento de erro da API, o mesmo das demais operações de /api/v1
1305
+ # (error, message e fields), com record, a posição do evento recusado,
1306
+ # quando há. Sem cobrança ou faturamento automático.
1307
+ #
776
1308
  # @param params [UsageIngestParams, Hash]
777
1309
  # @return [UsageIngestReceipt]
778
1310
  def ingest(params, api_key: nil)
@@ -787,7 +1319,15 @@ module Perata
787
1319
  @client = client
788
1320
  end
789
1321
 
790
- # Criar um endpoint de webhook; o segredo que assina as mensagens vem só nesta resposta.
1322
+ # Criar um endpoint de webhook.
1323
+ #
1324
+ # Cria um endpoint de webhook. O segredo que assina as mensagens vem só
1325
+ # nesta resposta; guarde-o.
1326
+ #
1327
+ # Autenticação: chave de API da organização em Authorization: Bearer
1328
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1329
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1330
+ # Respostas em JSON no envelope data; erros com error, message e fields.
791
1331
  #
792
1332
  # @param params [WebhooksCreateEndpointParams, Hash]
793
1333
  # @return [WebhookEndpointCreated]
@@ -796,7 +1336,15 @@ module Perata
796
1336
  WebhookEndpointCreated.from_hash(data)
797
1337
  end
798
1338
 
799
- # Excluir um endpoint de webhook; as entregas que ainda esperavam por ele falham. The API answers 204, so there is nothing to return.
1339
+ # Excluir um endpoint de webhook. The API answers 204, so there is nothing to return.
1340
+ #
1341
+ # Exclui um endpoint de webhook. As entregas que ainda esperavam por ele
1342
+ # falham.
1343
+ #
1344
+ # Autenticação: chave de API da organização em Authorization: Bearer
1345
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1346
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1347
+ # Respostas em JSON no envelope data; erros com error, message e fields.
800
1348
  #
801
1349
  # @return [nil]
802
1350
  def delete_endpoint(endpoint, idempotency_key: nil, api_key: nil)
@@ -806,13 +1354,28 @@ module Perata
806
1354
 
807
1355
  # Ler um endpoint de webhook.
808
1356
  #
1357
+ # Devolve um endpoint de webhook pelo ID.
1358
+ #
1359
+ # Autenticação: chave de API da organização em Authorization: Bearer
1360
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1361
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1362
+ # Respostas em JSON no envelope data; erros com error, message e fields.
1363
+ #
809
1364
  # @return [WebhookEndpoint]
810
1365
  def get_endpoint(endpoint, api_key: nil)
811
1366
  data = @client.request("GET", "/api/v1/webhooks/endpoints/#{Perata.segment(endpoint)}", api_key: api_key)
812
1367
  WebhookEndpoint.from_hash(data)
813
1368
  end
814
1369
 
815
- # Listar as últimas 100 entregas de eventos aos endpoints, opcionalmente de um endpoint (endpoint_id) ou de uma situação (status). One page; +list_deliveries_iter+ walks every page.
1370
+ # Listar entregas de webhook. One page; +list_deliveries_iter+ walks every page.
1371
+ #
1372
+ # Devolve as últimas 100 entregas de eventos aos endpoints. Com endpoint_id,
1373
+ # só as de um endpoint; com status, só as de uma situação.
1374
+ #
1375
+ # Autenticação: chave de API da organização em Authorization: Bearer
1376
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1377
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1378
+ # Respostas em JSON no envelope data; erros com error, message e fields.
816
1379
  #
817
1380
  # @return [Page<WebhookDelivery>]
818
1381
  def list_deliveries(page: nil, limit: nil, endpoint_id: nil, status: nil, api_key: nil)
@@ -831,7 +1394,14 @@ module Perata
831
1394
  block ? items.each(&block) : items
832
1395
  end
833
1396
 
834
- # Listar os endpoints de webhook do lojista. One page; +list_endpoints_iter+ walks every page.
1397
+ # Listar endpoints de webhook. One page; +list_endpoints_iter+ walks every page.
1398
+ #
1399
+ # Devolve uma página dos endpoints de webhook da organização.
1400
+ #
1401
+ # Autenticação: chave de API da organização em Authorization: Bearer
1402
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1403
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1404
+ # Respostas em JSON no envelope data; erros com error, message e fields.
835
1405
  #
836
1406
  # @return [Page<WebhookEndpoint>]
837
1407
  def list_endpoints(page: nil, limit: nil, api_key: nil)
@@ -850,7 +1420,15 @@ module Perata
850
1420
  block ? items.each(&block) : items
851
1421
  end
852
1422
 
853
- # Atualizar o endereço, o formato, os eventos ou a descrição de um endpoint, ou ligar e desligar o envio (enabled); o segredo não muda.
1423
+ # Atualizar um endpoint de webhook.
1424
+ #
1425
+ # Muda o endereço, o formato, os eventos ou a descrição de um endpoint, ou
1426
+ # liga e desliga o envio (enabled). O segredo não muda.
1427
+ #
1428
+ # Autenticação: chave de API da organização em Authorization: Bearer
1429
+ # (prk_test_… ou prk_live_…). Organização, showcase e ambiente vêm da chave,
1430
+ # nunca da requisição: a chave criada num showcase só alcança o que é dele.
1431
+ # Respostas em JSON no envelope data; erros com error, message e fields.
854
1432
  #
855
1433
  # @param params [WebhooksUpdateEndpointParams, Hash]
856
1434
  # @return [WebhookEndpoint]