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

bash
curl "$BASE_URL/api/v1/vendor/quotes?status=pending&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cotações do seller
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
}

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

bash
curl "$BASE_URL/api/v1/vendor/quotes/69" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cotação
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
    }
  ]
}

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

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."
}'

Resposta

200Cotação atualizada
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
    }
  ]
}

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

bash
curl -X POST "$BASE_URL/api/v1/vendor/quotes/69/reject" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cotação recusada
json
{
  "message": "quote rejected"
}

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

bash
curl "$BASE_URL/api/v1/vendor/quotes/69/proposal/events" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Eventos
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"
    }
  ]
}

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