# Pagamentos Recorrentes - Desenvolvedor: EDD_Subscription
##### Índice
- [Propriedades](#properties)
- [Métodos](#methods)
- [Uso](#usage)
- [Modificação de Objeto](#modification)
- [Métodos Operacionais](#operational)
- [Obtendo Informações da Assinatura](#getters)
- [Condicionais de Assinatura](#conditionals)
- [Métodos de Status](#status)
[Pagamentos Recorrentes](https://easydigitaldownloads.com/downloads/recurring-payments/) vem com uma nova classe EDD para gerenciar assinaturas. A classe EDD\_Subscription permite que um desenvolvedor trabalhe com assinaturas programaticamente. Este documento listará as propriedades, métodos e funcionalidades sugeridas da EDD\_Subscription.
### Propriedades
- $id = 0;
- $customer\_id = 0;
- $period = '';
- $initial\_amount = '';
- $recurring\_amount = '';
- $bill\_times = 0;
- $parent\_payment\_id = 0;
- $product\_id = 0;
- $created = '0000-00-00 00:00:00';
- $expiration = '0000-00-00 00:00:00';
- $status = 'pending';
- $profile\_id = '';
- $gateway = '';
- $customer;
### Métodos
- create( $data = array() )
- update( $args = array() )
- delete()
- get\_original\_payment\_id()
- get\_child\_payments()
- get\_total\_payments()
- get\_lifetime\_value()
- add\_payment( $args = array() )
- renew()
- complete()
- expire()
- failing()
- cancel()
- can\_cancel()
- get\_cancel\_url()
- can\_update()
- get\_update\_url()
- is\_active()
- is\_expired()
- get\_expiration()
- get\_expiration\_time()
- get\_status()
- get\_status\_label()
- payment\_exists( $txn\_id = '' )
### Uso
##### Instanciação Básica
Um objeto EDD\_Subscription "vazio" pode ser criado com este código:
```
$subscription = new EDD_Subscription();
```
Isso retornará um objeto com esta estrutura:
```
EDD_Subscription Object
(
[subs_db:EDD_Subscription:private] => EDD_Subscriptions_DB Object
(
[table_name] => wp_edd_subscriptions
[version] => 1.0
[primary_key] => id
)
[id] => 0
[customer_id] => 0
[period] =>
[initial_amount] =>
[recurring_amount] =>
[bill_times] => 0
[parent_payment_id] => 0
[product_id] => 0
[created] => 0000-00-00 00:00:00
[expiration] => 0000-00-00 00:00:00
[status] => pending
[profile_id] =>
[gateway] =>
[customer] =>
)
```
##### Instanciando uma Assinatura Existente
O construtor EDD\_Subscription aceita 2 argumentos. O primeiro é um inteiro representando um ID de assinatura ou, se o segundo argumento for verdadeiro, o primeiro pode ser um profile\_id de assinatura.
Você pode encontrar um ID de assinatura na URL ao visualizar uma assinatura. 
Você pode encontrar o ID do perfil listado ao visualizar uma assinatura. 
Estas duas linhas de código retornarão a mesma saída porque se referem à mesma assinatura:
```
$subscription = new EDD_Subscription( 3 );
```
```
$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );
```
As linhas de código acima retornariam cada uma um objeto como este:
```
EDD_Subscription Object
(
[subs_db:EDD_Subscription:private] => EDD_Subscriptions_DB Object
(
[table_name] => wp_edd_subscriptions
[version] => 1.0
[primary_key] => id
)
[id] => 1
[customer_id] => 3
[period] => month
[initial_amount] => 50.00
[recurring_amount] => 50.00
[bill_times] => 0
[parent_payment_id] => 87
[product_id] => 85
[created] => 2016-03-15 15:36:30
[expiration] => 2016-04-15 23:59:59
[status] => pending
[profile_id] => paypal-363e3cc178dab152bb59b958024bce75
[gateway] => paypal
[customer] => EDD_Customer Object
(
[id] => 3
[purchase_count] => 3
[purchase_value] => 110.000000
[email] => user@example.com
[name] => Bob Smith
[date_created] => 2016-03-08 15:01:02
[payment_ids] => 54,63,87,88,91
[user_id] => 2
[notes] => Array
(
[0] => March 16, 2016 14:37:22 - Subscription #3 cancelled admin
)
[db:protected] => EDD_DB_Customers Object
(
[table_name] => wp_edd_customers
[version] => 1.0
[primary_key] => id
)
)
)
```
#### Modificação de Objeto
Usando os métodos incluídos, quase tudo pode ser feito com uma assinatura.
A menos que declarado o contrário, todos os exemplos de métodos fornecidos usarão este modelo de instanciação:
```
$subscription = new EDD_Subscription();
```
#### Métodos Operacionais
EDD\_Subscription inclui métodos para criar, excluir, atualizar e renovar assinaturas, além de adicionar pagamentos.
##### $subscription->create()
Para criar uma assinatura corretamente, você precisa fornecer algumas informações. Estes itens são obrigatórios:
```
$data = array(
'customer_id' => 0, // um inteiro, deve ser um customer_id válido
'period' => '', // aceita 'day', 'week', 'month' ou 'year'; com que frequência a assinatura é renovada
'initial_amount' => '', // aceita um float
'recurring_amount' => '', // aceita um float
'bill_times' => 0, // aceita um inteiro; o número de vezes que a cobrança deve ocorrer, 0 significa indefinido
'parent_payment_id' => 0, // aceita um inteiro; o ID do pagamento retornado pelo pagamento inicial
'product_id' => 0, // aceita um inteiro; o ID do produto
'created' => '', // aceita uma string de data; formatada como 0000-00-00 00:00:00
'expiration' => '', // aceita uma string de data; formatada como 0000-00-00 00:00:00
'status' => '', // aceita 'Pending', 'Active', 'Cancelled', 'Expired', 'Failing', 'Completed'
'profile_id' => '', // aceita uma string retornada pelo gateway de pagamento como o ID da assinatura deles
);
```
Então você pode chamar o método `create()` com essas informações.
```
$subscription->create( $data );
```
O método `create()` retorna um objeto com os mesmos dados que você obteria consultando um ID de assinatura específico.
#####
##### $subscription->update()
Atualizar uma assinatura usa o método `update()` com qualquer subconjunto das opções de array usadas para o método `create()`. O método `update()` também requer um ID de assinatura. Algo como isto funcionaria:
```
$data = array(
'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );
```
#####
##### $subscription->delete()
O método `delete()` aceita um ID de assinatura e remove permanentemente a assinatura da loja EDD. Observe que isso não afeta as assinaturas registradas nos Gateways de Pagamento. Essas devem ser tratadas individualmente.
##### $subscription->renew()
Este método renova uma assinatura, estendendo-a por um período além da data de expiração atual.
##### $subscription->add\_payment( $args = array() )
Este método permite que você faça um pagamento. Ele aceita um array e requer estes três elementos do array:
- **amount**: o valor em dinheiro pago
- **transaction\_id**: o ID da transação da assinatura do gateway de pagamento. Exemplo: 'ch\_17q04L4NqFpaKRwY8ucZjW3t'
- **gateway**: o gateway de pagamento usado para a assinatura. Exemplo: 'stripe'
Em caso de sucesso, `add_payment()` retorna true.
#### Obtendo Informações da Assinatura
EDD\_Subscription fornece vários métodos para obter informações sobre uma assinatura.
##### $subscription->get\_original\_payment\_id()
Este método retorna um inteiro que é o ID do pagamento original. Na Interface do Usuário, este Pagamento pode ser encontrado em Downloads → Histórico de Pagamentos.
##### $subscription->get\_child\_payments()
O método retorna um array de objetos EDD\_Payment onde cada objeto é um pagamento filho. Os objetos se parecerão com isto:
```
Array
(
[0] => EDD_Payment Object
(
[ID] => 1111111
[_ID:protected] => 1111111
[new:protected] =>
[number:protected] => 1111111
[mode:protected] => live
[key:protected] => 8d6f842jkf66cb6312117b9ad417dc6be
[total:protected] => 57.4
[subtotal:protected] => 57.4
[tax:protected] => 0
[discounted_amount:protected] => 0
[tax_rate:protected] =>
[fees:protected] => Array
(
)
[fees_total:protected] => 0
[discounts:protected] => samplediscount
[date:protected] => 2018-05-17 06:40:29
[completed_date:protected] =>
[status:protected] => edd_subscription
[post_status:protected] => edd_subscription
[old_status:protected] =>
[status_nicename:protected] => Renewal
[customer_id:protected] => 111111
[user_id:protected] => 1nan1
[first_name:protected] => Bob Smith
[last_name:protected] => Smith
[email:protected] => user@example.com
[user_info:EDD_Payment:private] => Array
(
[first_name] => Bob Smith
[last_name] => Smith
[discount] => samplediscount
[id] => 1nan1
[email] => user@example.com
[address] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
)
[payment_meta:EDD_Payment:private] => Array
(
[key] => 8d6f842jkf66cb6312117b9ad417dc6be
[email] => user@example.com
[date] => 2018-05-17 06:40:29
[user_info] => Array
(
[first_name] => Bob Smith
[discount] => samplediscount
[id] => 1nan1
[email] => user@example.com
[address] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
)
[[downloads]] => Array
(
[0] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
)
[cart_details] => Array
(
[0] => Array
(
[name] => Sample Product
[id] => 1234
[item_number] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
[item_price] => 57.4
[quantity] => 1
[discount] => 0
[subtotal] => 57.4
[tax] => 0
[fees] => Array
(
)
[price] => 57.4
)
)
[fees] => Array
(
)
[currency] => USD
)
[address:protected] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
[transaction_id:protected] => 7M999999999999999
[[downloads:protected]] => Array
(
[0] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
)
[ip:protected] => 192.168.1.1
[gateway:protected] => paypalexpress
[currency:protected] => USD
[cart_details:protected] => Array
(
[0] => Array
(
[name] => Sample Product
[id] => 1234
[item_number] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
[item_price] => 57.4
[quantity] => 1
[discount] => 0
[subtotal] => 57.4
[tax] => 0
[fees] => Array
(
)
[price] => 57.4
)
)
[has_unlimited_downloads:protected] =>
[pending:EDD_Payment:private] => Array
(
)
[parent_payment:protected] => 830936
)
)
```
##### $subscription->get\_total\_payments()
Este método retorna um inteiro que é a contagem total de pagamentos feitos, incluindo os pagamentos iniciais mais todos os pagamentos filhos.
##### $subscription->get\_lifetime\_value()
Este método retorna um float que é o total monetário de todos os pagamentos já feitos.
##### $subscription->get\_cancel\_url()
Este método retornará uma URL para cancelar uma assinatura que é processada pelo gateway através do qual a assinatura foi comprada.
##### $subscription->get\_update\_url()
Este método retornará uma URL para atualizar uma assinatura que é processada pelo gateway através do qual a assinatura foi comprada.
##### $subscription->get\_expiration()
Retorna a data e hora em que a assinatura expirará neste formato:
```
2016-04-15 23:59:59
```
##### $subscription->get\_expiration\_time()
Este método retorna um inteiro que é um timestamp Unix da expiração.
##### $subscription->get\_status()
Este método retorna o status atual de uma assinatura em um formato útil para código. As opções são 'pending', 'active', 'cancelled', 'expired', 'failing', 'completed'.
##### $subscription->get\_status\_label()
Este método retorna o status atual de uma assinatura em um formato útil para apresentação. As opções são 'Pending', 'Active', 'Cancelled', 'Expired', 'Failing', 'Completed'.
#### Condicionais de Assinatura
EDD\_Subscription oferece vários métodos condicionais.
##### $subscription->can\_cancel()
Este método retorna um booleano e é filtrado por gateways de pagamento para retornar true em assinaturas que podem ser canceladas com um ID de perfil através do processador de pagamento.
##### $subscription->can\_update()
Este método retorna um booleano e é filtrado por gateways de pagamento para retornar true se a assinatura puder ter seu método de pagamento atualizado. É *apenas* para determinar se um método de pagamento pode ser atualizado.
##### $subscription->is\_active()
Este método retorna um booleano, e é true se a assinatura não expirou
*e* o status é
'active' ou 'cancelled'.
#####
##### $subscription->is\_expired()
Este método retorna um booleano, e é true se a assinatura expirou.
##### $subscription->payment\_exists( $txn\_id = '' )
Este método aceita um ID de transação que foi criado por um gateway de pagamento. Aqui está um exemplo de um ID de transação de assinatura do Stripe:
```
ch_17q04L4NqFpaKRwY8ucZjW3t
```
Este método retorna um booleano, true se ele encontrar uma transação com o ID fornecido.
#### Métodos de Status
EDD_Subscription inclui vários métodos para alterar o status de uma assinatura.
##### $subscription->complete()
Este método altera o status de uma assinatura para 'complete'.
##### $subscription->expire()
Este método altera o status de uma assinatura para 'expired'.
##### $subscription->failing()
Este método altera o status de uma assinatura para 'failing'.
##### $subscription->cancel()
Este método altera o status de uma assinatura para 'cancelled'.