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

Pedidos de compra

Lista, consulta e cria pedidos de compra enviados aos fornecedores do seller.

Listar pedidos de compra

Um pedido de compra (OC, purchase order) é a ordem enviada a um fornecedor com o que o seller quer comprar. A listagem traz o cabeçalho e item_count, do mais novo para o mais antigo.

GET/api/v1/vendor/erp/compras/ordersSeller

Lista os pedidos de compra

Parâmetros de consulta

statusstring
draftpending_approvalapprovedsentpartially_receivedreceivedcancelled
Estado do pedido. Valor desconhecido devolve lista vazia.
supplier_iduuid
Só pedidos deste fornecedor.
pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar pedidos de compra

bash
curl "$BASE_URL/api/v1/vendor/erp/compras/orders?status=sent" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar pedidos de compra

200Pedidos retornados
json
{
  "orders": [
    {
      "id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
      "supplier_name": "Distribuidora Aurora Ltda",
      "status": "draft",
      "subtotal_cents": 99800,
      "freight_cents": 5000,
      "other_costs_cents": 0,
      "total_cents": 104800,
      "notes": "Reposição de outubro",
      "item_count": 1,
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

ordersarray

Pedidos da página (sem items).

iduuid
Id do pedido de compra.
vendor_iduuid
Seller dono.
supplier_iduuid
Fornecedor.
supplier_namestring
Nome do fornecedor.
statusstring
draftpending_approvalapprovedsentpartially_receivedreceivedcancelled
Estado do pedido.
subtotal_centsinteger
Soma das linhas.
freight_centsinteger
Frete, rateado no custo dos itens ao receber.
other_costs_centsinteger
Outras despesas acessórias, também rateadas.
total_centsinteger
Subtotal + frete + outras despesas.
notesstring
Observação.
item_countinteger
Quantidade de linhas.
created_byuuid
Quem criou. Ausente se não houve usuário.
approved_byuuid
Quem aprovou. Ausente até a aprovação manual.
approved_atdatetime
Quando foi aprovada manualmente. Ausente se não foi.
received_atdatetime
Quando foi totalmente recebida. Ausente antes disso.
created_atdatetime
Criação.
itemsarray

Linhas. Só aparece no detalhe e nas ações; a listagem não traz.

iduuid
Id da linha.
po_iduuid
Pedido a que pertence.
product_iduuid
Produto.
product_namestring
Nome do produto.
qtyinteger
Quantidade pedida.
received_qtyinteger
Quantidade já recebida (acumulado).
unit_cost_centsinteger
Custo unitário combinado, em centavos.
line_centsinteger
qty vezes unit_cost_cents.
totalinteger
Total que atende ao filtro.

Erros: Listar pedidos de compra

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list purchase orders","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
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"}

Consultar pedido de compra

GET/api/v1/vendor/erp/compras/orders/{id}Seller

Consulta um pedido de compra

Parâmetros de caminho

iduuidobrigatório
Id (UUID) do pedido de compra.

Exemplo de requisição: Consultar pedido de compra

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

Resposta: Consultar pedido de compra

200Pedido com linhas
json
{
  "id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "supplier_name": "Distribuidora Aurora Ltda",
  "status": "draft",
  "subtotal_cents": 99800,
  "freight_cents": 5000,
  "other_costs_cents": 0,
  "total_cents": 104800,
  "notes": "Reposição de outubro",
  "item_count": 1,
  "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "created_at": "2026-10-11T14:30:00Z",
  "items": [
    {
      "id": "f5b504d6-5497-4811-abc8-cccf3e9b79f5",
      "po_id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "qty": 20,
      "received_qty": 0,
      "unit_cost_cents": 4990,
      "line_cents": 99800
    }
  ]
}

Campos da resposta

iduuid
Id do pedido de compra.
vendor_iduuid
Seller dono.
supplier_iduuid
Fornecedor.
supplier_namestring
Nome do fornecedor.
statusstring
draftpending_approvalapprovedsentpartially_receivedreceivedcancelled
Estado do pedido.
subtotal_centsinteger
Soma das linhas.
freight_centsinteger
Frete, rateado no custo dos itens ao receber.
other_costs_centsinteger
Outras despesas acessórias, também rateadas.
total_centsinteger
Subtotal + frete + outras despesas.
notesstring
Observação.
item_countinteger
Quantidade de linhas.
created_byuuid
Quem criou. Ausente se não houve usuário.
approved_byuuid
Quem aprovou. Ausente até a aprovação manual.
approved_atdatetime
Quando foi aprovada manualmente. Ausente se não foi.
received_atdatetime
Quando foi totalmente recebida. Ausente antes disso.
created_atdatetime
Criação.
itemsarray

Linhas. Só aparece no detalhe e nas ações; a listagem não traz.

iduuid
Id da linha.
po_iduuid
Pedido a que pertence.
product_iduuid
Produto.
product_namestring
Nome do produto.
qtyinteger
Quantidade pedida.
received_qtyinteger
Quantidade já recebida (acumulado).
unit_cost_centsinteger
Custo unitário combinado, em centavos.
line_centsinteger
qty vezes unit_cost_cents.

Erros: Consultar pedido de compra

StatusQuandoCorpo
404O pedido não existe ou é de outro seller.{"error":"purchase order not found"}
500O id não é um UUID válido.{"error":"failed to get purchase order","detail":"o valor \"abc\" não é um uuid válido. ..."}
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"}

Criar pedido de compra

Cria o pedido em estado draft com as linhas informadas. Ele ainda não é enviado ao fornecedor: percorra o ciclo em Ciclo do pedido. Criar o pedido também registra o custo de cada produto como o último preço negociado com aquele fornecedor.

POST/api/v1/vendor/erp/compras/ordersSeller

Cria um pedido de compra

Corpo da requisição

supplier_iduuidobrigatório
Fornecedor do seller.
notesstring
Observação.
freight_centsinteger
Frete em centavos, zero ou mais. Padrão 0.
other_costs_centsinteger
Outras despesas em centavos, zero ou mais. Padrão 0.
itemsarrayobrigatório

Linhas do pedido. Linhas com product_id em branco são descartadas em silêncio; precisa sobrar ao menos uma.

product_iduuidobrigatório
Produto.
qtyintegerobrigatório
Quantidade, maior que zero.
unit_cost_centsintegerobrigatório
Custo unitário em centavos, maior que zero.

Exemplo de requisição: Criar pedido de compra

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/compras/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "notes": "Reposição de outubro",
  "freight_cents": 5000,
  "items": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "qty": 20,
      "unit_cost_cents": 4990
    }
  ]
}'

