Atualizações da API Invoices
Nas versões anteriores da API Stripe, a API Invoices não tinha status, e sim vários parâmetros booleanos, como closed
, paid
e forgiven
.
Introduzimos status nas faturas para melhorar a associação entre as faturas da Stripe e o trabalho do departamento financeiro. Agora, todos os objetos Invoice têm uma propriedade status
, que pode ter os valores draft
, open
, paid
, void
e uncollectible
.
- O status
draft
indica que a fatura pode ser alterada. - O status
open
indica que a fatura foi finalizada, não pode mais ser alterada e está pronta para pagamento. - O status
paid
indica que a fatura foi paga integralmente. - O status
void
indica que a fatura não é mais válida. - O status
uncollectible
que a fatura dificilmente será paga e pode ser considerada dívida incobrável.
Para obter mais detalhes sobre os status e as transições entre eles, consulte o guia de faturamento.
Exemplos de cronogramas de fatura
Esta seção apresenta exemplos de cronogramas para faturas avulsas e de assinaturas, mostrando os status que os dois tipos de fatura podem assumir.
Exemplo de fatura isolada
Este é um exemplo de um possível cronograma para uma fatura isolada. Essa sequência de eventos é igual ao cronograma de faturamento atual, exceto que a Stripe disponibiliza um campo status
para representar mais claramente o status de uma fatura.
- 16 de novembro: usando a API, você pode criar uma fatura que representa o envio de 12 widgets para um cliente. A Stripe envia um webhook
invoice.created
para notificar sobre a criação da fatura. Olhando para a API, você nota que a fatura temstatus='draft'
. - 26 de novembro: um contador revisa e finaliza a fatura no Stripe Dashboard. Na finalização da fatura, o status é atualizado para
status='open'
, e o campofinalized_at
é definido. A Stripe envia um webhookinvoice.finalized
para notificar sobre a finalização da fatura. - 26 de novembro: alguns segundos depois, a Stripe envia a fatura por e-mail e começa a fazer novas tentativas. Sempre que uma fatura é enviada, a Stripe envia um webhook
invoice.sent
para ajudar o seu sistema de CRM a acompanhar as faturas. - 1º de dezembro: seu cliente clica no link no e-mail e paga a fatura usando uma página de pagamento de fatura hospedada. Infelizmente, ele usa um cartão de crédito vencido. O pagamento falha e a Stripe envia o webhook
invoice.payment_failed
para notificar sobre a falha. - 3 de dezembro: o cliente tenta pagar novamente com um cartão de crédito atualizado. Desta vez, o pagamento é bem-sucedido. A Stripe envia o webhook
invoice.paid
para notificar o pagamento, salva o cartão e altera o status da fatura parastatus='paid'
. É possível configurar o envio imediato do recibo de pagamento da fatura ao cliente por e-mail.
Exemplo de fatura de assinatura
Veja este exemplo de cronograma de uma fatura gerada por assinatura.
- 13 de novembro: usando o Dashboard, você cria uma assinatura recorrente para um cliente, configurada com cobrança automática. A assinatura tem uma avaliação de 20 dias, então a primeira fatura será emitida 20 dias depois (3 de dezembro). A Stripe envia um webhook
customer.subscription.created
.
- 30 de novembro: três dias antes do final da avaliação, a Stripe envia um webhook
customer.subscription.trial_will_end
. Três dias antes de cobrar o cartão de crédito é um bom momento para enviar um e-mail de lembrete de avaliação.
- 3 de dezembro: uma fatura com
status='draft'
é criada no final da avaliação. A Stripe envia um webhookinvoice.created
para notificar sobre a criação da fatura. - 3 de dezembro: após aproximadamente uma hora, a fatura é finalizada automaticamente. Com isso, o Billing muda
status
'open'
, definefinalized_at
e envia o webhookinvoice.finalized
. - 3 de dezembro: logo depois, a Stripe tenta cobrar o cartão cadastrado do cliente. O pagamento é bem-sucedido. A Stripe envia o webhook
invoice.paid
para notificar sobre o pagamento e altera o status da fatura parastatus='paid'
.
Novos métodos de API
A Stripe lançou um pacote de novas APIs para gerenciar o status de uma fatura. As novas opções, detalhadas na lista de verificação de ugprade abaixo, são:
- Enviar uma fatura: a Stripe envia e reenvia automaticamente as faturas por e-mail. Esse endpoint, disponível na API Stripe, permite enviar a fatura ao cliente sempre que você quiser.
- Finalizar uma fatura: no exemplo acima, o contador finalizou a fatura no Stripe Dashboard. Essa funcionalidade também está disponível na API Stripe.
- Anular uma fatura: não é possível excluir uma fatura finalizada. Uma fatura é anulada para indicar que foi emitida com erros. Você pode anular uma fatura em que o nome da empresa está errado e criar outra fatura para substituí-la.
- Excluir um rascunho de fatura: esta ação se aplica apenas a rascunhos de faturas. Faturas excluídas não são visíveis no Dashboard ou na API e não é possível desfazer sua exclusão.
- Marcar uma fatura como incobrável: o departamento de contabilidade pode manter um cadastro de “débitos duvidosos”, ou seja, uma lista de faturas consideradas incobráveis. Você pode usar essa API para marcar as faturas aplicáveis.
Lista de verificação de upgrade
As seções a seguir listam as alterações funcionais no objeto Invoice
e nos webhooks associados à fatura.
Objeto Invoice
A Stripe adicionou vários campos ao objeto Invoice
para ajudar os usuários a entender melhor o status e comportamento das faturas.
finalized_at
O novo campo finalized_at
indica o momento em que a fatura foi finalizada. Ele está disponível para solicitações realizadas em todas as versões da API.
status
O novo campo status
está disponível para solicitações feitas em todas as versões de API e substitui vários booleanos da fatura, como:
- Para solicitações realizadas na versão 2018-11-08 ou posterior, o booleano
paid=true
foi removido. Em seu lugar, use o equivalentestatus='paid'
. - Para solicitações realizadas na versão 2018-11-08 ou posterior, o booleano
forgiven=true
foi removido. Em seu lugar, use o equivalentestatus='uncollectible'
.
auto_advance
O novo campo auto_advance
indica se a cobrança automática está ativa. Nos status 'draft'
e 'open'
, o campo auto_advance
pode ser atualizado. Caso contrário, auto_advance
será sempre false
.
Com auto_advance=false
, a Stripe não executará as seguintes ações:
- Emitir automaticamente rascunhos de fatura
- Enviar automaticamente o e-mail inicial e os e-mails de lembrete sobre faturas
collection_method='send_invoice'
- Tentar pagar automaticamente uma ou mais vezes faturas com
collection_method='charge_automatically'
Mesmo com auto_advance=false
, a Stripe concilia automaticamente as transferências de crédito recebidas. Quando uma transferência faz referência a uma fatura, a transferência de crédito é reconciliada com essa fatura. Caso contrário, a Stripe pesquisa e tenta pagar faturas não pagas.
Em faturas com os status 'uncollectible'
, 'void'
e 'paid'
, o campo auto_advance
é sempre false
.
Em versões anteriores à 2018-11-08, o campo closed
continua presente e é o inverso de auto_advance
. Por exemplo, auto_advance=true
é equivalente a closed=false
(e vice-versa). Faturas criadas com versões anteriores da API continuarão a assumir o padrão de closed=false
.
Webhooks
Nesta atualização, introduzimos três novos webhooks:
invoice.finalized
: enviado quando uma fatura é finalizada.invoice.voided
: enviado quando uma fatura é anulada.invoice.marked_uncollectible
: enviado quando uma fatura é marcada como incobrável.
O webhook invoice.created
é enviado quando uma fatura é criada. Se o seu gerenciador de webhooks precisa diferenciar entre faturas isoladas e faturas geradas por uma assinatura, verifique a existência da propriedade invoice.subscription
no corpo do webhook.
Estes webhooks já existentes não foram alterados:
invoice.sent
: enviado quando uma fatura é enviada por e-mail a um usuário de forma automática usando a API ou de forma manual usando o Dashboard.invoice.deleted
: enviado quando uma faturadraft
é excluída usando a API ou o Dashboard.invoice.paid
ouinvoice.payment_failed
: enviado quando uma tentativa de pagar uma fatura é bem-sucedida ou falha.