DEV Community: Reserva INK

[Subscription] Subscription Flow

José Sobral — Tue, 20 Dec 2022 19:19:08 +0000

Neste manual vamos compartilhar como pensamos o nosso motor de Subscriptions dentro da nossa plataforma.

Chamamos de 'manual' e não 'artigo' pois o objetivo deste documento é ser um guia; por isso, a leitura não precisa ser top down e sim ser uma consulta para sanar eventuais dúvidas.

Esperamos que ajude os DEV's da INK e a todos que este documento tocar :)

Sumário

Seção 1: Principais diferenças de arquitetura entre o PagarMe e a Zoop

Bastidores Zoop
Diferença PagarMe-Zoop: desenho de endpoints
Diferença PagarMe-Zoop: consumo da API via métodos ao inves de JSON's
Arquitetura INK para o consumo da API da Zoop

Seção 2: Novos conceitos de arquitetura gerados pela migração da Zoop

Motor baseado em Webhooks
Expiração Manual de Subscriptions

Seção 3: Atributos essencias de subscription na Zoop e INK

due_date
due_since
expiration_date
is_active (loja)
is_active (subscription)
status
trial

Seção 4: Eventos utilizados

subscription.created
subscription.suspended
subscription.expired
subscription.active
invoice.overdue
invoice.paid

Seção 5: UseCases utilizados

Hashie Gem
Mind Map: Subscription Flow
UC's: webhooks
UC's: checkout
UC's: payment_update

Seção 1: Principais diferenças de arquitetura entre o PagarMe e a Zoop

No início do ano de 2021, demos um grande passo como plataforma: migramos do sistema de pagamentos do PagarMe para a Zoop

Sem entrar no mérito dos prós e contras de cada sistema de pagamento, neste artigo vamos focar no desafio técnico e em como a arquitetura de subscriptions foi idealizada.

Mas antes disso, nos bastidores...

O processo como um todo da migração foi a maior desafio técnico que os Devs da casa tiveram em suas carreiras naquele momento.

E, como todo o processo onde se adquire experiência, muita
coisa é feita na base de porrada e quebração de cabeça.

A história completa dos bastidores da migração ainda será um artigo, mas no resumo, alguns pontos relevantes:

Subdimensionamos o trabalho que seria migrar de um motor de assinaturas para outro
Na nossa arquitetura antiga, não suspendiamos o serviço de assinatura quando ele expirava, por isso não tinhamos experiência em como fazê-lo at all
Por fim, mais importante, quando o assunto é pagamento muito cuidado com a ânsia de lançar logo sua V0...lançar a migração de pagamento da forma que fizemos, foi bastante arriscado e pouco sustentável em matéria de gestão de conhecimento; isso gerou mais de 2 meses de trabalho posterior ao deploy, entre consertar bugs e readaptar novos motores. Além, é claro, de muita dor de cabeça.

Contudo, cá estamos com um motor novo de assinatura e buscando uma forma de registrar os passos que demos. VQV!

Voltando...

Tecnicamente, a maior diferença entre o PagarMe e a Zoop, é que o PagarMe é desenhado para ser implementando com muita velocidade e pouca customização.

Na prática, isso gera duas implicações:

Sistema de pagamento do pagarme chega com os endpoints preparados para a sua aplicação
O consumo da API se da através de métodos desenhados para a sua aplicação

Vamos a cada uma delas!

1-Sistema de pagamento do pagarme chega com os endpoints preparados para a sua aplicação

Por exemplo, para darmos um fetch em uma Subscription pelo PagarMe fazemos:

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription_id = "ID_DA_ASSINATURA"
subscription = PagarMe::Subscription.find_by_id(subscription_id)

Já pela Zoop, precisamos...

a) Criar uma classe que recebe os endpoints
b) Configurar cada um dos tipos de clients, com suas respectivas autenticações
c) No caso da nossa aplicação, criamos uma classe intermediária que modulariza o consumo da API no client side (nosso lado)
d) Por fim, darmos o fetch

A seguir, cada ponto com exemplos...

a) Criar uma classe que recebe os endpoints

app> service_layers > zoop > plans_and_subscriptions > api > endpoints.rb

class Zoop::PlansAndSubscriptions::Api::Endpoints
  def initialize(client, clientV2)
    @client = client
    @clientV2 = clientV2
  end

...

  def subscription_details(subscription_id:)
    path = "subscriptions/#{subscription_id}"
    data = { subscription_id: subscription_id }
    response = @clientV2.get(path: path, data: data)
    begin
      JSON.parse(response)
    rescue => error

      puts "JSON Parse error => #{error}"
    end
  end
end

b) Configurar cada um dos tipos de clients, com suas respectivas autenticações

app> service_layers > zoop > auth > rest_client_api.rb

class Zoop::Auth::RestClientApi
  def initialize
    @api_key = 'key'
    @mkt_place_id = 'key'
    @api_url = 'key'
  end

  def post(path:,data:)
    url = url(path)
    Rails.logger.info data

    request = RestClient::Request.new(method: :post, url: url,payload: data, user: @api_key)
    response = request.execute

    response
  end
...
end

c)No caso da nossa aplicação, criamos uma classe intermediária que modulariza o consumo da API no client side (nosso lado):

app> service_layers > zoop > plans_and_subscriptions > subscriptions > details.rb

class Zoop::PlansAndSubscriptions::Subscriptions::Details
    def initialize(subscription_id:)
        @subscription_id = subscription_id
        @endpoints = Zoop::PlansAndSubscriptions::Api::Endpoints.new(Zoop::Auth::RestClientApi.new, Zoop::Auth::RestClientApiV2.new)
    end

    def execute
        subscription_details = @endpoints.subscription_details(subscription_id: @subscription_id)
    end   
