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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 86611a40847769c3a60c570dd640db889321415c41a055e7fba673f5107f9031
4
- data.tar.gz: 45f7e631e0330e6a793439977f23c56a4fbe84b9040cdc32bc3fe46c10e71db1
3
+ metadata.gz: 87ef011e9fd858da6fede2b4e76bb129d1a5bedf9afdd7bb71167a12eec78f0d
4
+ data.tar.gz: f2abe0df1ccbf4d505aba8432f75590e76643df7aeddc2de8007180b7942954e
5
5
  SHA512:
6
- metadata.gz: 3906b2f2da02157003cc7b9d0025efd30289cef21449b00afad21db02da58ecfaaeff73bfc65409f188f4943dd822d19202aad80b039af0025aabff23951bb91
7
- data.tar.gz: fe05201951457d4295374ade54a27c47919ff1be033dff0e5d7a6692262beb57e251319416ad16dbdd0674cc05d9df91c05b431fbd5a51c447bc37ca5bab6d5c
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.4 · contrato da API: 0.1.0
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 || {}).reject { |_, value| value.nil? || value == "" }
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}",