VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Cotações e propostas B2B

Como o cliente pede um preço especial a um seller, negocia e fecha, ou aprova por link sem login.

Em vendas B2B o preço raramente é o de tabela: o comprador pede uma cotação (em inglês, RFQ, request for quotation), o seller responde com preços e prazos, e só depois o pedido nasce. Esta seção cobre o lado do cliente nesse fluxo, incluindo a negociação em rodadas e a proposta por link, que deixa uma pessoa sem conta aprovar a compra.

Pontos-chave
  • Cotação, negociação e itens exigem o token do cliente e o módulo b2b-pricing (a negociação também exige enhanced-rfq). Módulo desligado devolve 403 module_disabled.
  • O id da cotação é um inteiro; o de rodada e de carrinho é UUID.
  • Preços sempre em centavos (4990 = R$ 49,90).
  • Aceitar uma cotação não cria pedido: ela vai para o carrinho e o cliente fecha no checkout.
  • As rotas de proposta por link são públicas; o token do link é o segredo.

Como funciona

O ciclo de uma cotação:

Pendente→Respondida→Aceita→Convertida
statusSignificadoQuem move
pendingO cliente pediu; o seller ainda não respondeu.Cliente (cria)
quotedO seller respondeu com preços e, em geral, uma validade (valid_until).Seller
negotiatingHá rodadas de contraproposta em andamento (módulo enhanced-rfq).Cliente ou seller
acceptedO cliente (ou quem aprovou pelo link) aceitou os preços.Cliente
convertedOs itens foram para o carrinho. Fim do caminho da cotação.Cliente
rejectedRecusada pelo cliente ou pelo seller.Cliente ou seller
expiredPassou do valid_until sem decisão.Automático, na leitura

O fluxo de integração típico:

  1. Pedir a cotação

    O cliente escolhe um seller e produtos dele: Pedir cotação.

  2. Esperar a resposta do seller

    Consulte a cotação até o status virar quoted. Se a loja envia a proposta por link, o cliente também recebe o link por e-mail.

  3. Decidir ou negociar

    Aceite ou recuse direto, ou negocie em rodadas.

  4. Levar ao carrinho e fechar

    A cotação aceita vai ao carrinho com os preços acordados; o cliente segue pelo checkout normal da loja.

Conceitos-chave

Uma cotação, um seller

Uma cotação sempre pertence a um seller (lojista) e só aceita produtos dele. Para comprar de dois sellers, abra duas cotações.

Preço oferecido x preço de tabela

Cada linha tem product_price (tabela hoje), requested_price_cents (o que o cliente sugeriu) e offered_price_cents (o que o seller topou). Ao ir para o carrinho vale o oferecido; se o seller não definiu preço na linha, vale o de tabela.

Validade e expiração

O seller pode fixar valid_until. Não existe tarefa agendada: a cotação é marcada expired na primeira leitura depois do prazo, e accept e conversão recusam cotação vencida.

Aprovação por conta ou por link

Quem tem conta usa as rotas autenticadas (accept, convert-to-order). Quem não tem usa a proposta por link. As duas levam a cotação a accepted.

Endpoints

Método e caminhoPara quêAutenticaçãoPágina
POST /api/v1/storefront/quotesCria uma cotaçãoToken do clientePedir e consultar cotações
GET /api/v1/storefront/quotesLista as cotações do clienteToken do clientePedir e consultar cotações
GET /api/v1/storefront/quotes/{id}Detalhe de uma cotaçãoToken do clientePedir e consultar cotações
POST /api/v1/storefront/quotes/{id}/acceptAceita a cotaçãoToken do clienteDecidir uma cotação
POST /api/v1/storefront/quotes/{id}/rejectRecusa a cotaçãoToken do clienteDecidir uma cotação
POST /api/v1/storefront/quotes/{id}/convert-to-orderAceita e leva ao carrinho em um passoToken do clienteDecidir uma cotação
POST /api/v1/storefront/quotes/{id}/counterContraproposta do clienteToken do clienteNegociar em rodadas
GET /api/v1/storefront/quotes/{id}/negotiationsHistórico de rodadasToken do clienteNegociar em rodadas
POST /api/v1/storefront/quotes/{id}/accept-round/{roundId}Aceita uma rodadaToken do clienteNegociar em rodadas
POST /api/v1/storefront/quotes/{id}/reject-round/{roundId}Recusa uma rodadaToken do clienteNegociar em rodadas
POST /api/v1/storefront/quotes/{id}/convert-to-cartLeva a cotação aceita ao carrinhoToken do clienteNegociar em rodadas
GET /api/v1/storefront/quote-proposals/{token}Abre a proposta pelo linkPúblicaProposta por link (sem login)
GET /api/v1/storefront/quote-proposals/{token}/pdfBaixa o PDF da propostaPúblicaProposta por link (sem login)
POST /api/v1/storefront/quote-proposals/{token}/approveAprova a propostaPúblicaProposta por link (sem login)
POST /api/v1/storefront/quote-proposals/{token}/rejectRecusa a propostaPúblicaProposta por link (sem login)
POST /api/v1/storefront/quote-proposals/{token}/commentComenta a propostaPúblicaProposta por link (sem login)

Erros comuns

O que costuma dar errado
  1. Tratar o id da cotação como UUID. É inteiro.
  2. Mandar produtos de dois sellers na mesma cotação: o primeiro que não for do vendor_id derruba a criação inteira (volta 500 com detail).
  3. Esperar um pedido depois de convert-to-order. A rota só preenche o carrinho.
  4. Ignorar 403 module_disabled: a loja pode não ter b2b-pricing (ou enhanced-rfq para negociar).
  5. Oferecer "Aceitar" numa cotação vencida. Confira status e valid_until antes de mostrar o botão.
  6. Guardar o link da proposta em log ou analytics: o token dá acesso à cotação e à decisão.

Próximos passos

Pedir e consultar cotações
Abra e acompanhe a cotação.
Decidir uma cotação
Aceite, recuse ou vá ao carrinho.
Proposta por link (sem login)
Aprovação sem login por link.
Anterior
Planos disponíveis
Próxima
Pedir e consultar cotações
Nesta página
  • Como funciona
  • Conceitos-chave
  • Uma cotação, um seller
  • Preço oferecido x preço de tabela
  • Validade e expiração
  • Aprovação por conta ou por link
  • Endpoints
  • Erros comuns
  • Próximos passos