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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +70 -0
- data/README.es.md +145 -15
- data/README.md +143 -14
- data/README.pt-br.md +145 -14
- data/README.ru.md +141 -13
- data/lib/tronzap/client.rb +157 -6
- data/lib/tronzap/coerce.rb +8 -0
- data/lib/tronzap/errors.rb +74 -17
- data/lib/tronzap/models/bulk_rejected_row.rb +30 -0
- data/lib/tronzap/models/direct_recharge_rate.rb +1 -1
- data/lib/tronzap/models/energy_rate.rb +12 -8
- data/lib/tronzap/models/enums.rb +15 -1
- data/lib/tronzap/models/subscription_params.rb +28 -0
- data/lib/tronzap/requests/aml_check.rb +17 -6
- data/lib/tronzap/requests/bulk_calculate.rb +40 -0
- data/lib/tronzap/requests/bulk_create.rb +52 -0
- data/lib/tronzap/requests/bulk_history.rb +28 -0
- data/lib/tronzap/requests/bulk_item.rb +29 -0
- data/lib/tronzap/requests/bulk_lookup.rb +48 -0
- data/lib/tronzap/requests/bulk_report.rb +55 -0
- data/lib/tronzap/requests/start_subscription.rb +54 -0
- data/lib/tronzap/requests/subscription_history.rb +35 -0
- data/lib/tronzap/requests/subscription_lookup.rb +48 -0
- data/lib/tronzap/requests/validation.rb +8 -0
- data/lib/tronzap/response_decoder.rb +53 -15
- data/lib/tronzap/responses/aml_check.rb +1 -1
- data/lib/tronzap/responses/bulk_calculation.rb +44 -0
- data/lib/tronzap/responses/bulk_history.rb +28 -0
- data/lib/tronzap/responses/bulk_order.rb +87 -0
- data/lib/tronzap/responses/calculation.rb +5 -3
- data/lib/tronzap/responses/energy_estimate.rb +6 -4
- data/lib/tronzap/responses/service_rates.rb +3 -2
- data/lib/tronzap/responses/subscription.rb +73 -0
- data/lib/tronzap/responses/subscription_history.rb +28 -0
- data/lib/tronzap/responses/subscription_plan.rb +52 -0
- data/lib/tronzap/version.rb +1 -1
- data/lib/tronzap.rb +17 -0
- 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.
|
|
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
|
|
200
|
-
|
|
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.
|
|
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
|
-
|
|
234
|
-
|
|
235
|
-
345 de largura de banda com um
|
|
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`).
|
|
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
|
|
316
|
-
#
|
|
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.
|
|
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.
|
|
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
|
-
|
|
236
|
-
|
|
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
|
|
317
|
-
#
|
|
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 не знает,
|