end

d)Por fim, darmos o fetch

subscription_details = Zoop::PlansAndSubscriptions::Subscriptions::Details.new(
subscription_id: @subscription.zoop_subscription_id).execute

2-O consumo da API se da através de métodos desenhados para a sua aplicação

No pagarMe, para você acessar o fim do período de uma subscription (atributo current_period_end) é feito através de:

irb(main):003:0> PagarMe::Subscription.all.last.current_period_end
RestClient.get "https://api.pagar.me/1/subscriptions", "{\"page\":1,\"count\":10}", "Accept"=>"application/json", "Content-Length"=>"21", "Content-Type"=>"application/json; charset=utf8", "User-Agent"=>"pagarme-ruby/2.4.0", "X-PagarMe-User-Agent"=>"pagarme-ruby/2.4.0"
# => 200 OK | application/json 19666 bytes, 0.15s
=> "2021-03-10T00:27:31.849Z"
irb(main):004:0>

Já na Zoop, consumindo a API você recebe JSON's. Com isso, para acessar o fim do período de uma subscription (atributo expiration_date) fazemos:

irb(main):004:0> subscription_details = Zoop::PlansAndSubscriptions::Subscriptions::Details.new(
irb(main):005:1* subscription_id: Subscription.all.last.zoop_subscription_id).execute
  Subscription Load (2.2ms)  SELECT "subscriptions".* FROM "subscriptions" WHERE "subscriptions"."deleted_at" IS NULL ORDER BY "subscriptions"."id" DESC LIMIT $1  [["LIMIT", 1]]
=> {"id"=>"33ea0db33dc3430489527a6f1f2c1b6d", "marketplace_id"=>"aa671febc9d4466b9f34134327c56d20", "plan"=>"561ce6726be74b16b9fe4c51f6a94b03", "currency"=>"BRL", "updated_at"=>"2021-08-02T23:18:30+00:00", "tolerance_period"=>nil, "on_behalf_of"=>"36fabbcd71a540a2b4a34ae338b58069", "payment_method"=>"credit", "due_since"=>nil, "expiration_date"=>"2021-08-16T23:00:00", "created_at"=>"2021-08-02T22:45:53+00:00", "suspended_at"=>"2021-08-02T23:18:30+00:00", "due_date"=>"2021-08-16", "status"=>"suspended", "amount"=>9900, "customer"=>"10066c2410f9427ea3d6553b8dc8baeb"}
irb(main):006:0> subscription_details["expiration_date"]
=> "2021-08-16T23:00:00"
irb(main):007:0>

Essas duas diferenças já mudam drasticamente a maneira como todas as entidades de assinaturas vão se relacionar entre API-INK.

Contudo, a principal questão para o nosso time foi que não pensamos nos processos de interface da API com a nossa aplicação, como

renovação de pagamento
expiração de subscription
exclusão de multiplas subscriptions em caso de upsell
etc

pois no PagarMe, esses processos eram realizados automaticamente no lado do PagarMe.

Com isso, vamos aos principais conceitos de arquitetura trazidos pela escolha da Zoop

Seção 2: Novos conceitos gerados pela migração da Zoop

Motor baseado em Webhooks

Pela Zoop, recomenda-se que usemos os chamados Webhooks para "ouvir" as interações entre a API e a INK.

Na prática, um Webhook é de fato um "gancho" para que quando uma ação ocorra na API, haja uma chamada para o client side informando a ação e o que foi alterado.

Por exemplo, toda vez que houver uma criação de subscription na Zoop, haverá um trigger no evento subscription.created; com isso, podemos criar um Webhook que, toda vez que houver um subscription.created, possamos usar informações deste evento para atualizar nosso banco e aplicar nossas próprias regras de negócio.

Expiração Manual de Subscriptions

Na Zoop, a expiração de uma subscription é feita manualmente.

O que isso significa?

Simples, nós que precisamos dizer quando uma assinatura expira

Na prática isso trouxe uma grande dor de cabeça:

Como vamos setar e atualizar o campo de expiração para que o fluxo de renovação e suspensão de assinatura funcione corretamente?

A resposta à esta pergunta virá na explicação dos UseCases utilizados na nossa aplicação

Seção 3: Atributos essencias de subscription na Zoop e INK

Nesta seção, nosso objetivo é explicar cada um dos principais atributos gerados pela subscription na zoop e na nossa base.

Atributos Zoop

due_date: Data da próxima cobrança para a Subscription
expiration_date: Data de expiração para a Subscription
due_since: Data do último pagamento atribuido a subscription
status: Status que se encontra a Subscription (active, suspended, expired)

Atributos INK

expiration_date: Reflexo direto do expiration_date da Zoop
is_active (store): Booleano que indica se a loja está ativa ou não; caso não esteja, o usuário não conseguirá realizar vendas em sua loja.
is_active (subscription): Booleano que indica se a subscripton está ativa ou não; caso o usuário não possua nenhuma subscription ativa (is_active = true), a loja terá, em tese, um is_active = false
trial: Booleano que diz se a condição de trial para subscription é true ou false
status: Reflexo direto do status vindo da Zoop

A interface entre os atributos ficará clara na seção de UseCases Utilizados

Seção 4: Eventos utilizados

Nesta seção, vamos explicitar cada um dos eventos utlizados pela nossa aplicação, um payload de exemplo e quando idealizamos que eles seriam triggados

subscription.created

