tronzap-sdk 1.0.0 → 1.2.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.
Files changed (39) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +70 -0
  3. data/README.es.md +145 -15
  4. data/README.md +143 -14
  5. data/README.pt-br.md +145 -14
  6. data/README.ru.md +141 -13
  7. data/lib/tronzap/client.rb +157 -6
  8. data/lib/tronzap/coerce.rb +8 -0
  9. data/lib/tronzap/errors.rb +74 -17
  10. data/lib/tronzap/models/bulk_rejected_row.rb +30 -0
  11. data/lib/tronzap/models/direct_recharge_rate.rb +1 -1
  12. data/lib/tronzap/models/energy_rate.rb +12 -8
  13. data/lib/tronzap/models/enums.rb +15 -1
  14. data/lib/tronzap/models/subscription_params.rb +28 -0
  15. data/lib/tronzap/requests/aml_check.rb +17 -6
  16. data/lib/tronzap/requests/bulk_calculate.rb +40 -0
  17. data/lib/tronzap/requests/bulk_create.rb +52 -0
  18. data/lib/tronzap/requests/bulk_history.rb +28 -0
  19. data/lib/tronzap/requests/bulk_item.rb +29 -0
  20. data/lib/tronzap/requests/bulk_lookup.rb +48 -0
  21. data/lib/tronzap/requests/bulk_report.rb +55 -0
  22. data/lib/tronzap/requests/start_subscription.rb +54 -0
  23. data/lib/tronzap/requests/subscription_history.rb +35 -0
  24. data/lib/tronzap/requests/subscription_lookup.rb +48 -0
  25. data/lib/tronzap/requests/validation.rb +8 -0
  26. data/lib/tronzap/response_decoder.rb +53 -15
  27. data/lib/tronzap/responses/aml_check.rb +1 -1
  28. data/lib/tronzap/responses/bulk_calculation.rb +44 -0
  29. data/lib/tronzap/responses/bulk_history.rb +28 -0
  30. data/lib/tronzap/responses/bulk_order.rb +87 -0
  31. data/lib/tronzap/responses/calculation.rb +5 -3
  32. data/lib/tronzap/responses/energy_estimate.rb +6 -4
  33. data/lib/tronzap/responses/service_rates.rb +3 -2
  34. data/lib/tronzap/responses/subscription.rb +73 -0
  35. data/lib/tronzap/responses/subscription_history.rb +28 -0
  36. data/lib/tronzap/responses/subscription_plan.rb +52 -0
  37. data/lib/tronzap/version.rb +1 -1
  38. data/lib/tronzap.rb +17 -0
  39. metadata +18 -1
data/README.pt-br.md CHANGED
@@ -57,7 +57,7 @@ begin
57
57
 
