Como funcionam as cotações
Observação
Você pode usar cotações no modo de teste, mas precisa fazer o upgrade para o Invoicing Plus ou o Billing Scale para usar todas as funções no modo de produção. Veja qual é o plano adequado para você.
As cotações permitem que você informe os preços estimados de mercadorias e serviços. Além disso, elas podem facilitar a negociação antes do início de uma assinatura ou fatura.
Criamos os status da cotação para refletir um fluxo normal de cotação seguido por um vendedor: a cotação é criada com itens de linha que especificam os itens a serem comprados, incluindo a aplicação de descontos e impostos, o envio da cotação ao cliente em potencial e o provisionamento dos serviços após a aprovação da cotação.
Status | Descrição | Ações possíveis |
---|---|---|
draft | Status inicial para todas as cotações. Neste ponto, ainda é possível editar a cotação. | Finalize a cotação (o status muda para open ) ou cancele-a. |
open | A cotação está finalizada e aguarda a ação do cliente. Agora, é possível editar somente a data de validade. | Marque a cotação como accepted ou cancele-a. |
accepted | O cliente aceitou a cotação. A cotação gera uma fatura, assinatura ou programação de assinatura. | N/D |
canceled | A cotação expirou ou foi cancelada, e você não pode mais aceitá-la. | N/D |
Cotações canceladas
Você pode cancelar uma cotação quando ela é rejeitada pelo cliente ou você quer que ela deixe de ser válida. Você não pode mais aceitar cotações canceladas. Cotações com status draft
ou open
são canceladas automaticamente quando alcançam a data de validade. A Stripe gera um webhook quote.canceled
.
Cotações aceitas
Depois que o cliente concorda com a cotação, você pode marcá-la como aceita. Cotações aceitas geram automaticamente uma fatura, assinatura ou programação de assinatura, dependendo da existência de preços recorrentes na cotação ou de a data efetiva da cotação ser uma data futura.
Transições do fluxo de trabalho
Os status das cotações podem passar por estas transições:
Status | Endpoint da API | Webhook emitido | Status final |
---|---|---|---|
draft | POST /v1/quotes/:id/cancel | quote.canceled | canceled |
draft | POST /v1/quotes/:id/finalize | quote.finalized | open |
open | POST /v1/quotes/:id/cancel | quote.canceled | canceled |
open | POST /v1/quotes/:id/accept | quote.accepted | accepted |
Finalizar cotações provisórias
As cotações são criadas com o status draft
. Nesse status, é possível editar a cotação para fazer as alterações necessárias. Quando estiver tudo pronto para enviar a cotação ao cliente, você pode finalizá-la. O status muda para open
e permanece assim enquanto você aguarda a ação do cliente.
A finalização de uma cotação também atribui a ela um number
. Esse número tem quatro partes: o prefixo QT
, o prefixo de fatura do cliente, a sequência da cotação e a sequência da revisão. Por exemplo, QT-68BB114-0001-1
é a primeira cotação de um cliente, e a cotação está na primeira revisão. A cotação QT-68BB114-0001-2
é a mesma, mas na segunda revisão. QT-68BB114-0002-1
é a segunda cotação do cliente.
Você pode finalizar uma cotação usando a API, como no exemplo a seguir.
Aceitar uma cotação
Somente cotações com status open
podem ser aceitas. Cotações aceitas mudam para o status accepted
e geram uma fatura, assinatura ou programação de assinatura.
Se a cotação não tiver nenhum preço recorrente nos itens de linha, é gerada uma fatura com status draft
e auto_advance
definido como false
. Você pode modificar a fatura antes de finalizá-la e enviá-la para pagamento pelo cliente.
Se a cotação tiver pelo menos um preço recorrente em um item de linha, será criada uma assinatura ou programação de assinatura. Quando a data efetiva da cotação for futura, será criada uma programação de assinatura. Caso contrário, será criada uma assinatura. A primeira fatura da assinatura é criada com o status draft
e auto_advance
definido como true
.
No Dashboard, você pode marcar uma cotação como aceita clicando no botão Converter em fatura ou Converter em assinatura na página de detalhes da cotação. Também é possível marcar uma cotação como aceita usando a API, como no exemplo a seguir.
Cancelar uma cotação
Faturas com status draft
ou open
podem ser canceladas acessando a página de detalhes das faturas no Dashboard ou usando a API, como no exemplo a seguir.
Baixar o PDF de uma cotação
O método PDF funciona de forma diferente da maioria dos métodos SDK com os quais você pode estar acostumado, pois eles costumam retornar dados no formato JSON. Em vez disso, o método PDF tem uma saída única.
Ele retorna diretamente um fluxo de dados que representa as sequências de bytes dos dados recebidos.
Na verdade, em vez de aguardar o carregamento de todo o conjunto de dados, o fluxo de bytes pode ser lido em “pedaços” ou segmentos à medida que os dados são transferidos.
Esse método é particularmente útil para processar dados de grandes quantidades ou em tempo real, em que você pode começar a processar os dados recebidos antes da conclusão de todo o carregamento de dados.