VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Compras

Cotações: ofertas e conversão

Registra ofertas de fornecedores, converte a vencedora em pedido de compra, cancela ou apaga a cotação.

Registrar ofertas

Grava uma ou mais ofertas numa cotação aberta. Enviar de novo a oferta do mesmo fornecedor para o mesmo item atualiza o preço em vez de duplicar. Tudo ou nada: se uma oferta for inválida, nenhuma é gravada.

POST/api/v1/vendor/erp/cotacoes/{id}/offersSeller

Registra ofertas de fornecedores

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da cotação.

Corpo da requisição

offersarrayobrigatório

Ofertas. Ao menos uma.

quote_item_iduuidobrigatório
Item da cotação (items[].id).
supplier_iduuidobrigatório
Fornecedor do seller.
unit_cost_centsintegerobrigatório
Preço unitário em centavos, zero ou mais.
lead_time_daysinteger
Prazo de entrega em dias.
notesstring
Observação.

Exemplo de requisição: Registrar ofertas

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/cotacoes/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/offers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "offers": [
    {
      "quote_item_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
      "unit_cost_cents": 4500,
      "lead_time_days": 7,
      "notes": "Frete incluso"
    }
  ]
}'

Resposta: Registrar ofertas

200Cotação com as ofertas
json
{
  "id": "c41a9e07-6f2b-4d83-b0a5-2e7d9f1c3a68",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "COT-000001",
  "status": "open",
  "deadline_at": "2026-10-20T00:00:00Z",
  "notes": "Cotação de outubro",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z",
  "item_count": 1,
  "items": [
    {
      "id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "quote_id": "c41a9e07-6f2b-4d83-b0a5-2e7d9f1c3a68",
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "quantity": 100,
      "offers": [
        {
          "id": "e2b4c6d8-1a3c-4e5f-9b7d-0a2c4e6f8b10",
          "quote_item_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
          "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
          "supplier_name": "Distribuidora Aurora Ltda",
          "unit_cost_cents": 4500,
          "lead_time_days": 7,
          "notes": "Frete incluso",
          "created_at": "2026-10-11T14:30:00Z"
        }
      ]
    }
  ]
}

Campos da resposta

iduuid
Id da cotação.
vendor_iduuid
Seller dono.
codestring
Código legível COT-000001, sequencial por seller.
statusstring
openclosedcancelled
Estado da cotação.
deadline_atdatetime
Prazo para os fornecedores responderem. null se não definido.
notesstring
Observação.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
item_countinteger
Quantidade de itens.
itemsarray

Itens e ofertas. Vazio na listagem.

iduuid
Id do item cotado.
quote_iduuid
Cotação.
product_iduuid
Produto.
product_namestring
Nome do produto.
quantityinteger
Quantidade cotada.
offersarray

Ofertas dos fornecedores, da mais barata para a mais cara.

iduuid
Id da oferta.
quote_item_iduuid
Item cotado.
supplier_iduuid
Fornecedor que ofereceu.
supplier_namestring
Nome do fornecedor.
unit_cost_centsinteger
Preço unitário oferecido, em centavos.
lead_time_daysinteger
Prazo de entrega em dias. null se não informado.
notesstring
Observação.
created_atdatetime
Quando a oferta entrou.

Erros: Registrar ofertas

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400offers vazio.{"error":"vendorerp: at least one offer required"}
400A cotação não está open.{"error":"vendorerp: quote is not open"}
400Oferta sem item ou fornecedor.{"error":"vendorerp: quote_item_id and supplier_id required"}
400Preço negativo.{"error":"vendorerp: unit cost cannot be negative"}
404A cotação, o item ou o fornecedor não existe.{"error":"quote item not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Converter em pedido

Escolhe um fornecedor vencedor e gera um pedido de compra em draft com os preços das ofertas dele. Só entram os itens para os quais esse fornecedor deu oferta; os demais ficam de fora sem aviso. A cotação passa a closed.

POST/api/v1/vendor/erp/cotacoes/{id}/convertSeller

Converte a cotação em pedido de compra

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da cotação.

Corpo da requisição

supplier_iduuidobrigatório
Fornecedor vencedor.

Exemplo de requisição: Converter em pedido

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/cotacoes/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/convert" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12"
}'

Resposta: Converter em pedido

201Pedido de compra gerado
json
{
  "purchase_order_id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
  "total_cents": 450000,
  "item_count": 1
}

Campos da resposta