Payload

 {
            "created_at": "2021-08-04T12:05:30+00:00",
            "payload": {
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
                "suspended_at": null,
                "payment_method": "credit",
                "currency": "BRL",
                "expiration_date": null,
                "due_since": null,
                "amount": 49900,
                "updated_at": "2021-08-04T12:05:30+00:00",
                "created_at": "2021-08-04T12:05:30+00:00",
                "status": "active",
                "id": "b66d91d2963445ef81aab5f173551b21",
                "due_date": "2021-08-18",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "tolerance_period": null,
                "customer": "25b1a9c31ebc43fb85975eed7433761e"
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/5a55ea1828bc409087f4b6f02bdef9f3",
            "id": "5a55ea1828bc409087f4b6f02bdef9f3",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:05:40+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "59c61025a6384edd8295493a4d0f55f5"
                }
            ],
            "type": "subscription.created"
        }

Trigger

No checkout de subscription (app>app_core>subscription>use_cases>checkout>process_subscription_checkout.rb), há a criação da subscription da Zoop e neste momento imaginamos que este evento será triggado.

subscription.suspended

Payload

 {
            "created_at": "2021-08-04T12:15:18+00:00",
            "payload": {
                "payment_method": "credit",
                "currency": "BRL",
                "tolerance_period": null,
                "updated_at": "2021-08-04T12:15:18+00:00",
                "expiration_date": "2021-08-18T23:00:00",
                "created_at": "2021-08-04T12:05:30+00:00",
                "customer": "25b1a9c31ebc43fb85975eed7433761e",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
                "amount": 49900,
                "suspended_at": "2021-08-04T12:15:18+00:00",
                "status": "suspended",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "due_date": "2021-08-18",
                "id": "b66d91d2963445ef81aab5f173551b21",
                "due_since": null
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/c1a933089175476d86e902a003b3b01e",
            "id": "c1a933089175476d86e902a003b3b01e",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:15:28+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "1c10b9ecf9c94687a43d7946d35f6141"
                }
            ],
            "type": "subscription.suspended"
        }

Trigger

Quando o usuário acessa a rota de /user/subscription, caso sua subscription esteja ativa, irá aparecer um botão escrito "Suspender Assinatura". No click deste botão é suspensa a assinatura e é trigado este evento (app>app_core>subscription>use_cases>webhooks>handle_subscription_suspended_event.rb)

subscription.expired

Payload

 {
            "created_at": "2021-08-04T12:28:01+00:00",
            "payload": {
                "payment_method": "credit",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "created_at": "2021-04-19T19:26:51+00:00",
                "suspended_at": null,
                "tolerance_period": null,
                "expiration_date": "2021-06-10T09:01:54",
                "amount": 12900,
                "updated_at": "2021-08-04T12:28:01+00:00",
                "id": "67c9583d6b1f408ca2bbad23677901d6",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "due_date": "2021-05-03",
                "customer": "f4f34cd05e2743029cab8e47a1e03e35",
                "status": "expired",
                "due_since": null,
                "currency": "BRL",
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20"
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/12e32795b0ce49dc8a914e36723514f3",
            "id": "12e32795b0ce49dc8a914e36723514f3",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:28:11+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "5388ead647cb4e9d93c78f33797e90ff"
                }
            ],
            "type": "subscription.expired"
        }

Trigger

Este evento será triggado quando a subscription chegar na sua data de expiração e não houver renovação da assinatura. Isso acontece quando o usuário não pagou a subscription e, no dia de expiração, a assinatura irá de active para expired

subscription.active

Payload

  {
            "created_at": "2021-08-04T12:58:40+00:00",
            "payload": {
                "payment_method": "credit",
                "currency": "BRL",
                "tolerance_period": null,
                "updated_at": "2021-08-04T12:58:40+00:00",
                "expiration_date": "2021-09-03T23:59:59",
                "created_at": "2021-06-16T13:52:43+00:00",
                "customer": "74369907fd1f446d9777c201be73eef6",
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
                "amount": 12900,
                "suspended_at": null,
                "status": "active",
                "plan": "561ce6726be74b16b9fe4c51f6a94b03",
                "due_date": "2021-07-30",
                "id": "dc9ace773b63461c81139bd00d33c9d0",
                "due_since": "2021-06-30"
            },
            "resource": "event",
            "status": "succeeded",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/b71e8a87ff0d41798be9033118342c9f",
            "id": "b71e8a87ff0d41798be9033118342c9f",
            "dispatches": [
                {
                    "created_at": "2021-08-04T12:58:50+00:00",
                    "status": "succeeded",
                    "replay": false,
                    "webhook_id": "3286bf41cbf2474d87e29e2331d0fef5"
                }
            ],
            "type": "subscription.active"
        }

Trigger

Este evento terá trigger quando uma assinatura for suspensa e posteriormente for reativada. Isso pode ser feito através do /user/subscription; quando o usuário suspender a assinatura, aparecerá uma opção "Reativar Assinatura". O click deste botão irá reativar a assinatura e triggar este evento

invoice.overdue

Payload

  {
            "resource": "event",
            "created_at": "2021-08-04T13:02:13+00:00",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/36a24c2ab51746e4887ab5b3d318f32f",
            "status": "succeeded",
            "id": "36a24c2ab51746e4887ab5b3d318f32f",
            "dispatches": [
                {
                    "created_at": "2021-08-04T13:02:23+00:00",
                    "webhook_id": "b23ea12e177c482083b4ea02dae54f7d",
                    "status": "succeeded",
                    "replay": false
                }
            ],
            "type": "invoice.overdue",
            "payload": {
                "id": "56fd660c44c240afb0a3869c6398ab40",
                "setup_amount": null,
                "tolerance_period": null,
                "transactions": [],
                "description": null,
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "amount": 12900,
                "voided_at": null,
                "due_date": "2021-07-30T00:00:00",
                "status": "failed",
                "retries": 3,
                "payment_method": "credit",
                "paid_at": null,
                "subscription": "dc9ace773b63461c81139bd00d33c9d0",
                "expiration_date": null,
                "resource": "invoice",
                "invoice_customer": {
                    "first_name": "",
                    "last_name": null,
                    "taxpayer_id": null,
                    "id": "74369907fd1f446d9777c201be73eef6",
                    "email": "laurormn@gmail.com"
                },
                "max_retries": 3
            }
        }

