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

Cotações

Acompanha os pedidos de cotação de clientes B2B e recusa os que não devem seguir.

Em vendas B2B (empresa para empresa), o comprador muitas vezes não paga o preço de tabela: ele pede uma cotação (RFQ, "request for quotation") a um seller com os produtos e as quantidades que quer. O seller responde com os preços que oferece e uma validade. O comprador aceita, e a cotação vira carrinho. O administrador acompanha tudo isso e pode recusar uma cotação.

Pending→Quoted→Accepted→Converted

Saídas alternativas: rejected (recusada) e expired (a validade passou). Em negociação em rodadas, o estado negotiating fica entre pending e accepted.

Listar cotações

Lista os pedidos de cotação de todos os sellers, do mais recente ao mais antigo. Cada linha traz o cliente, o seller, o estado e o total, mas não os itens (use Consultar uma cotação).

GET/api/v1/admin/quotesAdmin

Lista as cotações B2B

Autenticação: Authorization: Bearer <token> de um administrador com manage_b2b ou manage_orders. Requer o módulo b2b-pricing ativo.

Parâmetros de consulta

statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpired
Estado: palavra (pending, quoted, negotiating, accepted, converted, rejected, expired) ou a letra (P, Q, N, A, C, R, E).
vendor_iduuid
Só as cotações de um seller.
user_iduuid
Só as cotações de um cliente.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
De 1 a 100. Fora disso vale 20.

Exemplo de requisição

Resposta

200Cotações devolvidas

Campos da resposta

quotesarray
Cotações da página.
quotes[].idinteger
Identificador numérico da cotação (não é UUID).
quotes[].user_iduuid
Cliente que pediu a cotação.
quotes[].vendor_iduuid
Seller que responde.
quotes[].statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpired
pending (pedida), quoted (o seller respondeu com preços), negotiating, accepted, converted (virou carrinho), rejected, expired.
quotes[].notesstring
Observação do cliente no pedido.
quotes[].vendor_notesstring
Resposta do seller. Omitido se vazio.
quotes[].total_centsinteger
Total da cotação, em centavos.
quotes[].valid_untilstring
Validade da proposta de preços, RFC 3339. Omitido se não definida.
quotes[].created_atstring
Criação, RFC 3339 em UTC.
quotes[].updated_atstring
Última alteração.
quotes[].user_emailstring
E-mail do cliente.
quotes[].user_namestring
Nome do cliente.
quotes[].vendor_namestring
Nome do seller.
quotes[].item_countinteger
Quantidade de itens. Só na listagem.
totalinteger
Total com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"b2b-pricing"} / {"error":"insufficient privileges","required":"manage_b2b"}
500vendor_id/user_id que não é UUID ou falha na consulta{"error":"failed to list quotes","detail":"..."}
Ler também atualiza

Antes de responder, a plataforma marca como expired as cotações cujo valid_until já passou. Por isso updated_at pode mudar numa leitura, e uma cotação que você viu como quoted pode aparecer expired logo depois.

Consultar uma cotação

Devolve a cotação com os itens, os preços pedidos e os preços oferecidos.

GET/api/v1/admin/quotes/{id}Admin

Consulta uma cotação com os itens

Autenticação: Authorization: Bearer <token> de um administrador com manage_b2b ou manage_orders. Requer o módulo b2b-pricing ativo.

Parâmetros de caminho

idintegerobrigatório
Identificador numérico da cotação.

Exemplo de requisição

Resposta

200Cotação devolvida

Campos da resposta

idinteger
Identificador numérico da cotação (não é UUID).
user_iduuid
Cliente que pediu a cotação.
vendor_iduuid
Seller que responde.
statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpired
pending (pedida), quoted (o seller respondeu com preços), negotiating, accepted, converted (virou carrinho), rejected, expired.
notesstring
Observação do cliente no pedido.
vendor_notesstring
Resposta do seller. Omitido se vazio.
total_centsinteger
Total da cotação, em centavos.
valid_untilstring
Validade da proposta de preços, RFC 3339. Omitido se não definida.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.
user_emailstring
E-mail do cliente.
user_namestring
Nome do cliente.
vendor_namestring
Nome do seller.
itemsarray
Itens pedidos. Só no detalhe.
items[].idinteger
Identificador do item.
items[].quote_idinteger
Cotação.
items[].product_iduuid
Produto.
items[].quantityinteger
Quantidade pedida.
items[].requested_price_centsinteger
Preço unitário que o cliente quer pagar, em centavos. Omitido se não pediu.
items[].offered_price_centsinteger
Preço unitário oferecido pelo seller, em centavos. Omitido antes da resposta.
items[].notesstring
Observação do item.
items[].product_namestring
Nome do produto.
items[].product_skustring
SKU do produto.
items[].product_priceinteger
Preço de tabela do produto, em centavos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"b2b-pricing"} / {"error":"insufficient privileges","required":"manage_b2b"}
400id que não é número{"error":"invalid quote id"}
404Cotação inexistente{"error":"quote not found"}