purchase_order_iduuid
Pedido de compra criado. Consulte em Pedidos de compra.
total_centsinteger
Total do pedido (sem frete).
item_countinteger
Linhas do pedido.

Erros: Converter em pedido

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400supplier_id em branco.{"error":"vendorerp: supplier_id required"}
400A cotação não está open.{"error":"vendorerp: quote is not open"}
400O fornecedor não ofereceu em nenhum item.{"error":"vendorerp: supplier has no offers on this quote"}
404A cotação não existe ou é de outro seller.{"error":"quote not found"}
404O fornecedor não existe ou é de outro seller.{"error":"supplier not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Cancelar cotação

POST/api/v1/vendor/erp/cotacoes/{id}/cancelSeller

Cancela uma cotação aberta

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da cotação.

Exemplo de requisição: Cancelar cotação

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/cotacoes/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Cancelar cotação

200Cotação cancelada
json
{
  "id": "c41a9e07-6f2b-4d83-b0a5-2e7d9f1c3a68",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "COT-000001",
  "status": "cancelled",
  "deadline_at": "2026-10-20T00:00:00Z",
  "notes": "Cotação de outubro",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z",
  "item_count": 1,
  "items": [
    {
      "id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "quote_id": "c41a9e07-6f2b-4d83-b0a5-2e7d9f1c3a68",
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "quantity": 100,
      "offers": [
        {
          "id": "e2b4c6d8-1a3c-4e5f-9b7d-0a2c4e6f8b10",
          "quote_item_id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
          "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
          "supplier_name": "Distribuidora Aurora Ltda",
          "unit_cost_cents": 4500,
          "lead_time_days": 7,
          "notes": "Frete incluso",
          "created_at": "2026-10-11T14:30:00Z"
        }
      ]
    }
  ]
}

Campos da resposta

iduuid
Id da cotação.
vendor_iduuid
Seller dono.
codestring
Código legível COT-000001, sequencial por seller.
statusstring
openclosedcancelled
Estado da cotação.
deadline_atdatetime
Prazo para os fornecedores responderem. null se não definido.
notesstring
Observação.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
item_countinteger
Quantidade de itens.
itemsarray

Itens e ofertas. Vazio na listagem.

iduuid
Id do item cotado.
quote_iduuid
Cotação.
product_iduuid
Produto.
product_namestring
Nome do produto.
quantityinteger
Quantidade cotada.
offersarray

Ofertas dos fornecedores, da mais barata para a mais cara.

iduuid
Id da oferta.
quote_item_iduuid
Item cotado.
supplier_iduuid
Fornecedor que ofereceu.
supplier_namestring
Nome do fornecedor.
unit_cost_centsinteger
Preço unitário oferecido, em centavos.
lead_time_daysinteger
Prazo de entrega em dias. null se não informado.
notesstring
Observação.
created_atdatetime
Quando a oferta entrou.

Erros: Cancelar cotação

StatusQuandoCorpo
400A cotação não está open.{"error":"cannot cancel quote in status \"closed\""}
404A cotação não existe ou é de outro seller.{"error":"quote not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Apagar cotação

Exclusão lógica em qualquer estado. O pedido de compra já gerado a partir dela não é afetado.

DELETE/api/v1/vendor/erp/cotacoes/{id}Seller

Apaga uma cotação

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da cotação.

Exemplo de requisição: Apagar cotação

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/erp/cotacoes/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Apagar cotação

200Cotação apagada
json
{
  "message": "quote deleted"
}

Campos da resposta

messagestring
Sempre quote deleted.

Erros: Apagar cotação

StatusQuandoCorpo
404A cotação não existe ou é de outro seller.{"error":"quote not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Ciclo curto

open leva a closed (ao converter) ou a cancelled. Ofertas só entram enquanto a cotação está open.

Veja também

  • Cotações: consulta e abertura
  • Ciclo do pedido
Anterior
Cotações: consulta e abertura
Próxima
NF-e de entrada: importar e consultar
Nesta página
  • Registrar ofertas
  • Exemplo de requisição: Registrar ofertas
  • Resposta: Registrar ofertas
  • Erros: Registrar ofertas
  • Converter em pedido
  • Exemplo de requisição: Converter em pedido
  • Resposta: Converter em pedido
  • Erros: Converter em pedido
  • Cancelar cotação
  • Exemplo de requisição: Cancelar cotação
  • Resposta: Cancelar cotação
  • Erros: Cancelar cotação
  • Apagar cotação
  • Exemplo de requisição: Apagar cotação
  • Resposta: Apagar cotação
  • Erros: Apagar cotação
  • Veja também