Trigger

Primeiramente, um "invoice" é uma fatura. O conceito de fatura geralmente está relacionado com recorrência, quase como se fosse uma "conta" que chega periodicamente para você.

Na nossa aplicação, a única "conta" que chega recorrentemente para os usuários é a subscription. Logo, todos os eventos de invoice, hoje, estão relacionados a subscription.

O invoice.overdue significa que aquela fatura teve o seu número máximo de tentativas de pagamento atingido. Ou seja, o cartão de crédito associado pode estar sem limite disponível, pode não estar mais válido (caso de cartão de crédito virtual que é excluido) entre outras possibilidades. O fato é que o pagamento não aconteceu.

Este evento acontece no due_date (data da pŕoxima cobrança) da assinatura. Se no dia da cobrança ela for mal sucedida, este evento será trigado.

invoice.paid

Payload

{
            "resource": "event",
            "created_at": "2021-08-04T13:03:13+00:00",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/7dbdc97c63df45f8bd40e80595b9e7a7",
            "status": "succeeded",
            "id": "7dbdc97c63df45f8bd40e80595b9e7a7",
            "dispatches": [
                {
                    "created_at": "2021-08-04T13:03:23+00:00",
                    "webhook_id": "9d453bca7b9947d4987d5e02dec0c692",
                    "status": "succeeded",
                    "replay": false
                }
            ],
            "type": "invoice.paid",
            "payload": {
                "payment_method": "credit",
                "status": "paid",
                "invoice_customer": {
                    "id": "888e1165cddf44d0a8eab133f41f53e5",
                    "taxpayer_id": "34498991000104",
                    "email": "suporte@arquiteturaequestre.com.br",
                    "first_name": "",
                    "last_name": null
                },
                "amount": 12900,
                "voided_at": null,
                "description": null,
                "due_date": "2021-08-04T00:00:00",
                "setup_amount": null,
                "retries": 0,
                "tolerance_period": null,
                "resource": "invoice",
                "paid_at": "2021-08-04T13:03:13+00:00",
                "max_retries": 3,
                "transactions": [
                    {
                        "masked_card": "5226***2794",
                        "card_brand": "MasterCard",
                        "currency": "BRL",
                        "id": "f00d64630d3d4af881a145371775f6b2"
                    }
                ],
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "id": "35c9881a40654d1d87b1d2e0fe8251b4",
                "subscription": "6bf2e484c5a249a98ca3e12196c5c41c",
                "expiration_date": null
            }
        }

Trigger

Como já explicado no evento anterior, um invoice é uma fatura. O evento ìnvoice.paid diz que uma fatura foi paga. Inclusive neste evento podemos saber a transaction_id relacionada a subscription.

Seção 5: UseCases utilizados

Antes de começarmos a falar sobre os UC, precisamos falar de dois pontos essenciais:

Hashie Gem
Como projetamos cada UC

1-Hashie Gem

Esta é uma Gem que usamos no Flow de Subscription que facilitou muito o nosso lado na hora de manipular os payloads chegados pela Zoop através dos Webhooks

Para resumir a história do uso por de trás da Gem, vamos falar apenas sobre a dor resolvida e como implementamos ela no projeto

Dor resolvida Imagina que, recebendo um hash do evento invoice.paid, por exemplo, queiramos acessar a transaction_id desta fatura.

Para isso, quando chega o payload de exemplo:

 {
            "resource": "event",
            "created_at": "2021-08-04T14:42:13+00:00",
            "uri": "/v1/marketplaces/aa671febc9d4466b9f34134327c56d20/events/190dc7e15d414005aafe90d028ec54c3",
            "status": "succeeded",
            "id": "190dc7e15d414005aafe90d028ec54c3",
            "dispatches": [
                {
                    "created_at": "2021-08-04T14:42:23+00:00",
                    "webhook_id": "9d453bca7b9947d4987d5e02dec0c692",
                    "status": "succeeded",
                    "replay": false
                }
            ],
            "type": "invoice.paid",
            "payload": {
                "payment_method": "credit",
                "status": "paid",
                "invoice_customer": {
                    "id": "a6080bb9b36c4af8a9c9fce651fd7ea8",
                    "taxpayer_id": "39123487828",
                    "email": "weynerenan@gmail.com",
                    "first_name": "Renan",
                    "last_name": "Weyne"
                },
                "amount": 12900,
                "voided_at": null,
                "description": "Fatura avulsa de assinatura para loja 3w",
                "due_date": "2021-08-04T00:00:00",
                "setup_amount": null,
                "retries": 0,
                "tolerance_period": null,
                "resource": "invoice",
                "paid_at": "2021-08-04T14:42:13+00:00",
                "max_retries": 3,
                "transactions": [
                    {
                        "masked_card": "5502***5987",
                        "card_brand": "MasterCard",
                        "currency": "BRL",
                        "id": "dcab432a48e445e3b5c42a0e91400bdb"
                    }
                ],
                "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
                "id": "f304c7eb4d8d464b96e94e44a33a1e35",
                "subscription": "5c99dfbb6dd745db9e75159f9b8912e9",
                "expiration_date": null
            }
        }

Podemos colocar este numa variável event e extrair o transaction_id através de:

event["payload"]["transactions"][0]["id"]

O Hashie chega para prevenir esta sintax! Com ele, podemos buscar o chave de um hash através de métodos intuitivos e que facilitam muito o manejo de objetos com estrutura em hash.