Recusar uma cotação

Muda a cotação para rejected. É a única alteração de estado que o administrador pode fazer aqui: responder com preços é do seller, e aceitar é do cliente. Só cotações pending ou quoted podem ser recusadas.

PUT/api/v1/admin/quotes/{id}Admin

Recusa uma cotação (única mudança permitida ao administrador)

Autenticação: Authorization: Bearer <token> de um administrador com manage_b2b ou manage_orders. Requer o módulo b2b-pricing ativo.

Parâmetros de caminho

idintegerobrigatório
Identificador numérico da cotação.

Corpo da requisição

statusstringobrigatório
rejected
Só aceita rejected.

Exemplo de requisição

Resposta

200Cotação recusada

Campos da resposta

idinteger
Identificador numérico da cotação (não é UUID).
user_iduuid
Cliente que pediu a cotação.
vendor_iduuid
Seller que responde.
statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpired
pending (pedida), quoted (o seller respondeu com preços), negotiating, accepted, converted (virou carrinho), rejected, expired.
notesstring
Observação do cliente no pedido.
vendor_notesstring
Resposta do seller. Omitido se vazio.
total_centsinteger
Total da cotação, em centavos.
valid_untilstring
Validade da proposta de preços, RFC 3339. Omitido se não definida.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.
user_emailstring
E-mail do cliente.
user_namestring
Nome do cliente.
vendor_namestring
Nome do seller.
itemsarray
Itens pedidos. Só no detalhe.
items[].idinteger
Identificador do item.
items[].quote_idinteger
Cotação.
items[].product_iduuid
Produto.
items[].quantityinteger
Quantidade pedida.
items[].requested_price_centsinteger
Preço unitário que o cliente quer pagar, em centavos. Omitido se não pediu.
items[].offered_price_centsinteger
Preço unitário oferecido pelo seller, em centavos. Omitido antes da resposta.
items[].notesstring
Observação do item.
items[].product_namestring
Nome do produto.
items[].product_skustring
SKU do produto.
items[].product_priceinteger
Preço de tabela do produto, em centavos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"b2b-pricing"} / {"error":"insufficient privileges","required":"manage_b2b"}
400id que não é número, corpo inválido ou status diferente de rejected{"error":"only 'rejected' status is supported via admin update"}
500Cotação inexistente ou já em outro estado que não permite recusar{"error":"failed to reject quote","detail":"quote not found or not in rejectable status"}
Recusar não avisa o cliente por aqui

A rota só muda o estado. Se houver um link de proposta ativo para a cotação, revogue-o em Propostas.

Veja também

  • Propostas formais
  • Negociações
Anterior
Cotações B2B
Próxima
Propostas formais
Nesta página
  • Listar cotações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma cotação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Recusar uma cotação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/quotes?status=quoted" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/quotes/69" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/admin/quotes/69" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "rejected"
  }'
json
{
  "quotes": [
    {
      "id": 69,
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "quoted",
      "notes": "Preciso de 5 unidades para o escritório novo",
      "vendor_notes": "Prazo de entrega de 7 dias",
      "total_cents": 20000,
      "valid_until": "2026-11-10T07:04:19Z",
      "created_at": "2026-10-01T07:01:32Z",
      "updated_at": "2026-10-02T09:00:00Z",
      "user_email": "ana.souza@example.com",
      "user_name": "Ana Souza",
      "vendor_name": "Loja Seller Teste",
      "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 o escritório novo",
  "vendor_notes": "Prazo de entrega de 7 dias",
  "total_cents": 20000,
  "valid_until": "2026-11-10T07:04:19Z",
  "created_at": "2026-10-01T07:01:32Z",
  "updated_at": "2026-10-02T09:00:00Z",
  "user_email": "ana.souza@example.com",
  "user_name": "Ana Souza",
  "vendor_name": "Loja Seller Teste",
  "item_count": 1,
  "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": "rejected",
  "notes": "Preciso de 5 unidades para o escritório novo",
  "vendor_notes": "Prazo de entrega de 7 dias",
  "total_cents": 20000,
  "valid_until": "2026-11-10T07:04:19Z",
  "created_at": "2026-10-01T07:01:32Z",
  "updated_at": "2026-10-02T09:00:00Z",
  "user_email": "ana.souza@example.com",
  "user_name": "Ana Souza",
  "vendor_name": "Loja Seller Teste",
  "item_count": 1,
  "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
    }
  ]
}