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

Ciclo do pedido de compra

Submete, aprova, marca como enviado, recebe (inteiro ou em partes) e cancela um pedido de compra.

Submeter

Tira o pedido de draft. Se o seller definiu um limite de aprovação (veja Configuração) e o total_cents alcança o limite, o pedido vai para pending_approval; caso contrário já fica approved.

POST/api/v1/vendor/erp/compras/orders/{id}/submitSeller

Envia o rascunho para aprovação

Parâmetros de caminho

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

Exemplo de requisição: Submeter

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

Resposta: Submeter

200Aprovado direto (sem limite, ou total abaixo dele)
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": "approved",
  "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
    }
  ]
}
200Aguardando aprovação (total alcançou o limite)
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": "pending_approval",
  "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: Submeter

StatusQuandoCorpo
400O pedido não está em draft.{"error":"cannot submit purchase order in status \"sent\""}
400O pedido não tem linhas.{"error":"vendorerp: cannot submit an empty purchase order"}
404O pedido não existe ou é de outro seller.{"error":"purchase order 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"}

Aprovar

Aprova um pedido em pending_approval e grava quem aprovou e quando. Não existe regra que impeça o próprio criador de aprovar.

POST/api/v1/vendor/erp/compras/orders/{id}/approveSeller

Aprova um pedido pendente

Parâmetros de caminho

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

Exemplo de requisição: Aprovar

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

Resposta: Aprovar

200Pedido atualizado
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": "approved",
  "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: Aprovar

StatusQuandoCorpo
400O pedido não está em pending_approval.{"error":"cannot approve purchase order in status \"draft\""}
404O pedido não existe ou é de outro seller.{"error":"purchase order 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"}

Enviar ao fornecedor

Muda approved para sent. A plataforma só registra o estado: ela não envia e-mail nem integra com o fornecedor. É um pedido enviado por você que se torna recebível.

POST/api/v1/vendor/erp/compras/orders/{id}/sendSeller

Marca o pedido como enviado

Parâmetros de caminho

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

Exemplo de requisição: Enviar ao fornecedor

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

Resposta: Enviar ao fornecedor

200Pedido atualizado
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": "sent",
  "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: Enviar ao fornecedor

StatusQuandoCorpo
400O pedido não está em approved.{"error":"cannot move purchase order from \"draft\" to \"sent\""}
404O pedido não existe ou é de outro seller.{"error":"purchase order 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"}

Receber

Registra a chegada da mercadoria, total ou parcial. Numa única transação a plataforma soma as unidades ao estoque do depósito, atualiza o custo médio ponderado (o custo unitário mais o rateio de frete e despesas) e avança o estado para partially_received ou received. Sem items, recebe todo o saldo pendente de todas as linhas. Receber um pedido não cria conta a pagar; isso acontece ao lançar a NF-e de entrada.

POST/api/v1/vendor/erp/compras/orders/{id}/receiveSeller

Dá entrada no estoque do pedido

Parâmetros de caminho

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

Corpo da requisição

warehouse_iduuidobrigatório
Depósito ativo do seller que recebe as unidades.
itemsarray

Recebimento parcial. Omita para receber tudo que falta.

po_item_iduuidobrigatório
Id da linha do pedido (items[].id).
qtyintegerobrigatório
Unidades que chegaram agora, até o saldo pendente da linha.

Exemplo de requisição: Receber

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/compras/orders/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/receive" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "items": [
    {
      "po_item_id": "f5b504d6-5497-4811-abc8-cccf3e9b79f5",
      "qty": 12
    }
  ]
}'

Resposta: Receber

200Pedido atualizado
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": "received",
  "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: Receber

StatusQuandoCorpo
400warehouse_id ausente.{"error":"vendorerp: warehouse_id required to receive"}
400O depósito está inativo.{"error":"warehouse is inactive"}
400O pedido não está em sent nem partially_received.{"error":"cannot receive purchase order in status \"draft\""}
400O pedido já foi recebido por inteiro.{"error":"purchase order already received"}
400Um item de items sem po_item_id ou com qty <= 0.{"error":"vendorerp: cada item de recebimento precisa de po_item_id e qty > 0"}
400Nenhuma linha tinha saldo a receber.{"error":"vendorerp: nada a receber (itens já recebidos ou quantidade zero)"}
400Um qty pedido é maior que o saldo pendente da linha (qty menos received_qty).{"error":"vendorerp: item 4c1d8a2e-5b7f-4e39-9a60-3f2b1c0d9e11 excede o saldo pendente (5)"}
400Outro recebimento alterou o saldo de uma linha no mesmo instante. Releia a ordem e tente de novo.{"error":"vendorerp: recebimento concorrente alterou o saldo, tente novamente"}
404O depósito não existe ou é de outro seller.{"error":"warehouse not found"}
404O pedido não existe ou é de outro seller.{"error":"purchase order 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 corpo é opcional, o depósito não

A rota ignora um corpo ilegível, mas sem warehouse_id responde 400. Um comentário antigo do código fala em apenas marcar como recebido; hoje o depósito é sempre exigido.

Cancelar

Cancela um pedido em draft, pending_approval, approved, sent ou partially_received. Um pedido received ou já cancelled não pode ser cancelado. O que já foi recebido em estoque não é desfeito.

POST/api/v1/vendor/erp/compras/orders/{id}/cancelSeller

Cancela um pedido

Parâmetros de caminho

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

Exemplo de requisição: Cancelar

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

Resposta: Cancelar

200Pedido atualizado
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": "cancelled",
  "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: Cancelar

StatusQuandoCorpo
400O pedido já foi recebido ou cancelado.{"error":"cannot move purchase order from \"received\" to \"cancelled\""}
404O pedido não existe ou é de outro seller.{"error":"purchase order 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"}
Todas as transições respondem 400 quando o estado é errado

Não existe 409 aqui: uma transição inválida é 400 com a mensagem trazendo o estado atual.

Veja também

  • Pedidos de compra
  • Lançar NF-e de entrada
Anterior
Pedidos de compra
Próxima
Configuração de compras
Nesta página
  • Submeter
  • Exemplo de requisição: Submeter
  • Resposta: Submeter
  • Erros: Submeter
  • Aprovar
  • Exemplo de requisição: Aprovar
  • Resposta: Aprovar
  • Erros: Aprovar
  • Enviar ao fornecedor
  • Exemplo de requisição: Enviar ao fornecedor
  • Resposta: Enviar ao fornecedor
  • Erros: Enviar ao fornecedor
  • Receber
  • Exemplo de requisição: Receber
  • Resposta: Receber
  • Erros: Receber
  • Cancelar
  • Exemplo de requisição: Cancelar
  • Resposta: Cancelar
  • Erros: Cancelar
  • Veja também