No exemplo do payload, com o Hashie, poderíamos extrair o transaction_id fazendo:

@event_params = event_params
@transactions = (@event_params.deep_find("transactions"))[0]
@transactions["id"]

E por isso usamos o Hashie! Para facilitar a sintax de manipulação de objetos com estrutura em hash :)

Implementação no Projeto

A implementação aconteceu em 3 etapas

a) Adicionar no projeto os módulos associados ao Hashie.
app>services>hashie>deep_find.rb
app>services>hashie>deep_locate.rb
app>services>hashie>deep_fetch.rb

b) Criamos um Presenter* que recebe o hash como params na chamada da nossa aplicação pelo webhook da Zoop chamado ParametersPresenter

class ParametersPresenter < BasePresenter
  def initialize(event_params:)
    @event_params = event_params
  end

  def build
    @event_params.permit! rescue nil
    hash_params = @event_params.to_h rescue @event_params

    hash_params.extend Hashie::Extensions::DeepFind
    hash_params.extend Hashie::Extensions::DeepFetch
    hash_params.extend Hashie::Extensions::DeepLocate
  end
end

Este Presenter tem como finalidade adaptar um objeto que chega como ActionController::Paramaters para um objeto Hash com métodos do Hashie como o deep_find mostrado anteriormente.

c) Damos um build em cada UC para transformar um ActionController::Parameters um Hash com PowerUps da gem do Hashie

Exemplo:

module Subscription::UseCases::Webhooks
  class HandleInvoicePaidEvent
    def self.build(event_params:)
      new(
        event_params: ParametersPresenter.new(event_params: event_params).build
      )
    end

Pronto! Agora já sabemos como usar o Hashie :)

2-Como projetamos cada UC

Para este projeto, estreiamos o conceito de Mind Map na INK.

O objetivo era ter visualmente um fluxo de como cada ação do usuário refletia um evento na Zoop e, consequentemente, um script na nossa aplicação.

Este Mind Map foi essencial para estruturarmos a interface de cada atributo da INK com a Zoop e pensarmos na execução de cada UC

Hora dos UC's...

use_cases>webhooks

handle_invoice_paid_event.rb

Abaixo cada um dos métodos que são executados no evento invoice.paid

app>app_core>subscription>use_cases>webhooks>handle_invoice_paid.event.rb

    def execute
      set_active_status_into_db
      reactivate_status_into_zoop
      set_store_is_active
      set_subscription_is_active
      set_db_expiration_date
      set_zoop_expiration_date
      remove_trial
      create_subscription_invoice_record
    end

Interfaces:
a) Atributo status sendo setado active na Zoop e na INK
b) Atributo is_active da loja sendo setado para true
c) Atributo is_active da subscription sendo setado para true
d) Atributo trial sendo setado para false pois houve pagamento
e) Criação de um SubscriptionInvoice para acessarmos o invoice na nossa base com mais facilidade.
f) Atributo expiration_date sendo atualizado na Zoop e na INK. Ambos serão atualizados para o dia de hoje + dias do plano (anual, mensal); o final do dia que resultará esta operação, será o novo expiration_date

    def set_zoop_expiration_date
      current_expiration_date       = @subscription.expiration_date
      plan_days                     = @subscription.plan.interval

      Subscription::UpdateExpirationDateJob.perform_later(
        subscription: @subscription,
        expiration_date: plan_days.days.from_now.end_of_day.strftime('%Y-%m-%dT%H:%M:%S')
      )
    end

PS: A escolha do final do dia foi proposital. Isso ocorre pois o due_date (próxima cobrança) irá acontecer no início do dia, então caso não haja pagamento ao longo do dia, no final do dia haverá expiração

handle_invoice_overdue.rb

Abaixo cada um dos métodos que são executados no evento invoice.overdue

      def execute
        notify_invalid_credit_card_to_user
      end

Interfaces
a) Não há interfaces de atributos; aqui apenas notificamos o usuário do cartão de crédito inválido.

handle_subscription_active_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.active

    def execute
      set_status
    end

Interface
a) Atualizamos o atributo status na nossa base para active.

handle_subscription_created_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.created

    def execute
      set_trial
      set_status
      set_db_expiration_date
      set_zoop_expiration_date
    end

Interfaces
a) Setamos o atributo trial para true dado que a subscription acabou de ser criada
b) Setamos o atributo status para active
c) Setamos o atributo expiration_date para o due_date da subscription, no final do dia.

handle_subscription_expired_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.expired

    def execute
      set_status
      set_subscription_is_active
      handle_store_is_active
    end

Interfaces
a) Atributo status setado para expired
b) Atributo is_active da subscription é setado para false
c) Caso não hajam subscriptions com status active para aquele usuário, sua loja será desativada.

handle_subscription_suspended_event.rb

Abaixo cada um dos métodos que são executados no evento subscription.suspended

    def execute
      set_status
      handle_store_block
    end

Interfaces:
a) Setamos o atributo status para suspended
b) Lançamos um BackgroundJob para acontecer no dia da expiração da subscription; quando este BJ rodar, caso não hajam subscription com is_active=true, a loja será desativada.

Isso precisou ser feito pois as subscriptions suspended não migram para expired no dia da expiração; ou seja, elas nunca terão evento subscription.expired e precisamos usar este BJ para assegurar a desativação.

Exemplo:

        {
            "payment_method": "credit",
            "currency": "BRL",
            "tolerance_period": null,
            "updated_at": "2021-06-10T11:56:04+00:00",
            "expiration_date": "2021-06-10T08:56:02",
            "created_at": "2021-02-25T13:21:57+00:00",
            "customer": "a0ddaadd8c474a3193dcb153d88e0ea2",
            "on_behalf_of": "36fabbcd71a540a2b4a34ae338b58069",
            "marketplace_id": "aa671febc9d4466b9f34134327c56d20",
            "amount": 12900,
            "suspended_at": "2021-05-17T19:36:34+00:00",
            "status": "suspended",
            "plan": "561ce6726be74b16b9fe4c51f6a94b03",
            "due_date": "2021-06-11",
            "id": "3ced54f621d340bda03e7b39ceb34caf",
            "due_since": "2021-03-11"
        }

