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

Negociações (RFQ)

Acompanha as contrapropostas em rodadas entre cliente e seller e registra a mediação do administrador.

Quando o cliente não aceita o preço da cotação, comprador e seller podem trocar contrapropostas em rodadas (até um máximo, padrão de 5). Cada rodada traz os itens e os preços propostos por um dos lados. O administrador não negocia por eles, mas pode acompanhar o histórico e registrar uma nota quando está mediando.

Listar negociações

Mesma lista de cotações, com os dados da negociação em rodadas: em que rodada está, o máximo de rodadas, se o administrador está mediando e a nota dele.

GET/api/v1/admin/rfq/negotiationsAdmin

Lista as cotações com os dados da negociação

Autenticação: Authorization: Bearer <token> de um administrador com manage_orders. Requer o módulo enhanced-rfq ativo.

Parâmetros de consulta

statusstring
Estado da cotação, palavra ou letra (veja Cotações).
vendor_iduuid
Só as de um seller.
user_iduuid
Só as 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

200Negociações devolvidas

Campos da resposta

quotesarray
Cotações, com todos os campos da lista de cotações mais os abaixo.
quotes[].max_roundsinteger
Máximo de rodadas de contraproposta. Padrão 5.
quotes[].current_roundinteger
Rodada atual. 0 se ainda não houve negociação.
quotes[].negotiation_expires_atstring
Quando a negociação expira. Omitido se não definido.
quotes[].admin_mediatedboolean
Se o administrador marcou a negociação como mediada por ele.
quotes[].admin_notesstring
Nota do administrador. Omitido se vazio.
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":"enhanced-rfq"} / {"error":"insufficient privileges","required":"manage_orders"}
500Falha na consulta{"error":"failed to list negotiations","detail":"..."}
Lista todas as cotações

A lista não se limita às cotações que estão em negociação: traz todas, com current_round igual a 0 nas que nunca foram negociadas. Filtre por status=negotiating para ver só as em curso.

Consultar uma negociação

Devolve a cotação completa, todas as rodadas de contraproposta em ordem e a anotação do administrador.

GET/api/v1/admin/rfq/negotiations/{id}Admin

Consulta a cotação, o histórico de rodadas e a nota

Autenticação: Authorization: Bearer <token> de um administrador com manage_orders. Requer o módulo enhanced-rfq ativo.

Parâmetros de caminho

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

Exemplo de requisição

Resposta

200Negociação devolvida

Campos da resposta

quoteobject
A cotação com items, como em Consultar uma cotação.
history.quote_idinteger
Cotação.
history.max_roundsinteger
Máximo de rodadas.
history.current_roundinteger
Rodada atual.
history.expires_atstring
Quando a negociação expira. Omitido se não definido.
history.roundsarray
Rodadas, da primeira à última.
history.rounds[].iduuid
Identificador da rodada.
history.rounds[].round_numberinteger
Número da rodada, a partir de 1.
history.rounds[].initiated_bystring
customervendoradmin
Quem fez a proposta da rodada: customer, vendor ou admin.
history.rounds[].messagestring
Mensagem da rodada. Omitida se vazia.
history.rounds[].itemsarray
Itens da proposta: product_id, product_name, quantity, price_cents (unitário) e notes.
history.rounds[].total_centsinteger
Total da rodada, em centavos.
history.rounds[].statusstring
pendingacceptedrejectedcounteredexpired
pending, accepted, rejected, countered ou expired.
history.rounds[].created_atstring
Quando a rodada foi aberta.
annotationobject | null
Nota do administrador: notes, admin_mediated e admin_updated_at.

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":"enhanced-rfq"} / {"error":"insufficient privileges","required":"manage_orders"}
400id que não é número{"error":"invalid quote id"}
404Cotação inexistente{"error":"quote not found"}

Anotar uma negociação

O administrador registra uma nota interna sobre a negociação e, se quiser, marca que está mediando. Não altera preços, rodadas nem o estado da cotação: é só anotação.

PATCH/api/v1/admin/rfq/negotiations/{id}Admin

Grava a nota do administrador e a marca de mediação

Autenticação: Authorization: Bearer <token> de um administrador com manage_orders. Requer o módulo enhanced-rfq ativo.

Parâmetros de caminho

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

Corpo da requisição

notesstring
Texto da nota. Substitui a anterior; envie vazio para limpar.
admin_mediatedboolean
Marca a mediação. Se omitido, o valor atual é mantido.

Exemplo de requisição

Resposta

200Nota gravada

Campos da resposta

notesstring
Nota gravada.
admin_mediatedboolean
Marca de mediação.
admin_updated_atstring
Quando a nota foi gravada.

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":"enhanced-rfq"} / {"error":"insufficient privileges","required":"manage_orders"}
400id que não é número ou corpo inválido{"error":"invalid quote id"}
500Falha ao gravar{"error":"failed to annotate quote","detail":"..."}
Cotação inexistente responde `200 null`

Para um id que não existe, nada é gravado e a resposta é 200 com o corpo null. Confira a cotação antes com a rota de consulta.

Veja também

  • Cotações
  • Propostas formais
Anterior
Propostas formais
Próxima
Vales-presente
Nesta página
  • Listar negociações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma negociação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Anotar uma negociação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/rfq/negotiations?status=negotiating" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/rfq/negotiations/69" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PATCH "$BASE_URL/api/v1/admin/rfq/negotiations/69" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Cliente pediu 8% de desconto; seller topou 5%",
    "admin_mediated": true
  }'
json
{
  "quotes": [
    {
      "id": 69,
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "negotiating",
      "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,
      "max_rounds": 5,
      "current_round": 1,
      "admin_mediated": false
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
json
{
  "quote": {
    "id": 69,
    "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "status": "negotiating",
    "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
      }
    ]
  },
  "history": {
    "quote_id": 69,
    "max_rounds": 5,
    "current_round": 1,
    "rounds": [
      {
        "id": "08199264-d0cf-4eb9-a26d-7216f7c450ba",
        "quote_id": 69,
        "round_number": 1,
        "initiated_by": "customer",
        "items": [
          {
            "product_id": "c7bc3778-2c79-4561-b9d7-979768f364c8",
            "product_name": "Notebook Plus Rosa",
            "quantity": 5,
            "price_cents": 4000
          }
        ],
        "total_cents": 20000,
        "status": "pending",
        "created_at": "2026-10-01T07:19:03Z"
      }
    ]
  },
  "annotation": {
    "notes": "",
    "admin_mediated": true,
    "admin_updated_at": "2026-10-02T08:15:18Z"
  }
}
json
{
  "notes": "Cliente pediu 8% de desconto; seller topou 5%",
  "admin_mediated": true,
  "admin_updated_at": "2026-10-11T21:40:00Z"
}