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

bash
curl "$BASE_URL/api/v1/admin/quotes?status=quoted" \
  -H "Authorization: Bearer $TOKEN"

Resposta

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

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

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

Resposta

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

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

bash
curl -X PUT "$BASE_URL/api/v1/admin/quotes/69" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "rejected"
  }'

Resposta

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

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