VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cotações e preços B2B

Cotações

Lista, detalha, responde e recusa as cotações B2B recebidas pelo seller.

Uma cotação (RFQ, request for quotation) é um pedido de preço que um comprador B2B faz a um seller antes de comprar. Estas rotas são o lado do seller: ver o que chegou, responder com preços e recusar. A negociação em várias rodadas está em Negociação.

Responda todas as linhas, uma vez cada

respond recusa respostas parciais: o número de item_id distintos precisa ser igual ao número de linhas. Não repita um item_id: a soma do total conta a repetição duas vezes.

Dinheiro em centavos

Todo valor desta página é inteiro em centavos (4000 = R$ 40,00 por unidade).

Listar cotações

Devolve as cotações (pedidos de preço de compradores B2B) dirigidas ao seller do token, da mais nova para a mais antiga. Cada item vem resumido, com item_count no lugar das linhas. Antes de listar, a plataforma marca como expired as cotações respondidas cujo valid_until já passou.

GET/api/v1/vendor/quotesSeller

Listar as cotações do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring
pendingquotednegotiatingacceptedrejectedexpiredconverted
Filtra por situação. Aceita o nome (quoted) ou a letra do banco (Q). Vazio não filtra. Não existe valor all: ele não casa com nada e a lista vem vazia.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso vale 20.

Exemplo de requisição

Resposta

200Cotações do seller

Campos da resposta

quotesobject[]
Cotações da página. Mesmos campos do detalhe, sem items e com item_count.
totalinteger
Total de cotações que casam com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página aplicado.
total_pagesinteger
Número de páginas.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
403Usuário sem perfil de seller.{"error":"vendor profile not found"}

Ver uma cotação

Devolve uma cotação com todas as linhas. Use o id de cada linha como item_id ao responder.

GET/api/v1/vendor/quotes/{id}Seller

Detalhe de uma cotação com as linhas

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

idintegerobrigatório
Id da cotação (inteiro). Letras dão 400 invalid quote id.

Exemplo de requisição

Resposta

200Cotação

Campos da resposta

idinteger
Id da cotação (inteiro, não é UUID).
user_iduuid
Cliente (comprador) que pediu a cotação.
vendor_iduuid
Seller que recebeu o pedido. É sempre o seller do token.
statusstring
pendingquotednegotiatingacceptedrejectedexpiredconverted
Situação da cotação. Veja a tabela de status na página inicial da seção.
notesstring
Observações escritas pelo comprador no pedido.
vendor_notesstring
Sua resposta em texto, gravada em respond. Omitido enquanto vazio.
total_centsinteger
Total da cotação em centavos (soma de offered_price_cents vezes a quantidade). 0 até o seller responder.
valid_untilstring|null
Até quando a oferta vale, RFC 3339 em UTC. Depois disso a cotação passa a expired.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
user_emailstring
E-mail do comprador.
user_namestring
Nome do comprador.
vendor_namestring
Nome da empresa do seller.
item_countinteger
Quantidade de linhas. Vem só na listagem.
itemsobject[]

Linhas da cotação. Vem só no detalhe e depois do respond.

idinteger
Id da linha. É o item_id que você usa em respond.
quote_idinteger
Cotação dona da linha.
product_iduuid
Produto cotado.
quantityinteger
Quantidade pedida.
requested_price_centsinteger|null
Preço unitário que o comprador gostaria de pagar, em centavos. Opcional.
offered_price_centsinteger|null
Preço unitário que o seller ofereceu, em centavos. null antes da resposta.
notesstring
Observação da linha.
product_namestring
Nome do produto.
product_skustring
SKU do produto.
product_priceinteger
Preço de tabela atual do produto, em centavos.

Erros