58
58
  transaction = client.create_energy_transaction(
59
59
  address: "TRecipientAddress",
60
- energy: estimate.energy,
60
+ energy: estimate.amount,
61
61
  duration: 1,
62
62
  external_id: "order-42",
63
63
  activate_address: true
@@ -184,6 +184,17 @@ outras bibliotecas HTTP precisam ser traduzidos pelo adaptador, como acima.
184
184
  | `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Iniciar uma verificação AML |
185
185
  | `check_aml_status(id)` | `/v1/aml-checks/check` | Status e resultado de uma verificação AML |
186
186
  | `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | Histórico paginado de verificações AML |
187
+ | `get_subscriptions` | `/v1/subscriptions` | Planos de assinatura e preços |
188
+ | `start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0, external_id: nil, activate_address: false)` | `/v1/subscription/start` | Assinar um plano para um endereço |
189
+ | `check_subscription(id: nil, external_id: nil)` | `/v1/subscription/check` | Status de uma assinatura, por id ou id externo |
190
+ | `stop_subscription(id: nil, external_id: nil)` | `/v1/subscription/stop` | Parar uma assinatura |
191
+ | `get_subscription_history(page: 1, per_page: 10, status: nil)` | `/v1/subscriptions/history` | Histórico paginado de assinaturas |
192
+ | `bulk_calculate(items:, duration: 1)` | `/v1/bulk/calculate` | Validar e calcular as linhas de um pedido de energia em massa |
193
+ | `bulk_create(id:, external_id: nil, force: false, max_price_increase: nil, webhook_url: nil)` | `/v1/bulk/create` | Iniciar um pedido em massa a partir de um cálculo |
194
+ | `bulk_check(id: nil, external_id: nil)` | `/v1/bulk/check` | Status e progresso de um pedido em massa |
195
+ | `get_bulk_history(page: 1, per_page: 10)` | `/v1/bulk/history` | Histórico paginado de pedidos em massa |
196
+ | `bulk_report(id: nil, external_id: nil, status: nil)` | `/v1/bulk/report` | Relatório por endereço de um pedido em massa, em CSV |
197
+ | `verify_webhook_signature(body, signature)` | — | Verificar o `X-Signature` do webhook de um pedido em massa |
187
198
 
188
199
  Os métodos com parâmetros aceitam argumentos nomeados ou um objeto de requisição de
189
200
  `Tronzap::Requests`, então uma requisição pode ser montada, validada e repassada
@@ -196,11 +207,13 @@ client.create_energy_transaction(request)
196
207
 
197
208
  Uma requisição é validada ao ser criada, então uma requisição inválida lança
198
209
  `ArgumentError` e nunca chega à API. As quantidades devem ser valores `Integer`
199
- positivos. Os padrões coincidem com a API: `duration` é 1 hora e o histórico AML
200
- começa na página 1 com 10 itens.
210
+ positivos. Os padrões coincidem com a API: `duration` é 1 hora e os históricos AML
211
+ e de assinaturas começam na página 1 com 10 itens. A exceção é
212
+ `start_subscription`, em que `duration_days` e `transactions_limit` valem 0 por
213
+ padrão, o que significa sem limite.
201
214
 
202
215
  Os resultados são objetos `Data` imutáveis em `Tronzap::Responses` e
203
- `Tronzap::Models`, não hashes: `transaction.status`, `estimate.energy`. As coleções
216
+ `Tronzap::Models`, não hashes: `transaction.status`, `estimate.amount`. As coleções
204
217
  são congeladas e nunca são `nil`, e os valores que a API pode omitir são `nil`.
205
218
 
206
219
  ### Comprar recursos
@@ -230,9 +243,10 @@ client.create_resource_bundle_transaction(
230
243
  client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
231
244
  ```
232
245
 
233
- O preço da energia é por unidade e o da largura de banda é por 1000 unidades: em
234
- `get_services`, `EnergyRate#price` × 65000 é o custo de 65000 de energia, enquanto
235
- 345 de largura de banda com um `BandwidthRate#price` de 1 custam 0.345.
246
+ Em `get_services`, os preços da energia e da largura de banda são ambos por 1000
247
+ unidades, então uma compra custa `price × amount / 1000`: 65000 de energia com um
248
+ `EnergyRate#price` de 0.03 custam 1.95, e 345 de largura de banda com um
249
+ `BandwidthRate#price` de 1 custam 0.345.
236
250
 
237
251
  Atualmente a API informa um pacote de recursos com `service` igual a `:energy`, e
238
252
  não `:resource_bundle`. Consulte `params.amounts` para saber quais recursos uma
@@ -265,9 +279,101 @@ if result.status == :completed
265
279
  end
266
280
  ```
267
281
 
282
+ Em uma verificação por hash, `address` é o endereço do destinatário da
283
+ transação, onde os fundos foram recebidos, e `direction` indica de que lado você
284
+ está: `:deposit` se os fundos chegaram ao seu endereço (`address` é o seu
285
+ endereço), `:withdrawal` se foi você quem enviou (`address` é o endereço do
286
+ destinatário externo). O risco é calculado para a contraparte: o remetente em um
287
+ deposit, o destinatário em um withdrawal. Sem `direction`, o SDK envia
288
+ `deposit`.
289
+
268
290
  `risk_score` é `nil` até a verificação terminar. Uma verificação concluída pode
269
291
  ter pontuação 0, o que não é o mesmo que ainda não ter pontuação.
270
292
 
293
+ ### Assinaturas
294
+
295
+ Uma assinatura mantém um endereço abastecido de energia para cada transação até
296
+ ser parada ou esgotar seus dias ou transações. Escolha um plano de
297
+ `get_subscriptions` e passe o seu `subscription_id`, como `"unlimited_energy"`, não
298
+ o `id` numérico. Iniciar uma assinatura cobra o preço inicial do plano.
299
+
300
+ ```ruby
301
+ client.get_subscriptions.each do |plan|
302
+ puts "#{plan.subscription_id} #{plan.initial_price.to_s("F")} #{plan.price.to_s("F")}"
303
+ end
304
+
305
+ subscription = client.start_subscription(
306
+ subscription_id: "unlimited_energy",
307
+ address: "TRecipientAddress",
308
+ duration_days: 30, # 0 para não limitar o tempo
309
+ transactions_limit: 0, # 0 para não limitar
310
+ external_id: "subscription-42"
311
+ )
312
+
313
+ subscription = client.check_subscription(external_id: "subscription-42")
314
+
315
+ subscription = client.stop_subscription(id: subscription.id)
316
+
317
+ history = client.get_subscription_history(status: :active)
318
+ ```
319
+
320
+ Iniciar, consultar e parar retornam a assinatura com seus `params`; o histórico
321
+ retorna em vez disso os contadores de uso `transactions_used`, `energy_used` e
322
+ `total_price`, e deixa `params` como `nil`. Os status de uma assinatura estão em
323
+ `Tronzap::Models::SUBSCRIPTION_STATUSES`. Uma assinatura com limite de transações
324
+ não pode ser parada (`CANNOT_STOP_SUBSCRIPTION`).
325
+
326
+ ### Pedidos em massa
327
+
328
+ Compre energia para até 10 000 endereços em um único pedido. `bulk_calculate`
329
+ valida e calcula as linhas e retorna um cálculo válido por 10 minutos; nada é
330
+ cobrado. Linhas inválidas não fazem a requisição falhar: elas voltam em `rejected`
331
+ com o número da linha. `bulk_create` inicia o pedido; cada endereço é cobrado
332
+ quando é processado, e endereços não ativados são pulados sem cobrança.
333
+
334
+ Se o preço mudou desde o cálculo, `bulk_create` não inicia o pedido e lança
335
+ `Tronzap::BulkPriceChangedError` (código `BULK_PRICE_CHANGED`). Seu `calculation` é
336
+ o novo cálculo: confirme o novo total e inicie-o pelo `id`.
337
+
338
+ ```ruby
339
+ calculation = client.bulk_calculate(items: [
340
+ { address: "TRecipientAddress1", amount: 65000 },
341
+ { address: "TRecipientAddress2", amount: 131000 }
342
+ ])
343
+ calculation.rejected.each { |row| puts "row #{row.row}: #{row.reason}" }
344
+
345
+ begin
346
+ order = client.bulk_create(id: calculation.id, external_id: "order-42",
347
+ webhook_url: "https://example.com/tronzap/bulk")
348
+ rescue Tronzap::BulkPriceChangedError => e
349
+ new_calculation = e.calculation # confirme o novo total e inicie-o
350
+ order = client.bulk_create(id: new_calculation.id, external_id: "order-42")
351
+ end
352
+
353
+ order = client.bulk_check(external_id: "order-42") # consulte até :completed, :partial ou :failed
354
+ csv = client.bulk_report(id: order.id) # row,address,amount,status,reason,charged,transaction_id
355
+ history = client.get_bulk_history(page: 1, per_page: 10)
356
+ ```
357
+
358
+ As linhas são `Tronzap::Requests::BulkItem` ou hashes com `address` e `amount`. Um
359
+ pedido passa pelos status de `Tronzap::Models::BULK_STATUSES`; `:completed`,
360
+ `:partial` e `:failed` são finais. `status:` de `bulk_report` aceita um de
361
+ `Tronzap::Models::BULK_ROW_STATUSES`.
362
+
363
+ Com `webhook_url`, a API envia um `POST` quando o pedido chega a um status final.
364
+ Verifique o cabeçalho `X-Signature` com o corpo bruto antes de confiar nele, por
365
+ exemplo no Sinatra:
366
+
367
+ ```ruby
368
+ post "/tronzap/bulk" do
369
+ body = request.body.read
370
+ halt 401 unless client.verify_webhook_signature(body, request.env["HTTP_X_SIGNATURE"])
371
+
372
+ order = JSON.parse(body) # {"id":"01kb2m5x9qj4v8n3c7d6e5f4g3","external_id":"order-42","status":"partial"}
373
+ 200
374
+ end
375
+ ```
376
+
271
377
  ## Tratamento de erros
272
378
 
273
379
  Toda falha de uma chamada à API é um `Tronzap::Error`. Capture uma subclasse para
@@ -277,7 +383,7 @@ tratar um tipo específico de falha:
277
383
  Tronzap::Error
278
384
  ├── Tronzap::ApiError — a API respondeu com um código diferente de zero
279
385
  ├── Tronzap::HttpError — resposta não 2xx sem payload da API
280
- │ ├── Tronzap::RateLimitError — HTTP 429
386
+ │ ├── Tronzap::RateLimitError — HTTP 429 sem resposta da API
281
387
  │ ├── Tronzap::UnauthorizedError — HTTP 401 ou 403
282
388
  │ └── Tronzap::ServerError — HTTP 5xx
283
389
  ├── Tronzap::InvalidResponseError — resposta 2xx que o SDK não conseguiu ler
@@ -290,8 +396,7 @@ Tronzap::Error
290
396
  `ApiError`, `HttpError` e `InvalidResponseError` trazem o status HTTP (`status`) e
291
397
  o corpo bruto da resposta (`response_body`). `ApiError` também traz o código de
292
398
  erro da API (`code`), a chave do erro (`error_key`) e o ID da requisição
293
- (`request_id`). `RateLimitError#retry_after` contém o intervalo de `Retry-After`
294
- em segundos quando a API o envia.
399
+ (`request_id`).
295
400
 
296
401
  Argumentos inválidos não são falhas da API: eles lançam `ArgumentError` antes de
297
402
  qualquer envio.
@@ -312,8 +417,8 @@ rescue Tronzap::ApiError => e
312
417
  else
313
418
  warn "api error #{e.code}: #{e.message} (request #{e.request_id || "-"})"
314
419
  end
315
- rescue Tronzap::RateLimitError => e
316
- # Aguarde e tente novamente, após e.retry_after segundos se a API o enviou.
420
+ rescue Tronzap::RateLimitError
421
+ # HTTP 429 sem resposta da API, p. ex. de um proxy: aguarde e tente novamente.
317
422
  rescue Tronzap::UnauthorizedError
318
423
  # Token ou assinatura incorretos.
319
424
  rescue Tronzap::TimeoutError, Tronzap::ServerError
@@ -331,6 +436,24 @@ com status 2xx e outras com 4xx ou 5xx, então um payload legível com código
331
436
  diferente de zero é sempre informado como `Tronzap::ApiError`, nunca como
332
437
  `Tronzap::HttpError`.
333
438
 
439
+ `ApiError#result` é o `result` que a API enviou com o erro, como JSON analisado,
440
+ ou `nil`. O SDK lê os dados de `BULK_PRICE_CHANGED` e `BULK_NO_VALID_ITEMS` em
441
+ `Tronzap::BulkPriceChangedError#calculation` e
442
+ `Tronzap::BulkNoValidItemsError#rejected`; os dois são `ApiError`. Um limite de
443
+ requisições informado pela API é um `ApiError` com `RATE_LIMITED`;
444
+ `Tronzap::RateLimitError` é apenas um HTTP 429 sem resposta da API, p. ex. de um
445
+ proxy. `ApiError` e `HttpError` trazem `retry_after`, os segundos de espera do
446
+ cabeçalho `Retry-After` ou do campo `retry_after`, ou `nil` quando o servidor não
447
+ informou quanto esperar:
448
+
449
+ ```ruby
450
+ rescue Tronzap::ApiError => e
451
+ raise unless e.code == Tronzap::ErrorCode::RATE_LIMITED
452
+
453
+ sleep(e.retry_after || 60)
454
+ end
455
+ ```
456
+
334
457
  ### Códigos de erro da API
335
458
 
336
459
  | Código | Constante | Descrição |
@@ -339,16 +462,24 @@ diferente de zero é sempre informado como `Tronzap::ApiError`, nunca como
339
462
  | 2 | `INVALID_SERVICE_OR_PARAMS` | Serviço ou parâmetros inválidos |
340
463
  | 5 | `WALLET_NOT_FOUND` | Carteira interna não encontrada. Contate o suporte. |
341
464
  | 6 | `INSUFFICIENT_FUNDS` | Saldo insuficiente |
342
- | 10 | `INVALID_TRON_ADDRESS` | Endereço TRON inválido |
465
+ | 10 | `INVALID_TRON_ADDRESS` | Endereço TRON inválido, ou o endereço já tem uma assinatura ativa |
343
466
  | 11 | `INVALID_ENERGY_AMOUNT` | Quantidade de energia inválida |
344
467
  | 12 | `INVALID_DURATION` | Duração inválida |
345
468
  | 20 | `TRANSACTION_NOT_FOUND` | Transação/assinatura não encontrada |
346
- | 21 | `CANNOT_STOP_SUBSCRIPTION` | Não é possível interromper a assinatura |
469
+ | 21 | `CANNOT_STOP_SUBSCRIPTION` | Não é possível interromper a assinatura, p. ex. ela tem limite de transações |
347
470
  | 24 | `ADDRESS_NOT_ACTIVATED` | Endereço não ativado |
348
471
  | 25 | `ADDRESS_ALREADY_ACTIVATED` | Endereço já ativado |
349
472
  | 30 | `AML_CHECK_NOT_FOUND` | Verificação AML não encontrada |
350
473
  | 35 | `SERVICE_NOT_AVAILABLE` | Serviço indisponível |
351
474
  | 50 | `INVALID_BANDWIDTH_AMOUNT` | Quantidade de largura de banda inválida |
475
+ | 90 | `BULK_NOT_FOUND` | Pedido em massa não encontrado |
476
+ | 91 | `BULK_EXPIRED` | O cálculo expirou, calcule novamente |
477
+ | 92 | `BULK_PRICE_CHANGED` | O preço mudou; o novo cálculo está em `BulkPriceChangedError#calculation` |
478
+ | 93 | `BULK_TOO_MANY_ITEMS` | Mais de 10 000 linhas |
479
+ | 94 | `BULK_NO_VALID_ITEMS` | Nenhuma linha válida; elas estão em `BulkNoValidItemsError#rejected` |
480
+ | 95 | `BULK_RESOURCE_NOT_SUPPORTED` | Só energia pode ser pedida em massa |
481
+ | 96 | `PAYLOAD_TOO_LARGE` | Corpo da requisição grande demais (HTTP 413) |
482
+ | 429 | `RATE_LIMITED` | Requisições demais; aguarde `retry_after` se informado |
352
483
  | 500 | `INTERNAL_SERVER_ERROR` | Erro interno do servidor: contate o suporte |
353
484
 
354
485
  As constantes estão em `Tronzap::ErrorCode`. Um código que esta versão do SDK não
data/README.ru.md CHANGED
@@ -57,7 +57,7 @@ begin
57
57
 
58
58
  transaction = client.create_energy_transaction(
59
59
  address: "TRecipientAddress",
60
- energy: estimate.energy,
60
+ energy: estimate.amount,
61
61
  duration: 1,
62
62
  external_id: "order-42",
63
63
  activate_address: true
@@ -185,6 +185,17 @@ HTTP-библиотек адаптер должен преобразовать
185
185
  | `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Запустить AML-проверку |
186
186
  | `check_aml_status(id)` | `/v1/aml-checks/check` | Статус и результат AML-проверки |
187
187
  | `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | История AML-проверок с пагинацией |
188
+ | `get_subscriptions` | `/v1/subscriptions` | Планы подписок и цены |
189
+ | `start_subscription(subscription_id:, address:, duration_days: 0, transactions_limit: 0, external_id: nil, activate_address: false)` | `/v1/subscription/start` | Подписать адрес на план |
190
+ | `check_subscription(id: nil, external_id: nil)` | `/v1/subscription/check` | Статус подписки по id или внешнему id |
191
+ | `stop_subscription(id: nil, external_id: nil)` | `/v1/subscription/stop` | Остановить подписку |
192
+ | `get_subscription_history(page: 1, per_page: 10, status: nil)` | `/v1/subscriptions/history` | История подписок с пагинацией |
193
+ | `bulk_calculate(items:, duration: 1)` | `/v1/bulk/calculate` | Проверка и расчёт строк массового заказа энергии |
194
+ | `bulk_create(id:, external_id: nil, force: false, max_price_increase: nil, webhook_url: nil)` | `/v1/bulk/create` | Запуск массового заказа по расчёту |
195
+ | `bulk_check(id: nil, external_id: nil)` | `/v1/bulk/check` | Статус и прогресс массового заказа |
196
+ | `get_bulk_history(page: 1, per_page: 10)` | `/v1/bulk/history` | История массовых заказов с пагинацией |
197
+ | `bulk_report(id: nil, external_id: nil, status: nil)` | `/v1/bulk/report` | Отчёт массового заказа по адресам в CSV |
198
+ | `verify_webhook_signature(body, signature)` | — | Проверка `X-Signature` вебхука массового заказа |
188
199
 
189
200
  Методы с параметрами принимают либо именованные аргументы, либо объект запроса из
190
201
  `Tronzap::Requests`, поэтому запрос можно создать, проверить и передать дальше до
@@ -198,10 +209,12 @@ client.create_energy_transaction(request)
198
209
  Запрос проверяется при создании, поэтому невалидный запрос вызывает
199
210
  `ArgumentError` и никогда не доходит до API. Количества должны быть
200
211
  положительными `Integer`. Значения по умолчанию совпадают с API: `duration` —
201
- 1 час, история AML начинается со страницы 1 по 10 элементов.
212
+ 1 час, история AML и подписок начинается со страницы 1 по 10 элементов.
213
+ Исключение — `start_subscription`: `duration_days` и `transactions_limit` по
214
+ умолчанию равны 0, что означает отсутствие ограничения.
202
215
 
203
216
  Результаты — неизменяемые объекты `Data` в `Tronzap::Responses` и
204
- `Tronzap::Models`, а не хеши: `transaction.status`, `estimate.energy`. Коллекции
217
+ `Tronzap::Models`, а не хеши: `transaction.status`, `estimate.amount`. Коллекции
205
218
  заморожены и никогда не бывают `nil`, а значения, которые API может не прислать,
206
219
  равны `nil`.
207
220
 
@@ -232,9 +245,9 @@ client.create_resource_bundle_transaction(
232
245
  client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
233
246
  ```
234
247
 
235
- Цена энергии указана за единицу, цена bandwidth — за 1000 единиц: в
236
- `get_services` `EnergyRate#price` × 65000 — это стоимость 65000 энергии, а 345
237
- bandwidth при `BandwidthRate#price`, равном 1, стоят 0.345.
248
+ В `get_services` цены энергии и bandwidth указаны за 1000 единиц, поэтому покупка
249
+ стоит `price × amount / 1000`: 65000 энергии при `EnergyRate#price`, равном 0.03,
250
+ стоят 1.95, а 345 bandwidth при `BandwidthRate#price`, равном 1, стоят 0.345.
238
251
 
239
252
  Сейчас API возвращает пакет ресурсов с `service`, равным `:energy`, а не
240
253
  `:resource_bundle`. Состав покупки смотрите в `params.amounts`.
@@ -266,9 +279,101 @@ if result.status == :completed
266
279
  end
267
280
  ```
268
281
 
282
+ Для проверки по hash `address` — это адрес получателя средств в транзакции, а
283
+ `direction` указывает, на какой стороне транзакции вы: `:deposit`, если средства
284
+ пришли на ваш адрес (`address` — ваш адрес), `:withdrawal`, если их отправили вы
285
+ (`address` — адрес внешнего получателя). Риск оценивается для контрагента: для
286
+ deposit — для отправителя, для withdrawal — для получателя. Без `direction` SDK
287
+ отправляет `deposit`.
288
+
269
289
  `risk_score` равен `nil`, пока проверка не завершится. У завершённой проверки score
270
290
  может быть равен 0, и это не то же самое, что отсутствие результата.
271
291
 
292
+ ### Подписки
293
+
294
+ Подписка обеспечивает адрес энергией для каждой транзакции, пока её не
295
+ остановят или не закончатся её дни или транзакции. Выберите план из
296
+ `get_subscriptions` и передайте его `subscription_id`, например
297
+ `"unlimited_energy"`, а не числовой `id`. Запуск подписки списывает начальную
298
+ цену плана.
299
+
300
+ ```ruby
301
+ client.get_subscriptions.each do |plan|
302
+ puts "#{plan.subscription_id} #{plan.initial_price.to_s("F")} #{plan.price.to_s("F")}"
303
+ end
304
+
305
+ subscription = client.start_subscription(
306
+ subscription_id: "unlimited_energy",
307
+ address: "TRecipientAddress",
308
+ duration_days: 30, # 0 — без ограничения по времени
309
+ transactions_limit: 0, # 0 — без ограничения
310
+ external_id: "subscription-42"
311
+ )
312
+
313
+ subscription = client.check_subscription(external_id: "subscription-42")
314
+
315
+ subscription = client.stop_subscription(id: subscription.id)
316
+
317
+ history = client.get_subscription_history(status: :active)
318
+ ```
319
+
320
+ Запуск, проверка и остановка возвращают подписку с её `params`, а история
321
+ вместо них — счётчики использования `transactions_used`, `energy_used` и
322
+ `total_price`, и `params` в ней равен `nil`. Статусы подписки перечислены в
323
+ `Tronzap::Models::SUBSCRIPTION_STATUSES`. Подписку с лимитом транзакций
324
+ остановить нельзя (`CANNOT_STOP_SUBSCRIPTION`).
325
+
326
+ ### Массовые заказы
327
+
328
+ Покупка энергии на 10 000 адресов одним заказом. `bulk_calculate` проверяет и
329
+ рассчитывает строки и возвращает расчёт, действительный 10 минут; ничего не
330
+ списывается. Некорректные строки не валят запрос: они возвращаются в `rejected` с
331
+ номером строки. `bulk_create` запускает заказ; каждый адрес списывается в момент
332
+ обработки, неактивированные адреса пропускаются без списания.
333
+
334
+ Если цена изменилась после расчёта, `bulk_create` не запускает заказ и вызывает
335
+ `Tronzap::BulkPriceChangedError` (код `BULK_PRICE_CHANGED`). Его `calculation` —
336
+ новый расчёт: подтвердите новую сумму и запустите его по `id`.
337
+
338
+ ```ruby
339
+ calculation = client.bulk_calculate(items: [
340
+ { address: "TRecipientAddress1", amount: 65000 },
341
+ { address: "TRecipientAddress2", amount: 131000 }
342
+ ])
343
+ calculation.rejected.each { |row| puts "row #{row.row}: #{row.reason}" }
344
+
345
+ begin
346
+ order = client.bulk_create(id: calculation.id, external_id: "order-42",
347
+ webhook_url: "https://example.com/tronzap/bulk")
348
+ rescue Tronzap::BulkPriceChangedError => e
349
+ new_calculation = e.calculation # подтвердите новую сумму и запустите его
350
+ order = client.bulk_create(id: new_calculation.id, external_id: "order-42")
351
+ end
352
+
353
+ order = client.bulk_check(external_id: "order-42") # опрашивайте до :completed, :partial или :failed
354
+ csv = client.bulk_report(id: order.id) # row,address,amount,status,reason,charged,transaction_id
355
+ history = client.get_bulk_history(page: 1, per_page: 10)
356
+ ```
357
+
358
+ Строки — это `Tronzap::Requests::BulkItem` или хеши с `address` и `amount`. Заказ
359
+ проходит статусы из `Tronzap::Models::BULK_STATUSES`; `:completed`, `:partial` и
360
+ `:failed` — финальные. `status:` у `bulk_report` принимает одно из
361
+ `Tronzap::Models::BULK_ROW_STATUSES`.
362
+
363
+ С `webhook_url` API отправляет на него один `POST`, когда заказ становится
364
+ финальным. Перед тем как доверять ему, проверьте заголовок `X-Signature` по сырому
365
+ телу, например в Sinatra:
366
+
367
+ ```ruby
368
+ post "/tronzap/bulk" do
369
+ body = request.body.read
370
+ halt 401 unless client.verify_webhook_signature(body, request.env["HTTP_X_SIGNATURE"])
371
+
372
+ order = JSON.parse(body) # {"id":"01kb2m5x9qj4v8n3c7d6e5f4g3","external_id":"order-42","status":"partial"}
373
+ 200
374
+ end
375
+ ```
376
+
272
377
  ## Обработка ошибок
273
378
 
274
379
  Любой сбой вызова API — исключение `Tronzap::Error`. Перехватывайте подкласс, чтобы
@@ -278,7 +383,7 @@ end
278
383
  Tronzap::Error
279
384
  ├── Tronzap::ApiError — API ответил ненулевым code
280
385
  ├── Tronzap::HttpError — ответ не 2xx без payload API
281
- │ ├── Tronzap::RateLimitError — HTTP 429
386
+ │ ├── Tronzap::RateLimitError — HTTP 429 без ответа API
282
387
  │ ├── Tronzap::UnauthorizedError — HTTP 401 или 403
283
388
  │ └── Tronzap::ServerError — HTTP 5xx
284
389
  ├── Tronzap::InvalidResponseError — ответ 2xx, который SDK не смог прочитать
@@ -291,8 +396,6 @@ Tronzap::Error
291
396
  `ApiError`, `HttpError` и `InvalidResponseError` содержат HTTP-статус
292
397
  (`status`) и сырое тело ответа (`response_body`). `ApiError` также содержит код
293
398
  ошибки API (`code`), ключ ошибки (`error_key`) и ID запроса (`request_id`).
294
- `RateLimitError#retry_after` хранит задержку из `Retry-After` в секундах, если API
295
- её прислал.
296
399
 
297
400
  Невалидные аргументы не являются сбоями API: они вызывают `ArgumentError` ещё до
298
401
  отправки.
@@ -313,8 +416,8 @@ rescue Tronzap::ApiError => e
313
416
  else
314
417
  warn "api error #{e.code}: #{e.message} (request #{e.request_id || "-"})"
315
418
  end
316
- rescue Tronzap::RateLimitError => e
317
- # Подождите и повторите, через e.retry_after секунд, если API его прислал.
419
+ rescue Tronzap::RateLimitError
420
+ # HTTP 429 без ответа API, например от прокси: подождите и повторите.
318
421
  rescue Tronzap::UnauthorizedError
319
422
  # Неверный токен или подпись.
320
423
  rescue Tronzap::TimeoutError, Tronzap::ServerError
@@ -331,6 +434,23 @@ end
331
434
  часть — с 4xx или 5xx, поэтому читаемый payload с ненулевым кодом всегда
332
435
  сообщается как `Tronzap::ApiError`, а не как `Tronzap::HttpError`.
333
436
 
437
+ `ApiError#result` — поле `result`, которое API вернул вместе с ошибкой, в виде
438
+ разобранного JSON, или `nil`. Данные `BULK_PRICE_CHANGED` и `BULK_NO_VALID_ITEMS`
439
+ SDK читает в `Tronzap::BulkPriceChangedError#calculation` и
440
+ `Tronzap::BulkNoValidItemsError#rejected`; обе ошибки — это `ApiError`. Лимит
441
+ запросов, о котором сообщает API, — это `ApiError` с `RATE_LIMITED`;
442
+ `Tronzap::RateLimitError` — только HTTP 429 без ответа API, например от прокси.
443
+ `ApiError` и `HttpError` содержат `retry_after` — сколько секунд ждать, из
444
+ заголовка `Retry-After` или поля `retry_after`, или `nil`, если сервер не сообщил:
445
+
446
+ ```ruby
447
+ rescue Tronzap::ApiError => e
448
+ raise unless e.code == Tronzap::ErrorCode::RATE_LIMITED
449
+
450
+ sleep(e.retry_after || 60)
451
+ end
452
+ ```
453
+
334
454
  ### Коды ошибок API
335
455
 
336
456
  | Код | Константа | Описание |
@@ -339,16 +459,24 @@ end
339
459
  | 2 | `INVALID_SERVICE_OR_PARAMS` | Неверный сервис или параметры |
340
460
  | 5 | `WALLET_NOT_FOUND` | Внутренний кошелёк не найден. Обратитесь в поддержку. |
341
461
  | 6 | `INSUFFICIENT_FUNDS` | Недостаточно средств |
342
- | 10 | `INVALID_TRON_ADDRESS` | Неверный адрес TRON |
462
+ | 10 | `INVALID_TRON_ADDRESS` | Неверный адрес TRON, или у адреса уже есть активная подписка |
343
463
  | 11 | `INVALID_ENERGY_AMOUNT` | Неверное количество энергии |
344
464
  | 12 | `INVALID_DURATION` | Неверная длительность |
345
465
  | 20 | `TRANSACTION_NOT_FOUND` | Транзакция/подписка не найдена |
346
- | 21 | `CANNOT_STOP_SUBSCRIPTION` | Невозможно остановить подписку |
466
+ | 21 | `CANNOT_STOP_SUBSCRIPTION` | Невозможно остановить подписку, например, у неё есть лимит транзакций |
347
467
  | 24 | `ADDRESS_NOT_ACTIVATED` | Адрес не активирован |
348
468
  | 25 | `ADDRESS_ALREADY_ACTIVATED` | Адрес уже активирован |
349
469
  | 30 | `AML_CHECK_NOT_FOUND` | AML-проверка не найдена |
350
470
  | 35 | `SERVICE_NOT_AVAILABLE` | Сервис недоступен |
351
471
  | 50 | `INVALID_BANDWIDTH_AMOUNT` | Неверное количество bandwidth |
472
+ | 90 | `BULK_NOT_FOUND` | Массовый заказ не найден |
473
+ | 91 | `BULK_EXPIRED` | Расчёт истёк, рассчитайте заново |
474
+ | 92 | `BULK_PRICE_CHANGED` | Цена изменилась; новый расчёт в `BulkPriceChangedError#calculation` |
475
+ | 93 | `BULK_TOO_MANY_ITEMS` | Больше 10 000 строк |
476
+ | 94 | `BULK_NO_VALID_ITEMS` | Нет корректных строк; они в `BulkNoValidItemsError#rejected` |
477
+ | 95 | `BULK_RESOURCE_NOT_SUPPORTED` | Массово можно заказать только энергию |
478
+ | 96 | `PAYLOAD_TOO_LARGE` | Слишком большое тело запроса (HTTP 413) |
479
+ | 429 | `RATE_LIMITED` | Слишком много запросов; подождите `retry_after`, если указано |
352
480
  | 500 | `INTERNAL_SERVER_ERROR` | Внутренняя ошибка сервера: обратитесь в поддержку |
353
481
 
354
482
  Константы находятся в `Tronzap::ErrorCode`. Код, который эта версия SDK не знает,