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

Cotações B2B

Pedidos de cotação de clientes empresa, propostas formais com link de aceite e negociação em rodadas.

No comércio B2B (empresa vende para empresa), comprar é raramente um clique: o comprador pede um preço, o seller responde, os dois ajustam e só então o pedido acontece. A plataforma modela isso com a cotação (RFQ, "request for quotation"). Esta área é a visão do administrador sobre essas cotações.

São as rotas do administrador da loja. O cliente pede a cotação pela vitrine e o seller responde pelo painel dele.

Pontos principais
  • Cotações, propostas: módulo b2b-pricing ativo e manage_b2b ou manage_orders. Negociações: módulo enhanced-rfq ativo e manage_orders.
  • O id de uma cotação é um número inteiro, não um UUID.
  • Valores em centavos. Os preços oferecidos são unitários; total_cents é o total da cotação.
  • O administrador só pode recusar uma cotação. Responder com preços é do seller; aceitar é do cliente.
  • Ler uma cotação pode marcá-la como expired, se a validade já passou.

Como funciona

Pendente→Respondida→Aceita→Convertida em carrinho
statusSignificado
pendingO cliente pediu; o seller ainda não respondeu.
quotedO seller respondeu com preços e uma validade (valid_until).
negotiatingCliente e seller estão trocando contrapropostas em rodadas.
acceptedO cliente (ou o decisor, pela proposta formal) aceitou.
convertedA cotação aceita virou carrinho do cliente.
rejectedRecusada (pelo cliente, pelo seller ou pelo administrador).
expiredA validade passou sem decisão.

Para o decisor da empresa aprovar sem ter conta, o administrador ou o seller gera uma proposta formal: um PDF e um link com chave secreta.

Conceitos-chave

Preço pedido e preço oferecido

Cada item tem requested_price_cents (o que o cliente quer pagar, opcional) e offered_price_cents (o que o seller aceita cobrar), ambos por unidade. O product_price é o preço de tabela, só para comparação.

Rodadas

Na negociação, cada contraproposta é uma rodada numerada. Há um máximo de rodadas por cotação (max_rounds, padrão 5).

Mediação

O administrador pode marcar uma negociação como mediada e deixar uma nota. É uma anotação interna.

Endpoints

MétodoCaminhoPara que servePágina
GET/api/v1/admin/quotesListar cotaçõesCotações
GET/api/v1/admin/quotes/{id}Consultar uma cotaçãoCotações
PUT/api/v1/admin/quotes/{id}Recusar uma cotaçãoCotações
POST/api/v1/admin/quotes/{id}/proposalGerar proposta formalPropostas
DELETE/api/v1/admin/quotes/{id}/proposalRevogar o linkPropostas
GET/api/v1/admin/quotes/{id}/proposal/eventsTrilha de eventosPropostas
GET/api/v1/admin/rfq/negotiationsListar negociaçõesNegociações
GET/api/v1/admin/rfq/negotiations/{id}Consultar negociaçãoNegociações
PATCH/api/v1/admin/rfq/negotiations/{id}Anotar a negociaçãoNegociações

Erros comuns

  • Tratar o id como UUID. É um inteiro; outro formato responde 400.
  • Esperar que PUT aceite outros estados. Só rejected é aceito.
  • Gerar proposta de uma cotação que não está quoted. Responde 400.
  • Compartilhar o token ou a public_url com a pessoa errada. Quem tem o link aprova ou recusa. Revogue se isso acontecer.
  • Esperar 404 ao recusar uma cotação inexistente. Responde 500 com a explicação em detail.
  • Anotar uma negociação sem conferir o id. Um id inexistente devolve 200 com null.

Próximos passos

Cotações
Liste, consulte e recuse cotações.
Propostas formais
Gere o PDF e o link de aceite.
Negociações (RFQ)
Acompanhe as rodadas de contraproposta.
Anterior
Geração em lote e usos
Próxima
Cotações
Nesta página
  • Como funciona
  • Conceitos-chave
  • Preço pedido e preço oferecido
  • Rodadas
  • Mediação
  • Endpoints
  • Erros comuns
  • Próximos passos