StatusQuandoCorpo de exemplo
400id não é um inteiro.{"error":"invalid quote id"}
404Não existe cotação com esse id.{"error":"quote not found"}
403A cotação existe, mas é de outro seller.{"error":"quote does not belong to this vendor"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Responder uma cotação

Responde a uma cotação pending com o preço unitário de cada linha. A plataforma calcula o total, grava a validade (7 dias a partir de agora se você não enviar valid_until) e muda o status para quoted. O comprador passa a poder aceitar a oferta.

POST/api/v1/vendor/quotes/{id}/respondSeller

Informar o preço de cada item

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

idintegerobrigatório
Id da cotação (inteiro). Letras dão 400 invalid quote id.

Corpo da requisição

itemsobject[]obrigatório

Um objeto por linha da cotação, sem repetir linhas. Precisa cobrir todas as linhas.

item_idintegerobrigatório
Id da linha (items[].id do detalhe).
offered_price_centsintegerobrigatório
Preço unitário oferecido, em centavos. Zero ou mais.
valid_untilstring
Até quando a oferta vale, RFC 3339. Padrão: 7 dias a partir de agora.
notesstring
Texto da sua resposta para o comprador. Fica em vendor_notes. Vazio mantém o texto anterior.

Exemplo de requisição

Resposta

200Cotação atualizada

Campos da resposta

(corpo)object
A cotação completa, igual ao detalhe, já com status: quoted.

Erros

StatusQuandoCorpo de exemplo
400JSON inválido, id não inteiro ou items vazio.{"error":"at least one item response is required"}
404A cotação não existe.{"error":"quote not found"}
403A cotação é de outro seller.{"error":"quote does not belong to this vendor"}
500Regra de negócio violada. Hoje a plataforma responde 500 em vez de 4xx; o motivo vem em detail. Casos: cotação que não está pending, linha sem preço, preço negativo, item_id que não é da cotação.{"error":"failed to respond to quote","detail":"all quote items must be offered a price (quote has 2 items, response covers 1)"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Recusar uma cotação

Encerra a cotação como rejected. Só funciona enquanto ela está pending ou quoted. Não há corpo e não há campo para o motivo. Para negociar em vez de recusar, use a contraproposta.

POST/api/v1/vendor/quotes/{id}/rejectSeller

Recusar o pedido de preço

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

idintegerobrigatório
Id da cotação (inteiro). Letras dão 400 invalid quote id.

Exemplo de requisição

Resposta

200Cotação recusada

Erros

StatusQuandoCorpo de exemplo
400id não é um inteiro.{"error":"invalid quote id"}
404A cotação não existe.{"error":"quote not found"}
403A cotação é de outro seller.{"error":"quote does not belong to this vendor"}
500A cotação não está pending nem quoted (por exemplo já foi aceita). O motivo vem em detail.{"error":"failed to reject quote","detail":"quote not found or not in rejectable status"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Trilha da proposta

Lista, em modo leitura, os eventos que o comprador gerou ao abrir e decidir a proposta pelo link público (aprovar, recusar ou comentar), com nome, papel, IP e navegador. Serve como prova de quem aceitou o quê. Vem vazio se a proposta nunca foi aberta.

GET/api/v1/vendor/quotes/{id}/proposal/eventsSeller

Eventos de decisão da proposta pública

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

idintegerobrigatório
Id da cotação (inteiro). Letras dão 400 invalid quote id.

Exemplo de requisição

Resposta

200Eventos

Campos da resposta

eventsobject[]

Eventos, na ordem em que ocorreram.

iduuid
Id do evento.
event_typestring
Tipo do evento (por exemplo approve, reject, comment).
actor_namestring
Nome informado por quem decidiu. Omitido se vazio.
actor_rolestring
Cargo ou papel informado. Omitido se vazio.
commentstring
Comentário livre. Omitido se vazio.
ipstring
IP de origem. Omitido se vazio.
user_agentstring
Navegador. Omitido se vazio.
created_atstring
Quando ocorreu, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
400id não é um inteiro.{"error":"invalid quote id"}
404A cotação não existe.{"error":"quote not found"}
403A cotação é de outro seller.{"error":"quote does not belong to this vendor"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Veja também

  • Negociação em rodadas
  • Regras de preço B2B
  • Visão geral da seção
Anterior
Cotações e preços B2B
Próxima
Negociação em rodadas
Nesta página
  • Listar cotações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver uma cotação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Responder uma cotação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Recusar uma cotação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Trilha da proposta
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/quotes?status=pending&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/quotes/69" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/quotes/69/respond" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "item_id": 98,
      "offered_price_cents": 4000
    }
  ],
  "valid_until": "2026-10-18T14:00:00Z",
  "notes": "Preço válido para pagamento à vista."
}'
bash
curl -X POST "$BASE_URL/api/v1/vendor/quotes/69/reject" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/quotes/69/proposal/events" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "quotes": [
    {
      "id": 68,
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "pending",
      "notes": "",
      "total_cents": 0,
      "created_at": "2026-10-10T20:16:16Z",
      "updated_at": "2026-10-10T20:16:16Z",
      "user_email": "maria.souza@example.com",
      "user_name": "Maria Souza",
      "vendor_name": "Loja Exemplo",
      "item_count": 1
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
json
{
  "id": 69,
  "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "quoted",
  "notes": "Preciso de 5 unidades para uma reposição de estoque.",
  "vendor_notes": "Preço válido para pagamento à vista.",
  "total_cents": 20000,
  "valid_until": "2026-10-18T14:00:00Z",
  "created_at": "2026-10-11T13:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z",
  "user_email": "maria.souza@example.com",
  "user_name": "Maria Souza",
  "vendor_name": "Loja Exemplo",
  "items": [
    {
      "id": 98,
      "quote_id": 69,
      "product_id": "c7bc3778-2c79-4561-b9d7-979768f364c8",
      "quantity": 5,
      "offered_price_cents": 4000,
      "notes": "",
      "product_name": "Notebook Plus Rosa",
      "product_sku": "SD-000507",
      "product_price": 6990
    }
  ]
}
json
{
  "id": 69,
  "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "quoted",
  "notes": "Preciso de 5 unidades para uma reposição de estoque.",
  "vendor_notes": "Preço válido para pagamento à vista.",
  "total_cents": 20000,
  "valid_until": "2026-10-18T14:00:00Z",
  "created_at": "2026-10-11T13:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z",
  "user_email": "maria.souza@example.com",
  "user_name": "Maria Souza",
  "vendor_name": "Loja Exemplo",
  "items": [
    {
      "id": 98,
      "quote_id": 69,
      "product_id": "c7bc3778-2c79-4561-b9d7-979768f364c8",
      "quantity": 5,
      "offered_price_cents": 4000,
      "notes": "",
      "product_name": "Notebook Plus Rosa",
      "product_sku": "SD-000507",
      "product_price": 6990
    }
  ]
}
json
{
  "message": "quote rejected"
}
json
{
  "events": [
    {
      "id": "7b0f5f7e-9c0c-4d2c-8c55-2d0d6f7b1a11",
      "event_type": "approve",
      "actor_name": "Maria Souza",
      "actor_role": "Compradora",
      "comment": "De acordo.",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0",
      "created_at": "2026-10-12T09:30:00Z"
    }
  ]
}