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

Fornecedores

Cadastra e mantém os fornecedores do seller e consulta o último preço de cada produto com cada um.

Listar fornecedores

Um fornecedor é quem vende mercadoria ao seller. Os fornecedores alimentam pedidos de compra, cotações e contas a pagar. A lista vem com os ativos primeiro e depois por nome, sem paginação.

GET/api/v1/vendor/erp/compras/suppliersSeller

Lista os fornecedores

Exemplo de requisição: Listar fornecedores

bash
curl "$BASE_URL/api/v1/vendor/erp/compras/suppliers" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar fornecedores

200Fornecedores retornados
json
{
  "suppliers": [
    {
      "id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Distribuidora Aurora Ltda",
      "cnpj": "11222333000181",
      "email": "compras@aurora.example.com",
      "phone": "(11) 4000-1234",
      "active": true,
      "payment_terms_days": 28,
      "lead_time_days": 5,
      "min_order_cents": 50000,
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

suppliersarray

Fornecedores.

iduuid
Id do fornecedor.
vendor_iduuid
Seller dono.
namestring
Razão social ou nome.
cnpjstring
CNPJ como foi enviado. Vazio se não informado.
emailstring
E-mail de contato. Vazio se não informado.
phonestring
Telefone. Vazio se não informado.
activeboolean
Se o fornecedor está ativo.
payment_terms_daysinteger
Prazo de pagamento em dias, usado para calcular o vencimento das contas a pagar geradas por NF-e.
lead_time_daysinteger
Prazo estimado de entrega em dias.
min_order_centsinteger
Pedido mínimo, em centavos. Informativo: a API não bloqueia pedidos abaixo dele.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
totalinteger
Quantidade devolvida.

Erros: Listar fornecedores

StatusQuandoCorpo
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 fornecedor

POST/api/v1/vendor/erp/compras/suppliersSeller

Cria um fornecedor

Corpo da requisição

namestringobrigatório
Nome do fornecedor. Obrigatório.
cnpjstring
CNPJ. Se enviado, os dígitos verificadores são conferidos; com ou sem máscara.
emailstring
E-mail de contato.
phonestring
Telefone.
activebooleanpadrão: true
Se está ativo.
payment_terms_daysinteger
Prazo de pagamento em dias. Negativo vira 0. Na alteração, omitir mantém o valor atual.
lead_time_daysinteger
Prazo de entrega em dias. Negativo vira 0. Na alteração, omitir mantém o atual.
min_order_centsinteger
Pedido mínimo em centavos. Negativo vira 0. Na alteração, omitir mantém o atual.

Exemplo de requisição: Criar fornecedor

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/compras/suppliers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Distribuidora Aurora Ltda",
  "cnpj": "11.222.333/0001-81",
  "email": "compras@aurora.example.com",
  "phone": "(11) 4000-1234",
  "payment_terms_days": 28,
  "lead_time_days": 5,
  "min_order_cents": 50000
}'

Resposta: Criar fornecedor

201Fornecedor criado
json
{
  "id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Distribuidora Aurora Ltda",
  "cnpj": "11222333000181",
  "email": "compras@aurora.example.com",
  "phone": "(11) 4000-1234",
  "active": true,
  "payment_terms_days": 28,
  "lead_time_days": 5,
  "min_order_cents": 50000,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id do fornecedor.
vendor_iduuid
Seller dono.
namestring
Razão social ou nome.
cnpjstring
CNPJ como foi enviado. Vazio se não informado.
emailstring
E-mail de contato. Vazio se não informado.
phonestring
Telefone. Vazio se não informado.
activeboolean
Se o fornecedor está ativo.
payment_terms_daysinteger
Prazo de pagamento em dias, usado para calcular o vencimento das contas a pagar geradas por NF-e.
lead_time_daysinteger
Prazo estimado de entrega em dias.
min_order_centsinteger
Pedido mínimo, em centavos. Informativo: a API não bloqueia pedidos abaixo dele.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Criar fornecedor

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400name em branco.{"error":"vendorerp: name required"}
400CNPJ com dígitos verificadores inválidos.{"error":"cnpj invá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"}

Alterar fornecedor

Substitui nome, CNPJ, e-mail, telefone e active. Os três números (payment_terms_days, lead_time_days, min_order_cents) só mudam se vierem no corpo.

PUT/api/v1/vendor/erp/compras/suppliers/{id}Seller

Altera um fornecedor

Parâmetros de caminho

iduuidobrigatório
Id (UUID) do fornecedor.

Corpo da requisição

namestringobrigatório
Nome do fornecedor. Obrigatório.
cnpjstring
CNPJ. Se enviado, os dígitos verificadores são conferidos; com ou sem máscara.
emailstring
E-mail de contato.
phonestring
Telefone.
activebooleanpadrão: true
Se está ativo.
payment_terms_daysinteger
Prazo de pagamento em dias. Negativo vira 0. Na alteração, omitir mantém o valor atual.
lead_time_daysinteger
Prazo de entrega em dias. Negativo vira 0. Na alteração, omitir mantém o atual.
min_order_centsinteger
Pedido mínimo em centavos. Negativo vira 0. Na alteração, omitir mantém o atual.

Exemplo de requisição: Alterar fornecedor

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/compras/suppliers/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Distribuidora Aurora Ltda",
  "cnpj": "11.222.333/0001-81",
  "email": "compras@aurora.example.com",
  "phone": "(11) 4000-1234",
  "payment_terms_days": 28,
  "lead_time_days": 5,
  "min_order_cents": 50000,
  "active": true
}'

Resposta: Alterar fornecedor

200Fornecedor alterado
json
{
  "id": "e3d204f2-582c-4b7e-bac0-f46214d52c12",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Distribuidora Aurora Ltda",
  "cnpj": "11222333000181",
  "email": "compras@aurora.example.com",
  "phone": "(11) 4000-1234",
  "active": true,
  "payment_terms_days": 28,
  "lead_time_days": 5,
  "min_order_cents": 50000,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id do fornecedor.
vendor_iduuid
Seller dono.
namestring
Razão social ou nome.
cnpjstring
CNPJ como foi enviado. Vazio se não informado.
emailstring
E-mail de contato. Vazio se não informado.
phonestring
Telefone. Vazio se não informado.
activeboolean
Se o fornecedor está ativo.
payment_terms_daysinteger
Prazo de pagamento em dias, usado para calcular o vencimento das contas a pagar geradas por NF-e.
lead_time_daysinteger
Prazo estimado de entrega em dias.
min_order_centsinteger
Pedido mínimo, em centavos. Informativo: a API não bloqueia pedidos abaixo dele.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Alterar fornecedor

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400name em branco.{"error":"vendorerp: name required"}
400CNPJ com dígitos verificadores inválidos.{"error":"cnpj inválido"}
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"}
Texto omitido é apagado; active omitido reativa

cnpj, email e phone que você não enviar ficam vazios, e active volta a true. Mande o registro completo.

Apagar fornecedor

Exclusão lógica. Pedidos de compra antigos continuam mostrando o nome do fornecedor apagado.

DELETE/api/v1/vendor/erp/compras/suppliers/{id}Seller

Apaga um fornecedor

Parâmetros de caminho

iduuidobrigatório
Id (UUID) do fornecedor.

Exemplo de requisição: Apagar fornecedor

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

Resposta: Apagar fornecedor

200Fornecedor apagado
json
{
  "message": "supplier deleted"
}

Campos da resposta

messagestring
Sempre supplier deleted.

Erros: Apagar fornecedor

StatusQuandoCorpo
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"}

Preços do fornecedor

Devolve, por produto, o último custo negociado com o fornecedor. A plataforma aprende esse preço sozinha a cada pedido de compra criado e a cada NF-e lançada; use para pré-preencher o próximo pedido.

GET/api/v1/vendor/erp/compras/suppliers/{id}/pricesSeller

Histórico de preços de um fornecedor

Parâmetros de caminho

iduuidobrigatório
Id (UUID) do fornecedor.

Exemplo de requisição: Preços do fornecedor

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

Resposta: Preços do fornecedor

200Preços retornados
json
{
  "prices": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "sku": "CAM-PRE-M",
      "last_cost_cents": 4990,
      "last_qty": 20,
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

pricesarray

Um item por produto.

product_iduuid
Produto.
product_namestring
Nome do produto.
skustring
SKU do produto.
last_cost_centsinteger
Último custo unitário, em centavos.
last_qtyinteger
Quantidade dessa última compra.
updated_atdatetime
Quando o preço foi aprendido.
totalinteger
Quantidade devolvida.

Erros: Preços do fornecedor

StatusQuandoCorpo
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"}

Veja também

  • Pedidos de compra
  • Cotações
Anterior
ERP de compras do seller
Próxima
Pedidos de compra
Nesta página
  • Listar fornecedores
  • Exemplo de requisição: Listar fornecedores
  • Resposta: Listar fornecedores
  • Erros: Listar fornecedores
  • Criar fornecedor
  • Exemplo de requisição: Criar fornecedor
  • Resposta: Criar fornecedor
  • Erros: Criar fornecedor
  • Alterar fornecedor
  • Exemplo de requisição: Alterar fornecedor
  • Resposta: Alterar fornecedor
  • Erros: Alterar fornecedor
  • Apagar fornecedor
  • Exemplo de requisição: Apagar fornecedor
  • Resposta: Apagar fornecedor
  • Erros: Apagar fornecedor
  • Preços do fornecedor
  • Exemplo de requisição: Preços do fornecedor
  • Resposta: Preços do fornecedor
  • Erros: Preços do fornecedor
  • Veja também