Resposta: Criar pedido de compra

201Pedido criado em rascunho
json
{
  "id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "supplier_id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "supplier_name": "Distribuidora Aurora Ltda",
  "status": "draft",
  "subtotal_cents": 99800,
  "freight_cents": 5000,
  "other_costs_cents": 0,
  "total_cents": 104800,
  "notes": "Reposição de outubro",
  "item_count": 1,
  "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "created_at": "2026-10-11T14:30:00Z",
  "items": [
    {
      "id": "f5b504d6-5497-4811-abc8-cccf3e9b79f5",
      "po_id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "qty": 20,
      "received_qty": 0,
      "unit_cost_cents": 4990,
      "line_cents": 99800
    }
  ]
}

Campos da resposta

iduuid
Id do pedido de compra.
vendor_iduuid
Seller dono.
supplier_iduuid
Fornecedor.
supplier_namestring
Nome do fornecedor.
statusstring
draftpending_approvalapprovedsentpartially_receivedreceivedcancelled
Estado do pedido.
subtotal_centsinteger
Soma das linhas.
freight_centsinteger
Frete, rateado no custo dos itens ao receber.
other_costs_centsinteger
Outras despesas acessórias, também rateadas.
total_centsinteger
Subtotal + frete + outras despesas.
notesstring
Observação.
item_countinteger
Quantidade de linhas.
created_byuuid
Quem criou. Ausente se não houve usuário.
approved_byuuid
Quem aprovou. Ausente até a aprovação manual.
approved_atdatetime
Quando foi aprovada manualmente. Ausente se não foi.
received_atdatetime
Quando foi totalmente recebida. Ausente antes disso.
created_atdatetime
Criação.
itemsarray

Linhas. Só aparece no detalhe e nas ações; a listagem não traz.

iduuid
Id da linha.
po_iduuid
Pedido a que pertence.
product_iduuid
Produto.
product_namestring
Nome do produto.
qtyinteger
Quantidade pedida.
received_qtyinteger
Quantidade já recebida (acumulado).
unit_cost_centsinteger
Custo unitário combinado, em centavos.
line_centsinteger
qty vezes unit_cost_cents.

Erros: Criar pedido de compra

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"}
400Frete ou outras despesas negativos.{"error":"vendorerp: freight/other costs must be >= 0"}
400Alguma linha com qty <= 0.{"error":"vendorerp: item qty must be positive"}
400Alguma linha com unit_cost_cents <= 0.{"error":"vendorerp: unit cost must be greater than zero"}
400Nenhuma linha válida.{"error":"vendorerp: at least one item required"}
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"}
O produto não é conferido

A criação confere o fornecedor, mas não confere se product_id existe nem se é do seller. Um id inválido pode falhar com um erro genérico de banco; um id de produto de outro dono é aceito.

Veja também

  • Ciclo do pedido
  • Fornecedores
  • Configuração de aprovação
Anterior
Fornecedores
Próxima
Ciclo do pedido de compra
Nesta página
  • Listar pedidos de compra
  • Exemplo de requisição: Listar pedidos de compra
  • Resposta: Listar pedidos de compra
  • Erros: Listar pedidos de compra
  • Consultar pedido de compra
  • Exemplo de requisição: Consultar pedido de compra
  • Resposta: Consultar pedido de compra
  • Erros: Consultar pedido de compra
  • Criar pedido de compra
  • Exemplo de requisição: Criar pedido de compra
  • Resposta: Criar pedido de compra
  • Erros: Criar pedido de compra
  • Veja também