📘

O que você irá aprender com esse artigo?

• Os principais endpoints de Assinatura
• Sequência de Chamadas
• Como criar Plano
• Como criar Cliente
• Como criar Assinatura
• Como criar e Listar Forma de Pagamento

Caso de uso

“Quero poder cobrar meus clientes periodicamente, definindo intervalos específicos entre as cobranças para cada plano, tudo de forma automática via cartão de crédito.”

Recorrência na iugu

O processo de cobranças recorrentes envolve dois passos principais:

1. Criar Plano — v1/plans: são definidos os detalhes da cobrança, como periodicidade e produtos ou serviços associados.
2. Criar Assinatura — v1/subscriptions: que gera cobranças automáticas para os clientes conforme as especificações do plano.

Métodos de Pagamentos Compatíveis

Todos os métodos de pagamento são compatíveis, porém, com comportamentos diferentes.

Cartão de Crédito

Se o seu Plano/Assinatura aceitam Cartão de Crédito (credit_card) como forma de pagamento, então não há a necessidade do cliente fazer o pagamento manual da fatura.

Boleto Bancário

Já para Boleto Bancário (bank_slip), o cliente precisará acessá-lo e pagá-lo manualmente.

Pix

O Pix (pix) conta com a mesma dinâmica do boleto, porém, será via pix.

🚧

Importante

Antes de criar o Plano e/ou Assinatura, certifique-se de que o método escolhido esteja habilitado em sua conta iugu.

Sequência de Chamadas

O passo a passo a seguir simula:

• A contratação de uma assinatura mensal (a cada 1 mês)
• Dados de contato como nome (name) e e-mail (email), foram coletados previamente
• Os dados do cartão de crédito já foram coletados e tokenizados. Saiba mais

1. Criar Plano

Já tem um plano criado? Pule para a etapa 2. Se não, utilize o endpoint Criar Plano — v1/plans. Atente-se aos parâmetros:

• identifier — Identificador do Plano. Utilize-o como uma tag que identifica o plano
• interval_type — Meses (months) ou Semanas (weeks)
• interval — Quantidade de intervalos de Meses ou Semanas

📘

"E como fica uma assinatura anual?"

Simples! O interval_type será do tipo months (meses) e o interval será 12.

Request exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/plans?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "Nome do Plano",
  "identifier": "dev_basic",
  "interval": 1,
  "interval_type": "months",
  "value_cents": 1000,
  "payable_with": [
    "credit_card"
  ],
  "features": [
    {
      "name": "Nome da funcionalidade",
      "identifier": "id_function",
      "value": 1
    }
  ]
}
'

2. Criar um Cliente

Já tem um cliente criado? Pule para a etapa 3. Se não, utilize o Criar Cliente — v1/cutomers. Preencha os parâmetros obrigatórios:

• email — E-mail do cliente
• name — Nome do cliente

Request exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/customers?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "name": "Nome do Cliente"
}
'

3. Criar Forma de Pagamento

Se a forma de pagamento já existe: Utilize o Listar Formas de Pagamento — GET v1/customers/{customer_id}/payment_methods para obter seu id e pule para a etapa 4.

Se não: Utilize o Criar Forma de Pagamento — POST v1/customers/{customer_id}/payment_methods.

Preencha os parâmetros obrigatórios:

• customer_id — ID do Cliente (etapa 2)
• description — Descrição do cartão. Também usado como "apelido" ou "nome do cartão"
• token — Dados do cartão tokenizados (saiba mais)

E escolha se este cartão será a forma de pagamento padrão (favorito) deste cliente ou não:

• set_as_default — true ou false

Request exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/customers/7112C74C949A4195805265251C76ACF6/payment_methods?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "description": "Nome ou Descrição deste Cartão",
  "token": "53dd7091-05c7-4782-9eac-Censurado",
  "set_as_default": true
}
'

4. Criar Assinatura

Utilize o endpoint Criar Assinatura — v1/subscriptions. Atente-se aos parâmetros:

• plan_identifier — Identificador do Plano (identifier etapa 1)
• customer_id — ID do cliente (etapa 2)

O que a Assinatura herda do Plano?

Os parâmetros abaixo, quando não preenchidos nesta chamada, herdam os valores do Plano — POST v1/plans (etapa 1):

• payable_with— do parâmetro payable_with
• price_cents — do parâmetro value do objeto features (ou a soma deles)

👍

only_on_charge_success

Incentivamos a utilização do parâmetro only_charge_on_success como true. Desse modo, a Assinatura será criada apenas se a cobrança inicial for bem-sucedida.

Quando é a primeira cobrança de uma Assinatura

Quando é a primeira vez que esta Assinatura está sendo criada, no retorno deste endpoint será exibido o invoice_id parâmetro recent_invoices.

Quando é a cobrança de uma Assinatura já criada

Já nas próximas cobranças dessa Assinatura, aciona o gatilho Fatura Criada — invoice.created, Mudança de Status da Fatura — invoice.status_changed e Fatura Liberada — invoice.released.

Request exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/subscriptions?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "7112C74C949A4195805265251C76ACF6",
  "plan_identifier": "dev_basic"
}
'

Passo a passo em diagrama

O passo a passo acima pode ser ilustrado com o seguinte diagrama de sequência.

Features complementares

Há outros endpoints que permitem disponibilizar outros recursos aos assinantes. Por exemplo:

Suspender e Reativar Assinatura

Os endpoints abaixo permitem Suspender e/ou Ativar uma Assinatura:

• Ativar Assinatura — v1/subscriptions/{id}/activate
• Suspender Assinatura — v1/subscriptions/{id}/suspend

Upgrade/downgrade de Plano

O endpoint Alterar Plano da Assinatura — v1/subscriptions/{id}/change_plan/{plan_identifier} permite alterar o Plano da Assinatura do assinante.

Gestão de Forma de Pagamento

Os endpoints abaixo permitem a gestão das formas de pagamento:

• Criar Forma de Pagamento — POST v1/customers/{customer_id}/payment_methods
• Remover Forma de Pagamento — DELETE v1/customers/{id}
• Listar Forma de Pagamento — GET v1/customers/{customer_id}/payment_methods
• Editar Cliente — PUT v1/customers/{id} (parâmetro default_payment_method_id)