Subscription com expiration_date para 2021-06-10T08:56:02 (data já ocorrida) e mesmo assim com status suspended; mais uma vez, subscriptions suspended não triggam subscription.expired

Checkout

process_subscription_checkout.rb

        def execute
            create_buyer_id
            suspend_old_subscription
            create_zoop_subscription
            associate_credit_card_to_customer
            create_subscription_database_subscription
            create_store
        end

Payment Update

handle_subscription_reactivation_process.rb

        def execute
            associate_new_credit_card_to_zoop_customer
            associate_new_credit_card_token_to_subscription
            create_single_invoice
        end

Aqui, para reativarmos uma loja que está desativada, há um checkout especial (https://reserva.ink/subscriptions/reactivation/checkout).

Nele, simplesmente associamos um novo cartão de crédito ao usuário e criamos uma fatura avulsa para ser paga instanteamente.

Quando ela for paga, o evento invoice.paid será triggado e a loja será reativada.

handle_credit_card_change_process.rb

        def execute
            associate_new_credit_card_to_zoop_customer
            associate_new_credit_card_token_to_subscription
        end

Shrine Photo Uploader – Galeria de Fotos

José Sobral — Mon, 18 Jan 2021 22:36:31 +0000

Você já tentou criar uma aplicação web que permitisse upload de fotos? Nós, da Reserva INK já e gostaríamos de partilhar sobre a experiência de como criar uma feature iradíssima em Rails =)

Feature:

Usuários fazem upload de suas fotos

Relacionam à suas camisetas

Exibimos uma galeria de fotos e as respectivas imagens associadas a cada foto

Toolkit: Shrine

Neste artigo, contaremos um pouco mais sobre como instalar o Shrine e como utilizamos ele para criar a Galeria de Fotos da INK. Toda a aplicação desta feature foi escrita no paradigma MVC (Model View Controller), em Rails e tentaremos passar em detalhes a construção de cada parte do código.

Lembrando que a nossa intenção é muito mais compartilhar o conhecimento do que se mostrar referência na linguagem. Dito isso, se você tiver quaisquer sugestões de como poderíamos fazer melhor cada um dos passos a seguir ou apenas quiser conversar sobre a feature, estamos de braços abertos para receber feedbacks através do jose.sobral@reserva.ink

1-Como instalar o shrine do zero
2-Como configuramos em nossa aplicação

a)Model
I-Modelagem de dados
II-Criando os models no rails
III-Utilizando o shrine para guardar as imagens

b)View
I-Como criar o layout do form que guardará suas imagens II-Relacionar fotos e camisetas

c)Controller
I-Criando a galeria de cada loja
II-CRUD de fotos
III-Relacionamento de fotos e camisetas

1-Como instalar

A instalação do Shrine é bem tranquila e segue basicamente dois passos:

a) gemfile
gem "shrine", "~> 3.0"

b) config > initializers > shrine.rb

require "shrine"
require "shrine/storage/file_system"

if Rails.env.development? 
    Shrine.storages = {
        cache:  Shrine::Storage::FileSystem.new(“public”, prefix: “uploads/cache”)
        store: Shrine::Storage::FileSystem.new(“public”, prefix: “uploads”),


elsif Rails.env.Production? 
    Require ‘shrine/storage/s3’

    s3_options = {
        ***Suas credenciais do S3***
    }
    Shrine.storages = {
        cache: Shrine::Storage::S3.new(prefix: ‘cache’, **s3_options), # temporary
        store: Shrine::Storage::S3.new(prefix: ‘store, **s3options),       # permanent
}

end

Shrine.plugin :activerecord           # loads Active Record integration
Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files

Diferenciamos o Storage para o ambiente de Desenvolvimento e para o ambiente de Produção.

Quando a feature está no ar, o armazenamento de dados ocorre através do S3.
Em desenvolvimento, o upload é realizado para um banco local.

2-Como configuraramos em nossa aplicação

a)Model

i-Modelagem de dados

Para início de conversa, falemos sobre como a modelagem de dados foi feita. No ínicio, sabíamos que teriam dois fluxos de dados através das entidades:

Galeria
Fotos
Relacionamento fotos-produto

Por isso, quando começamos o projeto pensamos em criar três Models: Picture e GalleryRelatedProducts e Gallery, da seguinte forma:

Gallery

Estruturando o problema:

Cada seller teria sua própria galeria
Por enquanto, na nossa arquitetura atual, cada loja teria apenas uma galeria

Decisão

ID Store_id

Com esta modelagem, cada loja teria sua própria galeria (Store_id) e, no futuro, se quisermos que cada loja tenha mais de uma galeria, não teríamos que remodelar todo nosso Model pois poderíamos ter ID’s diferentes para o mesmo Store_id.

Picture

Estruturando o problema:

Cada loja precisava possuir suas próprias fotos
A mesma loja pode ter N fotos

Decisão:

ID Gallery_id Image_data

Com essa modelagem, cada foto teria seu próprio ID e saberíamos qual o owner da foto através do gallery_id

GalleryRelatedProducts

Estruturando o problema:

Cada loja poderia se relacionar N fotos ao mesmo produto
Cada Foto, poderia ser associada a N fotos

Decisão

ID Picture_id Art_id

Com isso, conseguimos criar um model N-N, que permite que a mesma foto (picture_id único) se relacione com tantas artes quanto necessário (Art_id) e vice e versa.

