Como funcionam as cotações
Saiba mais sobre o ciclo de vida da cotação.
Observação
You can use quotes in a sandbox. To finalize, download, or accept quotes in live mode for one-time invoices through the API or Dashboard, you must upgrade to Invoicing Plus. See which plan is right for you.
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..
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 |
draft | POST /v1/quotes/:id/finalize | quote. | open |
open | POST /v1/quotes/:id/cancel | quote. | canceled |
open | POST /v1/quotes/:id/accept | quote. | 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_ 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_ 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. Você pode marcar uma cotação como aceita na API como mostrado no exemplo a seguir.
Cancelar uma cotação
Cotações com status draft ou open podem ser canceladas. Cancele uma cotação usando o Dashboard na página de detalhes da cotação ou usando a API como mostrado 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.