API atual/Referência completa/Cotações B2B

Propostas formais

Gera o PDF e o link público de aceite de uma cotação, revoga o link e consulta a trilha de auditoria.

Uma proposta formal transforma uma cotação já respondida (quoted) em um documento que o decisor da empresa compradora pode aprovar sem criar conta: um PDF e um link com chave secreta. Cada ação dele (abrir, comentar, aprovar, recusar) fica registrada com nome, cargo, IP e horário.

Gerar proposta

Gera um PDF da proposta e um link público para o decisor do cliente aprovar ou recusar sem ter conta nem fazer login. A cotação precisa estar quoted. Gerar de novo revoga o link anterior e cria um novo. O cliente recebe o link por e-mail (melhor esforço: se o envio falhar, a proposta já existe e o link volta na resposta).

POST/api/v1/admin/quotes/{id}/proposalAdmin

Gera a proposta formal e o link de aceite

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 -X POST "$BASE_URL/api/v1/admin/quotes/69/proposal" \
  -H "Authorization: Bearer $TOKEN"

Resposta

201Proposta gerada

json

{
  "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "quote_id": 69,
  "token": "k3Jx9fQ2mZpL8vNwTa5RbYcDeHgUs1o7",
  "status": "active",
  "public_url": "https://minhaloja.io.venddor.com.br/quote-proposals/k3Jx9fQ2mZpL8vNwTa5RbYcDeHgUs1o7",
  "expires_at": "2026-11-10T07:04:19Z",
  "created_at": "2026-10-11T21:00:00Z"
}

Campos da resposta

iduuid

Identificador da proposta.

quote_idinteger

Cotação.

tokenstring

Chave secreta do link. Quem a tem pode aprovar ou recusar a proposta: trate como senha.

statusstring

Sempre active ao gerar.

public_urlstring

Endereço público da proposta, a ser enviado ao decisor.

expires_atstring

Quando o link deixa de valer: valid_until da cotação, ou 30 dias depois de gerar se a cotação não tem validade.

created_atstring

Quando foi gerada.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"b2b-pricing"}` / `{"error":"insufficient privileges","required":"manage_b2b"}`
400	`id` inválido ou cotação que não está `quoted`	`{"error":"quote must be quoted to generate a proposal"}`
500	Cotação inexistente ou falha ao gerar o PDF	`{"error":"proposal operation failed","detail":"quote not found"}`

Revogar proposta

Desativa o link público ativo da cotação. Quem abrir o link depois recebe 410. Use quando o link foi enviado à pessoa errada ou a oferta mudou.

DELETE/api/v1/admin/quotes/{id}/proposalAdmin

Revoga o link ativo da proposta

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 -X DELETE "$BASE_URL/api/v1/admin/quotes/69/proposal" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Revogada

json

{
  "revoked": true
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"b2b-pricing"}` / `{"error":"insufficient privileges","required":"manage_b2b"}`
400	`id` que não é número	`{"error":"invalid quote id"}`
404	Não há proposta ativa para a cotação	`{"error":"proposal not found"}`

Trilha de eventos

Lista o que aconteceu com a proposta da cotação, do mais recente ao mais antigo: gerada, aberta, comentada, aprovada ou recusada. A página pública avisa o decisor de que o nome, o cargo, o IP e o horário dele são gravados; é aqui que esse registro aparece.

GET/api/v1/admin/quotes/{id}/proposal/eventsAdmin

Lista a trilha de auditoria da proposta

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/proposal/events" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Eventos devolvidos

json

{
  "events": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "event_type": "approved",
      "actor_name": "Carlos Pereira",
      "actor_role": "Diretor de compras",
      "comment": "",
      "ip": "203.0.113.25",
      "user_agent": "Mozilla/5.0",
      "created_at": "2026-10-12T14:20:00Z"
    },
    {
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "event_type": "regenerated",
      "created_at": "2026-10-11T21:00:00Z"
    }
  ]
}

Campos da resposta

eventsarray

Eventos, do mais recente ao mais antigo. Cobre todas as propostas da cotação.

events[].iduuid

Identificador do evento.

events[].event_typestring

regeneratedviewedcommentedapprovedrejected

regenerated (proposta gerada), viewed (link aberto), commented, approved ou rejected.

