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.
- checksums.yaml +4 -4
- data/README.md +68 -4
- data/lib/perata/client.rb +12 -1
- data/lib/perata/models.rb +308 -34
- data/lib/perata/params.rb +44 -16
- data/lib/perata/services.rb +651 -73
- data/lib/perata/version.rb +1 -1
- data/lib/perata/webhooks.rb +8 -3
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 87ef011e9fd858da6fede2b4e76bb129d1a5bedf9afdd7bb71167a12eec78f0d
|
|
4
|
+
data.tar.gz: f2abe0df1ccbf4d505aba8432f75590e76643df7aeddc2de8007180b7942954e
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 0e89ceaf9ce24071cc00d679cbc4e0d3166be306b9052dca8bdf74d7b4d7f7c7c0ff388b7c483686f4e14c5d5672232402a256b024273363e62f86253a95c6e2
|
|
7
|
+
data.tar.gz: 04f9b7482ab58394ed8b1765ca44e823b740bb6e5f66609251e2d31fcc96a899db4dfbbbe8eafa2397fae0fd5d7f7b08eff11af62b2a284b6427dd15fd8203bd
|
data/README.md
CHANGED
|
@@ -36,14 +36,15 @@ end
|
|
|
36
36
|
| `perata.payments` | `get`, `list`, `list_iter` |
|
|
37
37
|
| `perata.prices` | `create`, `list`, `list_iter` |
|
|
38
38
|
| `perata.products` | `archive`, `create`, `get`, `list`, `list_iter`, `update` |
|
|
39
|
-
| `perata.refunds` | `create`, `list`, `list_iter` |
|
|
39
|
+
| `perata.refunds` | `create`, `get`, `list`, `list_iter` |
|
|
40
|
+
| `perata.showcase` | `get` |
|
|
40
41
|
| `perata.subscriptions` | `cancel`, `get`, `list`, `list_iter`, `resume`, `update` |
|
|
41
42
|
| `perata.usage` | `ingest` |
|
|
42
43
|
| `perata.webhooks` | `create_endpoint`, `delete_endpoint`, `get_endpoint`, `list_deliveries`, `list_deliveries_iter`, `list_endpoints`, `list_endpoints_iter`, `update_endpoint` |
|
|
43
44
|
|
|
44
45
|
Os modelos são objetos imutáveis com leitores em snake_case (`payment.amount_cents`). O corpo de uma escrita é a classe de parâmetros do método (`Perata::ProductsCreateParams.new(name: "Curso")`) ou um `Hash` com os mesmos nomes; um campo opcional não informado fica fora do JSON. Os métodos `_iter` devolvem um `Enumerator` que percorre todas as páginas a partir de `page:` (ou recebem um bloco).
|
|
45
46
|
|
|
46
|
-
As escritas aceitam `idempotency_key:`, e todas aceitam `api_key:` para usar a chave de outra organização numa chamada. `Perata::Client.new` aceita `base_url:`, `timeout:` (30 segundos) e `transport:`. Um POST sem chave de idempotência é enviado com uma `Idempotency-Key` própria (UUID v4 aleatório, uma por chamada); passe a sua para poder repetir a mesma operação com segurança.
|
|
47
|
+
As escritas aceitam `idempotency_key:`, e todas aceitam `api_key:` para usar a chave de outra organização numa chamada. `Perata::Client.new` aceita `base_url:`, `timeout:` (30 segundos) e `transport:`. Um POST sem chave de idempotência é enviado com uma `Idempotency-Key` própria (UUID v4 aleatório, uma por chamada); passe a sua para poder repetir a mesma operação com segurança. Uma resposta 2xx fica guardada sob a chave; uma recusa 4xx ou uma falha 5xx a libera, e você pode repetir a escrita com a mesma chave, com o corpo corrigido ou como estava.
|
|
47
48
|
|
|
48
49
|
## Checkout transparente e embutido
|
|
49
50
|
|
|
@@ -70,6 +71,62 @@ No navegador, com o `client_secret` que o seu servidor devolveu (o site precisa
|
|
|
70
71
|
</script>
|
|
71
72
|
```
|
|
72
73
|
|
|
74
|
+
## Encerrar, listar e reativar
|
|
75
|
+
|
|
76
|
+
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), e o evento `checkout.expired` é enviado. Repetir a chamada é seguro; um checkout já pago, ou com boleto emitido, responde 409.
|
|
77
|
+
|
|
78
|
+
```ruby
|
|
79
|
+
closed = perata.checkouts.expire(checkout_id)
|
|
80
|
+
# closed.status == "expired"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Listar com filtros: `client_reference_id` acha o pedido que você registrou ao criar o checkout, e `metadata` casa os pares que você guardou (até 10 pares; a linha precisa ter todos). Os dois valem nas listas de checkouts, pedidos, pagamentos e assinaturas, e o filtro segue nas páginas de `list_iter`.
|
|
84
|
+
|
|
85
|
+
```ruby
|
|
86
|
+
filters = { client_reference_id: "pedido-123", metadata: { "pedido" => "123", "camera id" => "a/b" } }
|
|
87
|
+
page = perata.orders.list(**filters)
|
|
88
|
+
|
|
89
|
+
perata.orders.list_iter(**filters).each do |order|
|
|
90
|
+
puts order.id
|
|
91
|
+
end
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Reativar uma assinatura suspensa, que volta a ser cobrada, ou retomar uma pausada; qualquer outra assinatura responde 409:
|
|
95
|
+
|
|
96
|
+
```ruby
|
|
97
|
+
subscription = perata.subscriptions.resume(subscription_id)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Reembolso, assinatura com data e showcase
|
|
101
|
+
|
|
102
|
+
Reembolsar o pedido, sem o `payment_id`: envie o `order_id` (o id que `orders.get` recebe). Sem `amount_cents` devolve tudo o que ainda pode ser devolvido; com ele, só essa parte, em centavos (de 1 até o que resta). O `metadata` do pedido de reembolso guarda pares seus, que voltam como `refund_metadata` no reembolso e nos eventos `refund.created` e `refund.updated`; `reason` e `note` dizem o motivo. O reembolso traz `order_id`, `client_reference_id` e o `metadata` do pedido, e `refunds.get` lê um pelo id. Um reembolso que falha emite `refund.failed`, com `failure_reason` (em português) e `failure_code` (o código da Cielo, para o suporte).
|
|
103
|
+
|
|
104
|
+
```ruby
|
|
105
|
+
refund = perata.refunds.create({ order_id: order_id })
|
|
106
|
+
# refund.order_id, refund.status, refund.amount_cents
|
|
107
|
+
|
|
108
|
+
part = perata.refunds.create({ order_id: order_id, amount_cents: 2500 })
|
|
109
|
+
found = perata.refunds.get(refund.id)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Assinatura que começa numa data: `subscription_start_at` em `checkouts.create` é o dia da primeira cobrança, como o `trial_end` do Stripe. O cartão é guardado e conferido com o emissor, nada é cobrado hoje, e a cobrança acontece nesse dia (vale a meia-noite dele em São Paulo, qualquer que seja o fuso enviado). Só vale em um preço recorrente com valor, e só no cartão de crédito; tem de ser de amanhã a um ano, senão a resposta é 422. `items` e `discount_id` também valem num checkout de assinatura, e um pedido ou pagamento de assinatura traz `subscription_id`, `cycle_sequence`, `period_start` e `period_end`; as listas de pedidos e pagamentos aceitam o filtro `subscription_id`.
|
|
113
|
+
|
|
114
|
+
```ruby
|
|
115
|
+
checkout = perata.checkouts.create({
|
|
116
|
+
product_id: product_id,
|
|
117
|
+
price_id: price_id,
|
|
118
|
+
subscription_start_at: "2026-12-15T00:00:00-03:00",
|
|
119
|
+
})
|
|
120
|
+
# checkout.subscription_start_at: o instante da primeira cobrança
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Showcase: toda chave de API é de um showcase, e todo objeto da API traz o `showcase_id` dele. `showcase.get` lê o showcase da chave: o `id`, o `name`, se é o principal da organização (`is_principal`), se tem logo (`has_logo`) e o `environment` (`test` ou `live`). Uma chave só alcança o que é do seu showcase, e um 403 diz qual escopo faltou.
|
|
124
|
+
|
|
125
|
+
```ruby
|
|
126
|
+
showcase = perata.showcase.get
|
|
127
|
+
# showcase.id, showcase.name, showcase.is_principal, showcase.has_logo, showcase.environment
|
|
128
|
+
```
|
|
129
|
+
|
|
73
130
|
## Consumo (ingestão de eventos)
|
|
74
131
|
|
|
75
132
|
A ingestão de consumo usa outra credencial: a de uma fonte de ingestão (**Configurações › Fontes de ingestão**), `pus_test_…` em teste e `pus_live_…` em produção. Monte um cliente com ela; a chave de API da organização (`prk_…`) é recusada aqui com 401, e uma credencial de um ambiente nunca escreve no outro.
|
|
@@ -101,14 +158,21 @@ event = Perata.verify_webhook(ENV.fetch("PERATA_WEBHOOK_SECRET"), request.header
|
|
|
101
158
|
case event
|
|
102
159
|
when Perata::OrderWebhookEvent then puts event.type, event.data.id, event.data.installments
|
|
103
160
|
when Perata::DisputeWebhookEvent then puts event.data.provider_dispute_id
|
|
161
|
+
when Perata::SubscriptionWebhookEvent
|
|
162
|
+
case event.type
|
|
163
|
+
when "subscription.past_due" then puts event.data.id, event.data.payment_failure&.attempt # uma cobrança de cartão foi recusada
|
|
164
|
+
when "subscription.suspended" then puts event.data.id, event.data.suspension_reason # as tentativas acabaram
|
|
165
|
+
end
|
|
104
166
|
when Perata::UnknownWebhookEvent then nil # um tipo que esta versão ainda não conhece: event.data é o JSON
|
|
105
167
|
end
|
|
106
168
|
```
|
|
107
169
|
|
|
170
|
+
O `subscription.past_due` sai a cada cobrança de cartão recusada (`payment_failure` traz o número da tentativa e quando o cartão será cobrado de novo): mantenha o acesso do cliente até o `subscription.suspended`. Esse diz que as tentativas acabaram (`suspension_reason`): cancele a assinatura ou reative-a com `subscriptions.resume`.
|
|
171
|
+
|
|
108
172
|
A assinatura é a do Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), com tolerância de 5 minutos. Passe o corpo cru, antes de interpretar; os cabeçalhos podem vir num `Hash` ou no env do Rack. Uma assinatura que não confere levanta `Perata::WebhookVerificationError`.
|
|
109
173
|
|
|
110
174
|
O evento é tipado: um tipo para cada dado que o webhook carrega (`OrderWebhookEvent` traz um `WebhookOrder`, `DisputeWebhookEvent` a disputa, `IdentifiersWebhookEvent` os identificadores…), e o `type` diz o que aconteceu; um tipo que esta versão do SDK ainda não conhece chega como `UnknownWebhookEvent`, com os dados como vieram. Durante a rotação do segredo o cabeçalho traz mais de uma assinatura, e basta uma conferir. `Perata.verify_webhook_signature` só confere a assinatura.
|
|
111
175
|
|
|
112
|
-
Todo evento traz o ambiente em que aconteceu, em `event.environment`: `"test"` ou `"live"` (vazio se um servidor antigo não mandou). Recuse o evento do ambiente errado: um endpoint de produção deve responder 400 a um evento `"test"`, para que um teste não dê baixa em um pedido real.
|
|
176
|
+
Todo evento traz o ambiente em que aconteceu, em `event.environment`: `"test"` ou `"live"` (vazio se um servidor antigo não mandou). Recuse o evento do ambiente errado: um endpoint de produção deve responder 400 a um evento `"test"`, para que um teste não dê baixa em um pedido real. O showcase da venda vem em `event.showcase_id` (vazio se um servidor antigo não mandou): um endpoint é de um showcase só, e o mesmo `showcase_id` está nos objetos do evento.
|
|
113
177
|
|
|
114
|
-
Versão do SDK: 0.5.
|
|
178
|
+
Versão do SDK: 0.5.6 · contrato da API: 0.1.0
|
data/lib/perata/client.rb
CHANGED
|
@@ -62,6 +62,8 @@ module Perata
|
|
|
62
62
|
attr_reader :products
|
|
63
63
|
# @return [RefundsService]
|
|
64
64
|
attr_reader :refunds
|
|
65
|
+
# @return [ShowcaseService]
|
|
66
|
+
attr_reader :showcase
|
|
65
67
|
# @return [SubscriptionsService]
|
|
66
68
|
attr_reader :subscriptions
|
|
67
69
|
# @return [UsageService]
|
|
@@ -92,6 +94,7 @@ module Perata
|
|
|
92
94
|
@prices = PricesService.new(self)
|
|
93
95
|
@products = ProductsService.new(self)
|
|
94
96
|
@refunds = RefundsService.new(self)
|
|
97
|
+
@showcase = ShowcaseService.new(self)
|
|
95
98
|
@subscriptions = SubscriptionsService.new(self)
|
|
96
99
|
@usage = UsageService.new(self)
|
|
97
100
|
@webhooks = WebhooksService.new(self)
|
|
@@ -101,7 +104,15 @@ module Perata
|
|
|
101
104
|
# Perata::Error.
|
|
102
105
|
def request(method, path, query: nil, body: nil, idempotency_key: nil, api_key: nil)
|
|
103
106
|
url = @base_url + path
|
|
104
|
-
values = (query || {}).
|
|
107
|
+
values = (query || {}).flat_map do |name, value|
|
|
108
|
+
if value.is_a?(Hash)
|
|
109
|
+
# A map filter is one pair a key: metadata[pedido]=123, the keys sorted.
|
|
110
|
+
value.sort_by { |key, _| key.to_s }.map { |key, each| ["#{name}[#{key}]", each] }
|
|
111
|
+
else
|
|
112
|
+
[[name, value]]
|
|
113
|
+
end
|
|
114
|
+
end
|
|
115
|
+
values = values.reject { |_, value| value.nil? || value == "" }
|
|
105
116
|
url += "?#{URI.encode_www_form(values)}" unless values.empty?
|
|
106
117
|
headers = {
|
|
107
118
|
"Authorization" => "Bearer #{api_key.nil? || api_key.empty? ? @api_key : api_key}",
|