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

Pedir e consultar cotações

Cria uma cotação, lista as do cliente e consulta o detalhe.

Três rotas para o começo do fluxo: pedir a cotação a um seller, listar as que o cliente já abriu e consultar uma. Todas exigem o token do cliente e o módulo b2b-pricing ligado na loja.

Pedir cotação

Abre uma cotação (RFQ, request for quotation): o cliente escolhe um seller e uma lista de produtos desse seller e pede um preço especial. A cotação nasce em pending; o seller responde pelo painel dele e ela passa a quoted. Nada é cobrado nem reservado em estoque nesta etapa.

POST/api/v1/storefront/quotesCliente

Pede a um seller o preço de uma lista de produtos

Corpo da requisição

vendor_iduuidobrigatório
Seller que vai responder. Todos os produtos precisam ser dele.
notesstring
Observação livre para o seller.
itemsarrayobrigatório

Pelo menos um item.

product_iduuidobrigatório
Produto do seller, ativo e não excluído.
quantityintegerpadrão: 1
Quantidade. Valor menor que 1 é trocado por 1 em silêncio.
requested_price_centsinteger
Preço unitário que o cliente gostaria de pagar, em centavos. Opcional; é só uma sugestão ao seller.
notesstring
Observação da linha.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/quotes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
    "notes": "Preciso de entrega mensal",
    "items": [
      {
        "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
        "quantity": 200,
        "requested_price_cents": 1800
      }
    ]
  }'

Resposta

201Cotação criada
json
{
  "id": 42,
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
  "status": "pending",
  "notes": "Preciso de entrega mensal",
  "total_cents": 0,
  "created_at": "2026-10-11T14:02:11Z",
  "updated_at": "2026-10-11T14:02:11Z",
  "user_email": "maria.souza@example.com",
  "user_name": "Maria Souza",
  "vendor_name": "Distribuidora Aurora",
  "items": [
    {
      "id": 101,
      "quote_id": 42,
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 200,
      "requested_price_cents": 1800,
      "notes": "",
      "product_name": "Caneta esferográfica azul (cx 50)",
      "product_sku": "CAN-AZ-50",
      "product_price": 2490
    }
  ]
}

Campos da resposta

idinteger
Id numérico da cotação (não é UUID).
user_iduuid
Cliente que pediu a cotação.
vendor_iduuid
Seller (lojista) que responde.
statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpired
Estado atual. Veja o ciclo na página inicial da seção.
notesstring
Observação do cliente ao pedir.
vendor_notesstring
Observação do seller ao responder. Ausente enquanto não houver.
total_centsinteger
Total em centavos. É 0 até o seller responder e passa a refletir os preços oferecidos (ou a última rodada de negociação).
valid_untilstring
Data-limite (RFC 3339) para aceitar. Ausente quando o seller não definiu.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
user_emailstring
E-mail do cliente.
user_namestring
Nome do cliente.
vendor_namestring
Razão social do seller.
itemsarray

Itens da cotação (presente no detalhe e na criação).

idinteger
Id da linha.
product_iduuid
Produto.
quantityinteger
Quantidade pedida.
requested_price_centsinteger
Preço unitário que o cliente sugeriu, em centavos. Ausente se não sugeriu.
offered_price_centsinteger
Preço unitário oferecido pelo seller, em centavos. Ausente até a resposta.
notesstring
Observação da linha.
product_namestring
Nome do produto.
product_skustring
SKU.
product_priceinteger
Preço de tabela hoje, em centavos.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido ou lista de itens vazia.{"error":"at least one item is required"}
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
500vendor_id ausente, seller inexistente ou produto que não é do seller. A validação sai como 500 (veja o aviso).{"error":"failed to create quote","detail":"vendor_id is required"}
Validação volta como 500

Erros que são do chamador (vendor_id is required, vendor not found, product <id> not found or does not belong to vendor) chegam como HTTP 500 com a causa em detail. Trate 500 com detail como erro de validação nesta rota.

Listar minhas cotações

Devolve só as cotações do cliente dono do token, da mais nova para a mais antiga, com paginação. Cotações vencidas (valid_until no passado) são marcadas como expired no momento da leitura.

GET/api/v1/storefront/quotesCliente

Lista as cotações do cliente logado