events[].actor_namestring

Nome informado por quem agiu. Omitido se vazio.

events[].actor_rolestring

Cargo informado. Omitido se vazio.

events[].commentstring

Comentário. Omitido se vazio.

events[].ipstring

IP de quem agiu. Omitido se vazio.

events[].user_agentstring

Navegador. Omitido se vazio.

events[].created_atstring

Quando ocorreu.

Erros

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

Veja também

API atual/Referência completa/Cotações B2B

Propostas formais

Gera o PDF e o link público de aceite de uma cotação, revoga o link e consulta a trilha de auditoria.

Gerar proposta

POST/api/v1/admin/quotes/{id}/proposalAdmin

Gera a proposta formal e o link de aceite

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 -X POST "$BASE_URL/api/v1/admin/quotes/69/proposal" \
  -H "Authorization: Bearer $TOKEN"

Resposta

201Proposta gerada

json

{
  "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "quote_id": 69,
  "token": "k3Jx9fQ2mZpL8vNwTa5RbYcDeHgUs1o7",
  "status": "active",
  "public_url": "https://minhaloja.io.venddor.com.br/quote-proposals/k3Jx9fQ2mZpL8vNwTa5RbYcDeHgUs1o7",
  "expires_at": "2026-11-10T07:04:19Z",
  "created_at": "2026-10-11T21:00:00Z"
}

Campos da resposta

iduuid

Identificador da proposta.

quote_idinteger

Cotação.

tokenstring

Chave secreta do link. Quem a tem pode aprovar ou recusar a proposta: trate como senha.

statusstring

Sempre active ao gerar.

public_urlstring

Endereço público da proposta, a ser enviado ao decisor.

expires_atstring

Quando o link deixa de valer: valid_until da cotação, ou 30 dias depois de gerar se a cotação não tem validade.

created_atstring

Quando foi gerada.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"b2b-pricing"}` / `{"error":"insufficient privileges","required":"manage_b2b"}`
400	`id` inválido ou cotação que não está `quoted`	`{"error":"quote must be quoted to generate a proposal"}`
500	Cotação inexistente ou falha ao gerar o PDF	`{"error":"proposal operation failed","detail":"quote not found"}`

Revogar proposta

Desativa o link público ativo da cotação. Quem abrir o link depois recebe 410. Use quando o link foi enviado à pessoa errada ou a oferta mudou.

DELETE/api/v1/admin/quotes/{id}/proposalAdmin

Revoga o link ativo da proposta

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 -X DELETE "$BASE_URL/api/v1/admin/quotes/69/proposal" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Revogada

json

{
  "revoked": true
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"b2b-pricing"}` / `{"error":"insufficient privileges","required":"manage_b2b"}`
400	`id` que não é número	`{"error":"invalid quote id"}`
404	Não há proposta ativa para a cotação	`{"error":"proposal not found"}`

Trilha de eventos

GET/api/v1/admin/quotes/{id}/proposal/eventsAdmin

Lista a trilha de auditoria da proposta

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/proposal/events" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Eventos devolvidos

json

{
  "events": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "event_type": "approved",
      "actor_name": "Carlos Pereira",
      "actor_role": "Diretor de compras",
      "comment": "",
      "ip": "203.0.113.25",
      "user_agent": "Mozilla/5.0",
      "created_at": "2026-10-12T14:20:00Z"
    },
    {
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "event_type": "regenerated",
      "created_at": "2026-10-11T21:00:00Z"
    }
  ]
}

Campos da resposta

eventsarray

Eventos, do mais recente ao mais antigo. Cobre todas as propostas da cotação.

events[].iduuid

Identificador do evento.

events[].event_typestring

regeneratedviewedcommentedapprovedrejected

regenerated (proposta gerada), viewed (link aberto), commented, approved ou rejected.

events[].actor_namestring

Nome informado por quem agiu. Omitido se vazio.

events[].actor_rolestring

Cargo informado. Omitido se vazio.

events[].commentstring

Comentário. Omitido se vazio.

events[].ipstring

IP de quem agiu. Omitido se vazio.

events[].user_agentstring

Navegador. Omitido se vazio.

events[].created_atstring

Quando ocorreu.

Erros

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