📘

O que você irá aprender com esse artigo?

• O que é upgrade de plano e pro rata
• Retirar o cartão padrão vinculado a um cliente
• Como não cobrar pro rata ao alterar o plano de uma assinatura
• Realizar uma cobrança parcelada

Caso de uso

“Cliente entra no site e gostaria de realizar a alteração do plano mensal para o plano anual. Além disso, ele quer que o valor da assinatura anual seja parcelado.”

Diagrama de sequência

O que é upgrade de plano e pro rata

O plano é o motor de recorrência de uma assinatura, onde é definido o ciclo e o intervalo, por exemplo. Quando há necessidade de alterar esse plano por outro de valor maior, chama-se de upgrade de plano. Por outro lado, o downgrade é quando o plano é alterado por outro de valor menor. Essa manobra é muito utilizada principalmente quando é preciso mudar o intervalo da assinatura, como alterar de um plano mensal para outro anual.

O processo de alteração de um plano gera um proporcional chamado de pro rata. Na iugu não geramos crédito para o cliente, então no caso de downgrade é acrescentado ciclos na assinatura e no caso de upgrade é gerado uma fatura com o valor do plano menos o valor que sobrou do plano anterior.

Em alguns casos, o cliente não deseja cobrar o proporcional do assinante no upgrade de plano e é esse cenário que será mostrado aqui.

Retirar o cartão padrão vinculado a um cliente

Quando uma assinatura está vinculada a um cartão padrão do cliente, a cobrança ocorre de forma automática, então antes de alterar o plano é preciso retirar o default desse cartão, permitindo que a assinatura possa ser parcelada. Essa ação não remove o cartão do cliente, apenas não deixa o cartão como padrão para que a cobrança não seja feita de forma automática. Para isso, é necessário realizar um PUT (alteração) nos dados do cliente, informando o "default_payment_method_id" como null. Essa ação basicamente diz ao sistema que não há nenhum cartão padrão para esse cliente.

Modelo de request

curl --location --request PUT 'https://api.iugu.com/v1/customers/{{customer_id}}' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=446cf58091d5c77ed010bb0bbcbd02325b22e054-1633348012' \ 
--data-raw '{ 
    "default_payment_method_id": null 
}'

Modelo de response

Como não cobrar pro rata ao alterar o plano de uma assinatura

Após isso, o plano vinculado a assinatura pode ser alterado. Ao invés de usar a chamada de alteração de plano, nesse cenário de não cobrança do proporcional, é necessário fazer uma alteração diretamente na assinatura. Dessa forma, basta realizar um PUT na assinatura alterando o "plan_identifier" que é o identificador do plano e enviar o skip_charge como true.

Modelo de request

curl --location --request PUT 'https://api.iugu.com/v1/subscriptions/{{subscription_id}}' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=446cf58091d5c77ed010bb0bbcbd02325b22e054-1633348012' \ 
--data-raw '{ 
    "plan_identifier": "anual_1633349010", 
    "skip_charge": true 
}'

Modelo de response

Em resumo, o plan_identifier identifica o novo plano vinculado e o skip_charge impede que uma cobrança de pro rata seja feita.

No retorno dessa chamada será exibido o id da fatura que será usado no próximo passo, então acesse o callback da requisição e pegue o id da invoice que consta no "recent_invoices".

OBS: É importante ressaltar a forma como a iugu realiza a cobrança das assinaturas para que fique claro os cenários que podem ocorrer nessa alteração de plano. A iugu executa um job às 11hs que realiza a cobrança das faturas e outro às 13hs que é responsável pela criação das faturas. Essa informação é importante, pois influencia na criação da fatura quando a alteração de plano é feita. Se uma nova data de vencimento for informada, a fatura será gerada nessa data ou alguns dias antes dependendo dos dias de faturamento que tiver sido informado no plano. Se, por exemplo, a assinatura tiver data de vencimento para o mesmo dia que está sendo feita a alteração e essa mudança estiver sendo realizada depois das 13hs, a fatura não será gerada e no dia seguinte, que deveria gerar a fatura no job das 13hs, a assinatura estará como vencida, pois já passou da data de validade.

Quando uma fatura é paga, o próximo ciclo ocorre no mês seguinte (se for plano mensal) ou no próximo ano (se for plano anual).Por exemplo, supondo que a assinatura possui data de validade 03 de outubro e a fatura foi paga, sendo assim, o próximo ciclo fica automaticamente para o dia 03 de novembro. Se houve alguma alteração de plano depois desse pagamento, sem que a data de validade seja modificada, a próxima fatura será gerada no mês seguinte respeitando os dias de faturamento do novo plano.

Considerando os pontos acima, se a fatura não for gerada na alteração de plano é possível acessar o id da fatura consultando a assinatura ou através dos gatilhos. Uma forma de garantir que a fatura seja gerada é alterar a data de vencimento para a quantidade de dias correspondente ao faturamento do plano, exemplo: plano tem 2 dias de faturamento, se a alteração está sendo feita dia 02 de Outubro, então o vencimento pode ser alterado para 04 de Outubro.

Realizar uma cobrança parcelada

Quando a fatura do novo plano for gerada não será cobrada automaticamente do cliente, pois não há cartão padrão vinculado a ele. Para configurar o parcelamento da assinatura utilize o id da fatura que pode ser capturado no retorno de alteração do plano ou na consulta da assinatura (no campo recent_invoices) e realize uma chamada na API de cobrança direta passando o identificador do cartão do cliente, o id da fatura e a quantidade de parcelas.

📘

Parcelamento

Para permitir parcelamento é necessário que a conta tenha parcelamento configurado. Para habilitar o parcelamento da conta, acesse o painel da conta iugu e clique em: Configurações >> Cartão de Crédito >> Parcelas. Ou consulte aqui como realizar esse procedimento.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/charge' \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=446cf58091d5c77ed010bb0bbcbd02325b22e054-1633348012' \ 
--data-raw '{ 
    "customer_payment_method_id": "{{id_forma_de_pagamento}}", 
    "invoice_id": "6CD4B94FF6244DF8889608514525B742", 
    "months": 2 
}'

Modelo de response

Essa chamada permitirá que a fatura seja cobrada e que o número de parcelas seja configurado.

É importante salientar que no caso de assinatura parcelada sempre será necessário realizar a chamada na API de cobrança direta quando a nova fatura tiver sido gerada. Para isso, é necessário habilitar o gatilho de invoice.created para receber a notificação de criação da fatura nas próximas cobranças e com isso recuperar o id da invoice para realizar a captura na API de cobrança direta.

Para saber mais sobre como criar o gatilho, clique aqui.

Modelo de gatilho

Das informações que o gatilho envia, é necessário recuperar o id da invoice e informa-lo no body da requisição da cobrança direta.