ii-Criando os models no rails

Para criar os models executamos através do cmd,

$ rails generate model Gallery store:references
$ rails generate model Picture gallery:references image_data:text
$ rails generate model PictureRelatedProduct picture:references art:references

PS1: O comando “references” cria automaticamente uma foreign_key com o model que veio chamado antes dos “:”

PS2: O campo “image_data” não foi escolhido por acaso, a documentação do shrine pede que utilizemos o nome do tipo de arquivo seguido de “data” para este atributo. Genericamente: _data

iii-Utilizando o shrine para guardar as imagens

Neste passo você começará a sentir a potência do Shrine. Descreveremos em 3 passos como fazer esta configuração

Primeiro passo: Criamos uma classe uploader, herdando métodos do Shrine

app > uploaders > store_picture_uploader.rb

Class StorePictureUploader < Shrine
end

Segundo passo: Na model que receberemos os dados do Upload (picture, no nosso caso), faremos uma chamada desta classe que criamos em (i)

app > models > picture.rb

class Picture < ApplicationRecord
    include StorePictureUploader::Attachment(:image) 
end

Com isso, garantimos que os dados que chegarão neste atributo (image_data) chegarão através do Shrine.

PS: Usamos :image pois foi o nome do campo que criamos no model Picture (image_data), tirando a palavra “data”.

Terceiro passo: Não tem passo 3, é só isso mesmo :)

b)View

Arquivos utilizados:
app > views > user > dashboard > galleries > index.html.erb
app > views > user > dashboard > galleries > edit_image.html.erb

O usuário terá acesso a três interfaces:

Upload de fotos
Alterar e Deletar fotos / associar foto a um produto
Galeria que exibirá suas fotos os clientes de uma loja

PS: A interface de exibição das fotos não entrará neste artigo pois utilizamos uma arquitetura DDD (Domain Driven Design). Posteriormente, em outro artigo falaremos sobre como utilizamos esta arquitetura.

Sendo assim, vamos explorar as duas primeiras interfaces

I-Como criar o layout do form que guardará suas imagens

Upload de fotos

app > views > user > dashboard > galleries > index.html.erb

<%= form_for :picture, url: gallery_upload_path do |f| %>
    <%= f.hidden_field :image %>
    <%= f.file_field :image %>
    <%= f.submit “Enviar foto” %>
<% end %>

Debugando:

:picture -> Model que estaremos enviando as informações do form
:image -> Atributo que estaremos enviando a imagem. Lembrando que, mesmo o nome do campo sendo image_data, deixamos apenas image segunda a documentação do Shrine
gallery_upload_path -> Rota de post para onde enviaremos as informações de upload

post '/user/dashboard/gallery/', to: 'user/dashboard/galleries#upload', as: :gallery_upload

Adicionando um CSS e helpers de bootstrap…

Deletar fotos

app > views > user > dashboard > galleries > edit_image.html.erb

<%= link_to gallery_delete_picture_path(@image.id) do%>
    <button> Deletar Foto da Galeria </button>
<% end %>

Debugando:

@image = Picture.find(params[:pic_id])
gallery_delete_picture_path -> Rota para deletar uma imagem no banco. Ela pede um parâmetro que é a ID da foto

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

Debugando:

:picture -> model para onde enviaremos o form
onchange: ‘this.form.submit()’; -> com isso, fazemos que o próprio botão de escolha da foto seja o mesmo de submit.
gallery_update_picture_path -> Rota para atualizarmos uma imagem no banco

post '/user/dashboard/gallery/update/:pic_id', to: 'user/dashboard/galleries#update', as: :gallery_update_picture

II-Relacionamento de fotos e artes

Adicionar relação

<%= link_to gallery_insert_related_path(art.id, @image.id) %>
    <button> Adicionar </button>
<% end %>

Debugando:

art -> Para exibimos todas as artes do usuário no carrosel, fizemos um:

<% arts.each do |art| %>
<%= link_to gallery_insert_related_path(art.id, @image.id) %>
<button> Adicionar </button>
<% end %>
<% end %>

PS: Por isso que acessamos a variável “art”. Além disso, @arts = @store.arts, sendo @store a variável que instanciamos através do before_action

gallery_insert_related_path -> Rota para chamarmos a action de criação do relacionamento

get '/user/dashboard/gallery/insert_related/:art_id/:pic_id', to: 'user/dashboard/galleries#insert_related', as: :gallery_insert_related

Remover relação

<%= link_to gallery_remove_related_path(art.id, @image.id) %>
    <button> Remove </button>
<% end %>

Debugando:

gallery_remove_related_path -> Rota deletarmos uma associação do model GalleryRelatedPicture

get '/user/dashboard/remove_related/:art_id/:pic_id', to: 'user/dashboard/galleries#remove_related', as: :gallery_remove_related

c)Controller

app > controllers > user > dashboard > galleries_controller.rb

I-Criando a galeria de cada loja

Para criarmos uma galeria para o usuário, utilizamos o método before_action do rails. Com ele, assim que o usuário acessa a página do seu respectivo controller, antes de tudo, é executada uma ação.

Nossa lógica então foi fazer o seguinte: Assim que o usuário acessar a galeria através de seu dashboard, faremos:

app/controllers/galleries_controller.rb

class User::Dashboard::GalleriesController > ApplicationController
    before_action :load_store_and_galley
….

private
def load_store_and_gallery
    load_gallery
    load_store
end 

def  load_gallery
    @gallery = current_user&.store&.gallery || Gallery.new(store: current_user&.store)
end

def load_store
    @store = current_user&.store
end

Debugando:

current_user -> método nativo do rails para sabermos qual o usuário atual que está na nossa aplicação
& -> Com ele, a nossa aplicação não irá quebrar caso uma das chamadas seja “nil”