Parâmetros de consulta

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.
statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpiredall
Filtra por estado. Aceita o nome por extenso ou a letra interna. Vazio ou all não filtra.

Exemplo de requisição

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

Resposta

200Página de cotações
json
{
  "quotes": [
    {
      "id": 42,
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
      "status": "quoted",
      "notes": "Preciso de entrega mensal",
      "total_cents": 420000,
      "created_at": "2026-10-11T14:02:11Z",
      "updated_at": "2026-10-11T14:02:11Z",
      "user_email": "maria.souza@example.com",
      "user_name": "Maria Souza",
      "vendor_name": "Distribuidora Aurora",
      "vendor_notes": "Preço válido para pedido único.",
      "valid_until": "2026-10-25T23:59:59Z",
      "item_count": 1
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

quotesarray
Cotações da página, no formato da criação. A lista traz item_count e não traz items; busque o detalhe para ver as linhas.
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
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Consultar cotação

Devolve a cotação inteira, com os itens e os preços oferecidos pelo seller. É a chamada para exibir a tela "Minha cotação" e para decidir se o botão Aceitar deve aparecer (status igual a quoted e valid_until no futuro).

GET/api/v1/storefront/quotes/{id}Cliente

Detalhe de uma cotação com os itens

Parâmetros de caminho

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

Exemplo de requisição

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

Resposta

200Cotação respondida pelo seller
json
{
  "id": 42,
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
  "status": "quoted",
  "notes": "Preciso de entrega mensal",
  "total_cents": 420000,
  "created_at": "2026-10-11T14:02:11Z",
  "updated_at": "2026-10-11T14:02:11Z",
  "user_email": "maria.souza@example.com",
  "user_name": "Maria Souza",
  "vendor_name": "Distribuidora Aurora",
  "items": [
    {
      "id": 101,
      "quote_id": 42,
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 200,
      "requested_price_cents": 1800,
      "notes": "",
      "product_name": "Caneta esferográfica azul (cx 50)",
      "product_sku": "CAN-AZ-50",
      "product_price": 2490,
      "offered_price_cents": 2100
    }
  ],
  "vendor_notes": "Preço válido para pedido único.",
  "valid_until": "2026-10-25T23:59:59Z"
}

Campos da resposta

idinteger
Id numérico da cotação (não é UUID).
user_iduuid
Cliente que pediu a cotação.
vendor_iduuid
Seller (lojista) que responde.
statusstring
pendingquotednegotiatingacceptedconvertedrejectedexpired
Estado atual. Veja o ciclo na página inicial da seção.
notesstring
Observação do cliente ao pedir.
vendor_notesstring
Observação do seller ao responder. Ausente enquanto não houver.
total_centsinteger
Total em centavos. É 0 até o seller responder e passa a refletir os preços oferecidos (ou a última rodada de negociação).
valid_untilstring
Data-limite (RFC 3339) para aceitar. Ausente quando o seller não definiu.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
user_emailstring
E-mail do cliente.
user_namestring
Nome do cliente.
vendor_namestring
Razão social do seller.
itemsarray

Itens da cotação (presente no detalhe e na criação).

idinteger
Id da linha.
product_iduuid
Produto.
quantityinteger
Quantidade pedida.
requested_price_centsinteger
Preço unitário que o cliente sugeriu, em centavos. Ausente se não sugeriu.
offered_price_centsinteger
Preço unitário oferecido pelo seller, em centavos. Ausente até a resposta.
notesstring
Observação da linha.
product_namestring
Nome do produto.
product_skustring
SKU.
product_priceinteger
Preço de tabela hoje, em centavos.

Erros

StatusQuandoCorpo de exemplo
400O id não é um número.{"error":"invalid quote id"}
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403A cotação é de outro cliente.{"error":"quote does not belong to this user"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
404Cotação inexistente.{"error":"quote not found"}
Ids de cotação são inteiros

Diferente de pedidos e produtos, a cotação usa um id numérico (42). Guarde-o como número; enviar um UUID devolve invalid quote id.

Veja também

  • Aceitar, recusar e levar ao carrinho
  • Negociação em rodadas
  • Ids, dinheiro e datas
Anterior
Cotações e propostas B2B
Próxima
Decidir uma cotação
Nesta página
  • Pedir cotação
  • Listar minhas cotações
  • Consultar cotação
  • Veja também