II-CRUD de fotos

Insert

Como mostramos na view, estamos usando um form_for, passando a rota gallery_upload_path como argumento

form_for

<%= form_for :picture, url: gallery_upload_path do |f| %>

gallery_upload_path

post '/user/dashboard/gallery/', to: 'user/dashboard/galleries#upload', as: :gallery_upload

A action upload, ficou assim:

def upload
    @picture = Picture.new(post_params)
    @picture.gallery = @gallery

    if !@picture.save
        flash[:error] = @picture.errors.messages[:image] 
    end
end


private
def post_params
    params.require(:picture).permit(:image)
end

Debugando:

@gallery -> conseguimos acessar a variável de instância @gallery mesmo sem tê-la chamado neste action pois criamos ele usando o before_action. Logo, todas as actions do controller gallery terão acesso a esta variável
flash[:error] = @picture.errors.message[:image] -> em @picture, estamos instanciando um novo objeto do model Picture, logo ele retornará um ActiveRecord. Com isso, conseguimos acessar alguns métodos de objeto ActiveRecord, entre eles o objeto errors.message. Mas antes de falar sobre este método, mostraremos uma das validações que fizemos neste model.

app > models > picture.rb

validate :validate_image
...
def validate_image
if image.blank?
Errors.add(:image, ‘Por favor, adicione uma imagem’)
return
end
end

Com isso, fazemos com que, caso a imagem venha vazia (submit sem upload), adicionemos um “error” ao objeto Picture que foi instanciado (@picture = Picture.new no nossso caso) e não salvemos a imagem vazia no banco.

Por isso podemos combinar:

if !@picture.save → caso a imagem não seja salva no banco
@picture.errors.message[:image] → chamemos o log de erro que causou o não-salvamento do atributo :image

Update

Também mostrado na view, usamos um form_for passando a rota gallery_update_picture_path.

form_for

<%= form_for :picture, url: gallery_update_picture_path(@image.id) do |f| %>

gallery_update_picture_path

post '/user/dashboard/gallery/update/:pic_id', to: 'user/dashboard/galleries#update', as: :gallery_update_picture

app > controllers > galleries_controller.rb

def update
@picture = Picture.find_by(id: params[:pic_id])

if @picture.update(post_params)
    flash[:error] = @picture.errors.full_messages.first
    end
end

Debugando:

@picture.update -> Como @picture é um objeto ActiveRecord, conseguimos utiizar o método udpate
@picture.errors.full_messages.first -> Como não estamos instanciando um objeto novo no model Picture, a validação validate_image mostrada é executada de forma diferente. A saída que achamos para conseguimos carregar o log dos erros gerados foi usar este método chamado full_messages.first.

Delete

Esse foi o mais simples. Tivemos apenas que criar um link_to para a rota de delete – gallery_delete_picture_path e executar os devidos comandos no controller

link_to

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

gallery_delete_picture

get '/user/dashboard/gallery/delete/:id', to: 'user/dashboard/galleries#delete', as: :gallery_delete_picture

app > controllers > galleries_controller.rb

def delete
    @gallery_picture = Picture.find_by(id: params[:id])

    @gallery_picture.destroy

    redirect_to user_dashboard_gallery_path
end

Debugando:

params[:id] -> ID da imagem que desejamos excluir
.destroy -> método para deletar um objeto ActiveRecord
redirect_to -> método para redirecionamos o usuário para uma rota
user_dashboard_gallery_path ->

get '/user/dashboard/gallery(/:page)', to: 'user/dashboard/galleries#index', as: :user_dashboard_gallery

III-Relacionamento de fotos e artes

Adicionar relação foto – arte

Foi bem simples fazer. Colocamos aquele botão “adicionar” que mostramos na view e, por trás do panos do controller fizemos

app > controllers > galleries_controller.rb

def insert_related
    @picture = Picture.find_by(id: params[:id])
    @related = GalleryRelatedPicture.new(art_id: params[:art_id], picture: @picture, gallery: @gallery)

    @related.save

    flash[:error] = @related.errors.full_messages.first if @related.errors

    redirect_to request.referrer 
end

Debugando:

request.referrer -> Com este método conseguimos chamar a rota que o usuário estava antes da sua atual. Em outras palavras, é como dar um “click to go back” na seta para esquerda do seu navegador

Removendo relação foto – arte

A lógica foi bem parecida com adição: colocamos um link_to para a rota de remover relação (gallery_remove_related_path) passando os atributos art.id e @image.id nesta rota.

gallery_remove_related_path

get '/user/dashboard/remove_related/:art_id/:pic_id', to: 'user/dashboard/galleries#remove_related', as: :gallery_remove_related

app > controllers > galleries_controller.rb

def remove_related
    @related = GalleryRelatedPicture.find_by(art_id: params[:art_id], picture_id: params[:pic_id], gallery_id: @gallery.id)

    @related.destroy

    redirect_back(fallback_locatin: root_path)
end

Debugando:

redirect_back(fallback_location: root_path) -> método semalhante ao request.referrer. Caso tenha alguma diferença gritante, gostaríamos de ouvi-la leitor =)

Depois poucas semanas desta feature no ar já temos mais de 1000 fotos no model Picture. A percepção dos usuário foi excelente e temos muito orgulho do impacto dela na loja de cada usuário.

https://www.reserva.ink/owm/gallery

https://www.reserva.ink/blogdocavaco/gallery

https://www.reserva.ink/inspiringgirls/gallery

Ficou alguma dúvida, crítica ou sugestão? Fala com a gente, estamos em busca de criar uma rede de Devs que programem em Rails para compartilhamos cada vez mais nossos aprendizados =)

Abração!